Document Transcription System Requirements (Version 2)

UI (NiceGUI): Satisfies REQ-1, REQ-5, REQ-6, REQ-9, REQ-10.
API (FastAPI): Satisfies REQ-1, REQ-4, REQ-5, REQ-8.
WORKER (asyncio): Satisfies REQ-2, REQ-3, REQ-4, REQ-10.
PERSISTENCE (PostgreSQL): Satisfies REQ-3, REQ-6, REQ-7.
MODELS (Pydantic V2): Satisfies REQ-8.

This document captures the Version 2 baseline requirements for the production implementation.

Requirements Model

ID	Category	Requirement	Verify Method
REQ-0	System	Provide end-to-end multi-page document transcription with persistent, inspectable async job states.	demonstration
REQ-1	Functional	Allow users to upload folders or multi-image batches as sequential `Source` pages under a `Document`.	test
REQ-2	Functional	Process multi-page jobs asynchronously using an `asyncio` worker pool bounded by rate limits.	test
REQ-3	Functional	Persist page-level execution outputs (`raw_transcription`, `ai_metadata`, `raw_api_response`) on `JobSource`.	test
REQ-4	Functional	Support job states (`queued`, `processing`, `completed`, `partial_success`, `failed`) and page states (`pending`, `transcribed`, `failed`).	inspection
REQ-5	Functional	Allow users to manage historical `Person` records and link multiple authors/recipients to a `Document` via `DocumentPerson`.	test
REQ-6	Functional	Maintain immutable original machine output on `Source.raw_transcription` while permitting inline human edits on `Source.revised_text`.	test
REQ-7	Data Constraint	Store all persistent domain data in PostgreSQL using native `UUID`, `TIMESTAMPTZ`, and `JSONB` columns.	inspection
REQ-8	Data Constraint	Validate all API requests, database rows, and JSONB structures using Pydantic V2 schemas.	test
REQ-9	Interface	Render multi-page transcriptions sequentially by `page_number` in the web UI with author/recipient metadata.	demonstration
REQ-10	Operations	Allow operators to retry only failed pages for jobs in a `partial_success` state.	test