transcription/docs/requirements.md

Document Transcription System Requirements (V1 Baseline)

This page captures the Version 1 baseline requirements for the currently implemented system. It is the source of truth for V1 acceptance and test traceability.

Forward-looking architecture changes (for example PostgreSQL/Mongo adoption) are intentionally out of this document and should be tracked in a V2 planning/backlog artifact.

Scope

• System of interest: a single Python application service (NiceGUI + FastAPI) with SQLModel persistence.
• Runtime/persistence baseline: local-first execution using SQLite (default sqlite:///./transcription.db), with Docker Compose support.
• Primary concern: end-to-end transcription lifecycle from upload through terminal state plus optional single revision editing.

Requirements Model (Concise Text Form)

Requirements

ID	Category	Requirement	Risk	Verify Method
REQ-0	System	Provide end-to-end document transcription with persistent, inspectable lifecycle state.	medium	demonstration
REQ-1	Functional	Allow users to upload supported image/PDF files as sources from the web UI.	low	test
REQ-2	Functional	Process uploads asynchronously and return either original transcription output or explicit failure.	high	test
REQ-3	Functional	Persist and expose job states: queued, processing, transcribed, failed.	high	inspection
REQ-4	Functional	Persist original provider output (Job.text) and failure detail (Job.error_detail) for each job.	medium	test
REQ-5	Interface	Expose API/UI views for status inspection and transcription reading.	medium	demonstration
REQ-6	Performance	Trigger background processing on upload to preserve UI responsiveness.	medium	analysis
REQ-7	Design Constraint	Keep lifespan-owned runtime resources (engine/session factory/worker resources) initialized and disposed at application boundaries.	medium	inspection
REQ-8	Design Constraint	Initialize configuration and logging once at startup through centralized mechanisms.	low	inspection
REQ-9	Design Constraint	Support containerized app runtime via Docker Compose using the same V1 persistence model.	medium	demonstration
REQ-10	Design Constraint	Keep schema bootstrap explicit and opt-in for production safety.	high	inspection
REQ-11	Design Constraint	Route persistence changes through service/workflow orchestration boundaries.	medium	inspection
REQ-12	Design Constraint	Store transcription prompts as individual Markdown artifacts for iterative refinement.	medium	inspection
REQ-13	Functional	Allow users to create/update one optional revision derived from the original job transcription and view/delete it from the job detail flow.	low	test

Requirement Relationships

• Contains: REQ-0 contains REQ-1 through REQ-13.
• Derives: REQ-2 -> REQ-3, REQ-3 -> REQ-4.
• Traces: REQ-5 -> REQ-3.
• Refines: REQ-6 -> REQ-2.

Architecture Elements

Element	Type	Doc Reference
UI	NiceGUI pages/components	src/transcription/ui/pages, src/transcription/ui/components
API	FastAPI routes and handlers	src/transcription/api, src/transcription/app.py
WORKER	Async queued-job processing workflow	src/transcription/worker.py, src/transcription/services/workflows.py
DBREL	SQLModel relational persistence (SQLite in V1 baseline)	src/transcription/models.py, src/transcription/db
SERVICES	Service-layer persistence orchestration	src/transcription/services
OPS	Containerized runtime baseline	docker-compose.yml, Dockerfile
PROMPTS	Transcription prompt artifacts	prompts/
TESTS	Pytest verification suite	tests/

Satisfaction Mapping

• UI satisfies REQ-1, REQ-5, REQ-13.
• API satisfies REQ-5.
• WORKER satisfies REQ-2, REQ-6.
• DBREL satisfies REQ-3, REQ-4, REQ-10, REQ-13.
• SERVICES satisfies REQ-4, REQ-11.
• OPS satisfies REQ-9.
• PROMPTS satisfies REQ-12.

Verification Mapping

• TESTS verifies REQ-1, REQ-2, REQ-3, REQ-4, REQ-5, REQ-10, REQ-11, REQ-12, REQ-13.

Requirement Notes

• Requirement IDs (REQ-*) are stable references for planning, implementation, and traceability.
• This document is intentionally implementation-aligned for V1 completion and release sign-off.
• Planned storage evolution (PostgreSQL and optional MongoDB) is a V2 concern and should be tracked outside this V1 baseline.

Verification Intent

• Demonstration: validate end-to-end behavior through operator-visible flows.
• Inspection: verify architecture and startup/runtime policies in code and configuration.
• Analysis: evaluate asynchronous execution behavior and design sufficiency.
• Test: automate behavioral checks through pytest suites and service/UI integration tests.

Glossary

• Original transcription: immutable provider output stored on Job.text.
• Revision: optional user-authored editable text tied to a Source (0..1 in V1).
• Prompt artifact: a Markdown file containing instructions used for transcription.
• System of record: the authoritative relational store for canonical V1 data.