> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Chunked Upload Flow

> Sequence diagram: how audio chunks are uploaded, transcribed, and stitched.

# Chunked Upload Flow

This document describes the sequence of operations when a user uploads audio in chunks to a session.

```mermaid theme={null}
sequenceDiagram
    participant Frontend
    participant API
    participant DB
    participant Redis
    participant Worker

    Frontend->>API: POST /sessions (create session)
    API->>DB: Insert into sessions
    DB-->>API: session_id
    API-->>Frontend: session_id

    loop For each chunk (live feedback)
        Frontend->>API: POST /sessions/{id}/chunks (seq=1,2,3)
        API->>DB: Insert into audio_chunks (chunk_id)
        API->>DB: Insert into transcriptions<br/>(audio_id=NULL, audio_chunk_id=chunk_id)
        API->>DB: Insert into transcription_jobs
        API->>Redis: Push transcription job
        API-->>Frontend: job_id (live updates)

        Worker->>Redis: Pull transcription job
        Worker->>Worker: Transcribe chunk
        Worker->>DB: Update transcriptions (text, completed_at)
    end

    Frontend->>API: POST /sessions/{id}/finalize
    API->>DB: Query all audio_chunks
    API->>API: Stitch audio files
    API->>DB: Insert into audios (stitched_audio_id)
    API->>DB: Update audio_chunks.parent_audio_id
    API->>DB: Insert into transcriptions<br/>(audio_id=stitched_audio_id, audio_chunk_id=NULL)
    API->>DB: Insert into transcription_jobs
    API->>Redis: Push transcription job
    API-->>Frontend: job_id

    Worker->>Redis: Pull transcription job
    Worker->>Worker: Transcribe stitched audio
    Worker->>DB: Update transcriptions (text, completed_at)

    Worker->>DB: Insert into transcription_jobs (summarisation)
    Worker->>Redis: Push summarisation job

    Worker->>Redis: Pull summarisation job
    Worker->>Worker: Summarise (uses final transcription)
    Worker->>DB: Insert into summarisations
    Worker->>DB: Update session
```

## Data Model

* **Sessions**: 1 per upload session
* **Audio Chunks**: N per session (individual uploaded chunks)
* **Audios**: 1 per session (final stitched audio file)
* **Transcriptions**: N+1 per session
  * N transcriptions for individual chunks (audio\_chunk\_id set, audio\_id NULL)
  * 1 final transcription for stitched audio (audio\_id set, audio\_chunk\_id NULL)
* **Summarisations**: 1 per session (generated from the final transcription)

## Key Points

1. **Live Feedback**: Each chunk is transcribed immediately for real-time feedback
2. **Final Quality**: The stitched audio is transcribed separately for the highest quality result
3. **Summarisation**: Only the final transcription is used for summarisation
4. **Data Integrity**: Foreign key constraints ensure proper relationships between entities