transcription/docs/ver1/schema_v1.md

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

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

---

Related Local References

• System Overview
• System Design Intent
• Transcription Methodology
• System Architecture
• System Requirements
• Data model (this document)
• Error Handling Policy
• Implementation Plan

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.