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