diff --git a/docs/architecture_v2.md b/docs/architecture_v2.md index 1f55a8c..0c4753f 100644 --- a/docs/architecture_v2.md +++ b/docs/architecture_v2.md @@ -59,7 +59,7 @@ Responsibilities: ### Domain & Service Layer -* `src/transcription/models/*.py` (Pydantic V2 schemas and entity definitions) +* `src/transcription/db/models.py` (SQLModel/Pydantic V2 schema definitions for the current implementation) * `src/transcription/services/*.py` (Transactional operations for `Document`, `Person`, `Source`, `Job`, and `JobSource`) ### Infrastructure Layer @@ -121,14 +121,14 @@ Responsibilities: ## Related Local References -- [System Overview](index_v1.md) -- [System Design Intent](intent.md) -- [Transcription Methodology](transcription_methodology.md) +- [System Overview](index_v2.md) +- [System Design Intent](invariant/intent.md) +- [Transcription Methodology](invariant/transcription_methodology.md) - System Architecture (this document) -- [System Requirements](requirements_v1.md) -- [Data model](schema_v1.md) -- [Error Handling Policy](error_handling_v1.md) -- [Implementation Plan](implementation_plan_v1.md) +- [System Requirements](requirements_v2.md) +- [Data model](schema_v2.md) +- [Error Handling Policy](error_handling_v2.md) +- [Implementation Plan](implementation_plan_v2.md) diff --git a/docs/ddl_v2.sql b/docs/ddl_v2.sql deleted file mode 100644 index 65c1d75..0000000 --- a/docs/ddl_v2.sql +++ /dev/null @@ -1,102 +0,0 @@ -## PostgreSQL DDL Specification (Version 2) - -```sql --- Enable pgcrypto for UUID generation if on PostgreSQL < 13 -CREATE EXTENSION IF NOT EXISTS "pgcrypto"; - --- 1. PERSON TABLE -CREATE TABLE person ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - full_name TEXT NOT NULL, - display_name TEXT, - maiden_name TEXT, - birth_date DATE, - birth_date_raw TEXT, - birth_place TEXT, - death_date DATE, - death_date_raw TEXT, - death_place TEXT, - biography TEXT, - portrait_path TEXT, - metadata JSONB DEFAULT '{}'::jsonb, - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - updated_at TIMESTAMPTZ NOT NULL DEFAULT now() -); - --- 2. DOCUMENT TABLE -CREATE TABLE document ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - name TEXT NOT NULL, - document_type TEXT, - document_date DATE, - document_date_raw TEXT, - location_created TEXT, - notes TEXT, - archive_identifier TEXT, - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - updated_at TIMESTAMPTZ NOT NULL DEFAULT now() -); - --- 3. DOCUMENT_PERSON (Junction Table for Multi-Author / Multi-Recipient) -CREATE TABLE document_person ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - document_id UUID NOT NULL REFERENCES document(id) ON DELETE CASCADE, - person_id UUID NOT NULL REFERENCES person(id) ON DELETE CASCADE, - role VARCHAR(20) NOT NULL, -- 'author' or 'recipient' - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - CONSTRAINT unique_document_person_role UNIQUE (document_id, person_id, role) -); - --- 4. JOB TABLE (Batch-level orchestrator) -CREATE TABLE job ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - document_id UUID NOT NULL REFERENCES document(id) ON DELETE CASCADE, - status VARCHAR(50) NOT NULL DEFAULT 'queued', -- 'queued', 'processing', 'completed', 'partial_success', 'failed' - retry_count INTEGER NOT NULL DEFAULT 0, - provider TEXT NOT NULL, -- e.g., 'openai', 'anthropic' - model TEXT NOT NULL, -- e.g., 'gpt-4o', 'claude-3-5-sonnet' - prompt_name TEXT, - date_created TIMESTAMPTZ NOT NULL DEFAULT now(), - date_updated TIMESTAMPTZ NOT NULL DEFAULT now() -); - --- 5. SOURCE TABLE (Physical image files & active state) -CREATE TABLE source ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - document_id UUID NOT NULL REFERENCES document(id) ON DELETE CASCADE, - page_number INTEGER NOT NULL DEFAULT 1, - upload_name TEXT NOT NULL, - filename TEXT NOT NULL, - file_path TEXT NOT NULL, - raw_transcription TEXT, -- Cached active AI text output - revised_text TEXT, -- Active human edited text - date_uploaded TIMESTAMPTZ NOT NULL DEFAULT now(), - date_revised TIMESTAMPTZ -); - --- 6. JOB_SOURCE (Junction Table: Per-Image Execution Record) -CREATE TABLE job_source ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - job_id UUID NOT NULL REFERENCES job(id) ON DELETE CASCADE, - source_id UUID NOT NULL REFERENCES source(id) ON DELETE CASCADE, - status VARCHAR(50) NOT NULL DEFAULT 'pending', -- 'pending', 'transcribed', 'failed' - raw_transcription TEXT, -- Point-in-time raw AI text output - ai_metadata JSONB, -- Page-level bounding boxes, tokens, confidence - raw_api_response JSONB, -- Complete REST response envelope - error_detail TEXT, - executed_at TIMESTAMPTZ NOT NULL DEFAULT now(), - CONSTRAINT unique_job_source UNIQUE (job_id, source_id) -); - --- INDEXES FOR FAST LOOKUPS & QUERY PERFORMANCE -CREATE INDEX idx_person_full_name ON person(full_name); -CREATE INDEX idx_document_date ON document(document_date); -CREATE INDEX idx_document_person_doc ON document_person(document_id); -CREATE INDEX idx_document_person_per ON document_person(person_id); -CREATE INDEX idx_source_document ON source(document_id); -CREATE INDEX idx_source_page_order ON source(document_id, page_number); -CREATE INDEX idx_job_document ON job(document_id); -CREATE INDEX idx_job_source_job ON job_source(job_id); -CREATE INDEX idx_job_source_source ON job_source(source_id); -CREATE INDEX idx_job_source_ai_metadata ON job_source USING GIN (ai_metadata); -``` \ No newline at end of file diff --git a/docs/error_handling_v2.md b/docs/error_handling_v2.md index 5325c56..7915fb0 100644 --- a/docs/error_handling_v2.md +++ b/docs/error_handling_v2.md @@ -79,8 +79,8 @@ HTTP Status Mappings: ## Related Local References - [System Overview](index_v2.md) -- [System Design Intent](intent.md) -- [Transcription Methodology](transcription_methodology.md) +- [System Design Intent](invariant/intent.md) +- [Transcription Methodology](invariant/transcription_methodology.md) - [System Architecture](architecture_v2.md) - [System Requirements](requirements_v2.md) - [Data model](schema_v2.md) diff --git a/docs/implementation_plan_v2.md b/docs/implementation_plan_v2.md index d390f58..8b30960 100644 --- a/docs/implementation_plan_v2.md +++ b/docs/implementation_plan_v2.md @@ -22,7 +22,7 @@ Use a fresh database. There will be no migrations, data conversion, legacy compa - Remove `Revision`, `Source.job_id`, and the transcription fields that no longer belong on `Job`. - Keep `create_all()` as the schema bootstrap for a fresh database. - Delete `_ensure_sqlite_compat_columns()` and all schema patching from `src/transcription/db/operations.py`. -- Keep the Python models, `docs/schema_v2.md`, and `docs/ddl_v2.sql` consistent. +- Keep the Python models and `docs/schema_v2.md` consistent. ### 2. Align the async CRUD methods diff --git a/docs/index_v2.md b/docs/index_v2.md index 8ca3737..b7ff8fa 100644 --- a/docs/index_v2.md +++ b/docs/index_v2.md @@ -38,8 +38,8 @@ Read [architecture_v2.md](architecture_v2.md) first for technical overview and s ## Documentation Index - System Overview (this document) -- [System Design Intent](intent.md) -- [Transcription Methodology](transcription_methodology.md) +- [System Design Intent](invariant/intent.md) +- [Transcription Methodology](invariant/transcription_methodology.md) - [System Architecture](architecture_v2.md) - [System Requirements](requirements_v2.md) - [Data model](schema_v2.md) diff --git a/docs/Intent.md b/docs/invariant/intent.md similarity index 100% rename from docs/Intent.md rename to docs/invariant/intent.md diff --git a/docs/transcription_methodology.md b/docs/invariant/transcription_methodology.md similarity index 100% rename from docs/transcription_methodology.md rename to docs/invariant/transcription_methodology.md diff --git a/docs/requirements_v2.md b/docs/requirements_v2.md index f21b3c0..f693710 100644 --- a/docs/requirements_v2.md +++ b/docs/requirements_v2.md @@ -31,8 +31,8 @@ This document captures the **Version 2 baseline requirements** for the productio ## Related Local References - [System Overview](index_v2.md) -- [System Design Intent](intent.md) -- [Transcription Methodology](transcription_methodology.md) +- [System Design Intent](invariant/intent.md) +- [Transcription Methodology](invariant/transcription_methodology.md) - [System Architecture](architecture_v2.md) - System Requirements (this document) - [Data model](schema_v2.md) diff --git a/docs/schema_v2.md b/docs/schema_v2.md index 17408f2..0fb7991 100644 --- a/docs/schema_v2.md +++ b/docs/schema_v2.md @@ -126,8 +126,8 @@ erDiagram ## Related Local References - [System Overview](index_v2.md) -- [System Design Intent](intent.md) -- [Transcription Methodology](transcription_methodology.md) +- [System Design Intent](invariant/intent.md) +- [Transcription Methodology](invariant/transcription_methodology.md) - [System Architecture](architecture_v2.md) - [System Requirements](requirements_v2.md) - Data model (this document) diff --git a/docs/test_block-beta.md b/docs/ui/test_block-beta.md similarity index 100% rename from docs/test_block-beta.md rename to docs/ui/test_block-beta.md diff --git a/docs/test_flowchart.md b/docs/ui/test_flowchart.md similarity index 100% rename from docs/test_flowchart.md rename to docs/ui/test_flowchart.md