Update V1 & V2 core documents and reorganize docs folder

2026-07-31 10:04:07 -05:00
parent d2b793ea69
commit 3eefc36239
25 changed files with 671 additions and 783 deletions
@@ -0,0 +1,98 @@
+## 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`
+
+---
+
+## Related Local References
+
+- [System Overview](index_v1.md)
+- [System Design Intent](intent.md)
+- [Transcription Methodology](transcription_methodology.md)
+- [System Architecture](architecture_v1.md)
+- [System Requirements](requirements_v1.md)
+- Data model (this document)
+- [Error Handling Policy](error_handling_v1.md)
+- [Implementation Plan](implementation_plan_v1.md)
+
+## 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.