docs/architecture.md

Architecture

Current System

Browser UI
  -> FastAPI meeting/session routes
  -> local meeting JSON storage
  -> faster-whisper transcription
  -> OpenRouter transcript correction
  -> OpenRouter MoM generation
  -> Markdown persistence
  -> optional Hugging Face Dataset sync

Current UI metadata collected before transcription:

• meeting title
• meeting code
• participant/device label
• meeting type
• recording mode
• known terms
• meeting context

Room-recording processing safeguards:

• upload size limit
• audio metadata inspection
• serialized Whisper transcription on CPU
• merge-safe segment upserts for simultaneous participant submissions
• original-audio persistence before transcription
• atomic local metadata writes and locked segment upserts
• Dataset metadata restore after Space rebuild
• lazy original-audio and Markdown restore on host download

Implemented Modules

• app.py - FastAPI routes and page rendering
• config.py - environment and path configuration
• models.py - typed meeting/session structures
• storage.py - local persistence and optional Dataset sync
• transcription.py - Whisper loading and transcription
• llm.py - OpenRouter transcript correction and MoM generation
• markdown.py - transcript Markdown rendering

Target System

Browser UI
  -> FastAPI meeting/session routes
  -> local meeting storage
  -> Whisper raw transcript
  -> LLM transcript correction
  -> LLM MoM generation
  -> Markdown persistence
  -> Hugging Face Dataset persistence

Meeting Data Shape

{
  "meeting_id": "client-sync-2026-06-08",
  "title": "Client Sync",
  "context": "Discuss launch blockers",
  "meeting_type": "hybrid",
  "participants": [
    {
      "name": "Prashanth",
      "recording_mode": "room_recorder"
    }
  ],
  "segments": [
    {
      "segment_id": "seg-001",
      "label": "Conference Room",
      "recording_mode": "room_recorder",
      "covered_participants": ["Prashanth", "Asha", "Rahul"],
      "created_at": "2026-06-08T10:30:00Z",
      "raw_transcript": "...",
      "corrected_transcript": "..."
    }
  ]
}

Markdown Outputs

meetings/
  meeting-id/
    metadata.json
    recordings/
      segment-id.aac
    raw_transcript.md
    corrected_transcript.md
    minutes.md

On Hugging Face Spaces, local disk is not durable by default. Production persistence should use a Hugging Face Dataset repo or another external storage backend.

Route Plan

POST /api/meetings
GET  /api/meetings/{meeting_id}
GET  /api/meetings/{meeting_id}/host
POST /api/meetings/{meeting_id}/segments
POST /api/meetings/{meeting_id}/generate
GET  /api/meetings/{meeting_id}/downloads/{file_name}

These routes are implemented.