docs/architecture.md

# Architecture

## Current System

```text
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

```text
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

```json
{
  "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

```text
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

```text
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.