transcription/docs/ver4/schema_v4.md

Database Schema (Version 4)

This document defines the relational schema for the document transcription system.

Entity Relationship Diagram

erDiagram
DOCUMENT_TYPE {
UUID id PK
TEXT code
TEXT label
BOOLEAN is_active
INTEGER sort_order
TIMESTAMPTZ created_at
TIMESTAMPTZ updated_at
}

PERSON_ROLE {
UUID id PK
TEXT code
TEXT label
BOOLEAN is_active
TIMESTAMPTZ created_at
TIMESTAMPTZ updated_at
}

ROLE_EXCLUSIVITY {
UUID id PK
UUID left_role_id FK
UUID right_role_id FK
TIMESTAMPTZ created_at
}

PERSON {
UUID id PK
TEXT full_name
TEXT display_name
TEXT maiden_name
DATE birth_date
TEXT birth_date_raw
TEXT birth_place
DATE death_date
TEXT death_date_raw
TEXT death_place
TEXT biography
TEXT portrait_path
JSONB metadata
TIMESTAMPTZ created_at
TIMESTAMPTZ updated_at
}

DOCUMENT {
UUID id PK
UUID document_type_id FK
TEXT name
DATE document_date
TEXT document_date_raw
TEXT location_created
TEXT notes
TEXT archive_identifier
TIMESTAMPTZ created_at
TIMESTAMPTZ updated_at
}

DOCUMENT_PERSON {
UUID id PK
UUID document_id FK
UUID person_id FK
UUID role_id FK
TIMESTAMPTZ created_at
TIMESTAMPTZ updated_at
}

JOB {
UUID id PK
UUID document_id FK
VARCHAR status
INTEGER retry_count
TEXT provider
TEXT model
TEXT prompt_name
TEXT prompt_hash
TEXT system_prompt
TEXT user_prompt
FLOAT temperature
FLOAT top_p
TIMESTAMPTZ date_created
TIMESTAMPTZ date_updated
}

SOURCE {
UUID id PK
UUID document_id FK
INTEGER page_number
TEXT upload_name
TEXT filename
TEXT file_path
TEXT file_hash
BIGINT file_size_bytes
TEXT raw_transcription
TEXT revised_text
TIMESTAMPTZ date_uploaded
TIMESTAMPTZ date_revised
}

JOB_SOURCE {
UUID id PK
UUID job_id FK
UUID source_id FK
VARCHAR status
TEXT raw_transcription
JSONB ai_metadata
JSONB raw_api_response
TEXT error_detail
TIMESTAMPTZ executed_at
}

DOCUMENT_TYPE ||--o{ DOCUMENT : classifies
DOCUMENT ||--o{ DOCUMENT_PERSON : has_people
PERSON ||--o{ DOCUMENT_PERSON : appears_in
PERSON_ROLE ||--o{ DOCUMENT_PERSON : labels
PERSON_ROLE ||--o{ ROLE_EXCLUSIVITY : left_rule
PERSON_ROLE ||--o{ ROLE_EXCLUSIVITY : right_rule
DOCUMENT ||--o{ JOB : has_jobs
DOCUMENT ||--o{ SOURCE : contains_pages
JOB ||--o{ JOB_SOURCE : executes
SOURCE ||--o{ JOB_SOURCE : processed_in

Domain Invariants and Provenance Rules

Page-Level Execution and AI Outputs

• Every single page execution by an AI model produces a dedicated JOB_SOURCE record.
• Every JOB stores the frozen prompt identifier, prompt text, and hyperparameters used at submission time.
• Every JOB_SOURCE stores the complete provider response envelope and page-level operational metadata.
• SOURCE.raw_transcription caches the latest successful machine output for that page.

Image Storage and Integrity

• Binary images are stored on disk; SOURCE.file_path stores the persisted path.
• SOURCE.file_hash stores a SHA-256 digest.
• SOURCE.file_size_bytes stores the original file size.

Page Ordering and Revisions

• SOURCE.page_number dictates page ordering within a document.
• SOURCE.raw_transcription remains immutable machine output.
• SOURCE.revised_text stores human edits and is the preferred display value when present.

Document-Person Role Governance

• Documents support zero, one, or many people per relationship role.
• Relationship roles are defined by PERSON_ROLE rather than hardcoded columns.
• DOCUMENT_PERSON must be unique for (document_id, person_id, role_id).
• Configured exclusive role pairs from ROLE_EXCLUSIVITY cannot coexist for the same (document_id, person_id).
• Initial exclusivity seed blocks author and recipient for the same person-document pair.

Document Type Governance

• Every document type is defined by DOCUMENT_TYPE.
• DOCUMENT_TYPE.code is a stable machine identifier.
• DOCUMENT_TYPE.label is mutable display text.
• Inactive types remain valid for historical rows but should be excluded from default selection UIs.

Constraint Summary

• DOCUMENT_TYPE.code is unique.
• PERSON_ROLE.code is unique.
• DOCUMENT_PERSON(document_id, person_id, role_id) is unique.
• ROLE_EXCLUSIVITY(left_role_id, right_role_id) is unique.
• ROLE_EXCLUSIVITY must use canonical ordering to avoid duplicate mirrored pairs.

Indexing Guidance

• document(document_type_id)
• document_person(document_id)
• document_person(person_id)
• document_person(role_id)
• role_exclusivity(left_role_id, right_role_id)
• source(document_id, page_number)
• job(document_id, status)
• job_source(job_id)
• job_source(source_id)

Related Local References

• System Overview
• System Architecture
• System Requirements
• Error Handling Policy