transcription/docs/ver4/requirements_v4.md

Document Transcription System Requirements (Version 4)

This document defines the baseline requirements for the document transcription system.

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 one or more images as ordered Source pages under a Document.	test
REQ-2	Functional	Process page transcription asynchronously using an asyncio worker pool bounded by rate limits.	test
REQ-3	Functional	Persist submission-time request provenance and accurately labeled page-level SDK evidence; V4.2 adds exact OpenRouter-boundary transport evidence for new attempts.	test
REQ-4	Functional	Support job states queued, processing, completed, partial_success, and failed, plus page states pending, transcribed, and failed.	inspection
REQ-5	Functional	Allow users to manage historical Person records and link each Person to a Document once with exactly one role.	test
REQ-6	Functional	Support an extensible role taxonomy for document-person relationships.	inspection
REQ-7	Policy Constraint	Enforce deterministic relationship-role writes with uniqueness on (document_id, person_id) and explicit conflict responses for duplicate Person links.	test
REQ-8	Functional	Use set-based synchronization for document-person mutations so updates add and remove only the intended links.	test
REQ-9	Functional	Maintain selected machine output and exact attempt provenance on Source while permitting independent human edits on Source.revised_text.	test
REQ-10	Functional	Support a UUID-identified DocumentType taxonomy with unique user-facing labels and active/inactive lifecycle control.	test
REQ-11	Data Constraint	Store Document type as a controlled reference to DocumentType.	test
REQ-12	Interface	Render multi-page transcriptions sequentially by page_number with document, people, and document-type metadata.	demonstration
REQ-13	Interface	Document create/edit UI must provide one staged Linked People table and select active registry entries by UUID and label.	demonstration
REQ-14	API Constraint	Expose additive, role-aware retrieval and write behavior for document-person links and UUID-based selection for document types.	test
REQ-15	Data Constraint	Calculate and store cryptographic file hashes (SHA-256) and file sizes for uploaded source images.	test
REQ-16	Data Constraint	Preserve a portable relational model across supported backends using SQLModel, SQLAlchemy, SQLite, and PostgreSQL.	inspection
REQ-17	Reliability	Ensure delete and update flows for documents, people, and relationship links remain deterministic and safe.	test
REQ-18	Operations Constraint	Keep canonical development, testing, restore, and recovery workflows OS-independent; for AI-run unit tests, require a pre-test backup of ./data and an always-shown post-success confirmation prompt before any restore action.	inspection
REQ-19	Quality	Provide automated coverage for async transcription workflows, relationship-role enforcement, document-type selection, and regression behavior.	test
REQ-20	Data Constraint	Permit hidden immutable semantic keys only on protected built-in Document Types and Person Roles while retaining UUID as relationship identity.	test
REQ-21	Reliability	Persist Document fields and their complete Linked People set atomically.	test
REQ-22	Interface	Provide safe browser-native Facsimile and Text-only print views from persisted Document Detail.	demonstration
REQ-23	Security	Escape stored print text and serve Source images through record-validated application routes without disclosing local paths.	test
REQ-24	Functional	Print current human-preferred Source text, semantic Author metadata, deterministic Source order, and oldest-to-newest Job metadata.	test
REQ-25	Quality	Physically apply recognized raster orientation metadata to provider-input derivatives without changing original Source bytes.	test
REQ-26	Quality	Persist deterministic, non-mutating output warnings without automatic paid retries.	test
REQ-27	Functional	Create one-Source retranscription Jobs from a configured model allowlist and preserve later successes as candidates until explicit promotion.	test

Clarifying Constraints

1. DocumentType.id and PersonRole.id are their public and relationship identities; labels are unique ignoring case and surrounding whitespace.
2. Nullable semantic_key values identify protected application built-ins, remain internal, and never change.
3. Relationship-write policy and conflict handling must be consistent across UI, API, services, and persistence.
4. One Person may appear only once per Document and every link has exactly one role.
5. Relationship conflicts must fail deterministically without partial Document or link mutation.
6. Source page reordering and server-generated PDF files remain outside this revision.

Element Satisfaction Mapping

• UI (NiceGUI): Satisfies REQ-0, REQ-1, REQ-5, REQ-9, REQ-12, REQ-13, REQ-22, REQ-24.
• API (FastAPI): Satisfies REQ-1, REQ-4, REQ-5, REQ-7, REQ-8, REQ-14, REQ-23.
• Worker (asyncio): Satisfies REQ-2, REQ-3, REQ-4.
• Persistence (SQLModel / SQLAlchemy): Satisfies REQ-3, REQ-7, REQ-9, REQ-10, REQ-11, REQ-15, REQ-16, REQ-17, REQ-20, REQ-21.
• Test Suite: Verifies all test-marked requirements and satisfies REQ-19.

Related Local References

• System Overview
• System Architecture
• Data Model
• Error Handling Policy