## Database Schema (V1 Baseline)

This document describes the current relational schema for the transcription system.

All primary and foreign keys in the domain models are UUID-based in V1.

---

## Schema Diagram

```mermaid
erDiagram
    DOCUMENT {
        UUID id PK
        TEXT name
    }

    JOB {
        UUID id PK
        UUID document_id FK
        TEXT status
        INTEGER retry_count
        DATETIME date_created
        DATETIME date_updated
        TEXT provider
        TEXT model
        TEXT prompt_name
        TEXT text
        TEXT error_detail
    }

    SOURCE {
        UUID id PK
        UUID document_id FK
        UUID job_id FK
        TEXT upload_name
        TEXT filename
        TEXT file_path
        DATETIME date_uploaded
    }

    REVISION {
        UUID id PK
        UUID source_id "FK, UK"
        INTEGER revision
        TEXT text
        DATETIME date_created
    }

    DOCUMENT ||--o{ SOURCE : has_many
    DOCUMENT ||--o{ JOB : has_many
    JOB ||--o{ SOURCE : referenced_by
    SOURCE ||--o| REVISION : has_optional_one
```

---

## Table Relationships and Constraints

- A `Document` can have zero or more `Source` records.
- A `Document` can have zero or more `Job` records.
- A `Source` belongs to exactly one `Document` and one `Job`.
- A `Source` may have one optional `Revision`.
- Optional `0..1` revision cardinality is enforced by uniqueness on `revision.source_id`.

### Invariants

- `Job.text` stores immutable original provider transcription output.
- `Revision` rows are optional user-authored edits derived from original transcription.
- Revisions do not overwrite original `Job.text`.
- Job status lifecycle values are: `queued`, `processing`, `transcribed`, `failed`.

### Timestamp Fields

- `Job.date_created`
- `Job.date_updated`
- `Source.date_uploaded`
- `Revision.date_created`

---

## Glossary

- **Document**: logical grouping for one or more transcribed sources.
- **Source**: uploaded file content (image/PDF) linked to a job.
- **Job**: processing record that stores lifecycle status and original output.
- **Revision**: optional single user-authored edited text linked to a source.