generated from john/python-template
88 lines
2.1 KiB
Markdown
88 lines
2.1 KiB
Markdown
## 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.
|