generated from john/python-template
85 lines
5.1 KiB
Markdown
85 lines
5.1 KiB
Markdown
## Document Transcription System Requirements
|
|
|
|
This page captures a SysML v1.6-style requirements baseline for the production system described in [index.md](index.md). The model is represented as concise tables and traceability lists that preserve SysML-style IDs and relationship semantics.
|
|
|
|
## Scope
|
|
|
|
- System of interest: the single Python application service (NiceGUI + FastAPI) with PostgreSQL as the relational system of record and optional MongoDB for document-oriented persistence.
|
|
- Operational context: local-first execution with Docker Compose and an intentionally lightweight production trajectory.
|
|
- Primary concern: end-to-end transcription job lifecycle from upload through completion or failure.
|
|
|
|
## 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 one or more document images from the web UI. | low | test |
|
|
| REQ-2 | Functional | Run each upload through asynchronous processing that returns a transcription or explicit failure. | high | test |
|
|
| REQ-3 | Functional | Persist and expose job states: upload, queued, processing, transcribed, failed, completed. | high | inspection |
|
|
| REQ-4 | Functional | Persist transcription output, processing history, and failure details. | medium | test |
|
|
| REQ-5 | Interface | Expose API and UI views for status inspection and completed 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: SQLAlchemy engine, async session factory, worker resources, provider clients. | medium | inspection |
|
|
| REQ-8 | Design Constraint | Initialize configuration and logging once at startup through centralized mechanisms. | low | inspection |
|
|
| REQ-9 | Design Constraint | Use Docker Compose baseline of app plus PostgreSQL; allow optional MongoDB container when enabled. | medium | demonstration |
|
|
| REQ-10 | Design Constraint | Keep schema bootstrap explicit and opt-in; normal startup does not mutate production schema. | high | inspection |
|
|
| REQ-11 | Design Constraint | Use service-backed persistence for core document and job data. | medium | inspection |
|
|
| REQ-12 | Design Constraint | Store transcription prompts as individual Markdown artifacts for iterative refinement. | medium | inspection |
|
|
|
|
### Requirement Relationships
|
|
|
|
- Contains: REQ-0 contains REQ-1 through REQ-12.
|
|
- 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 | src/transcription/ui/pages |
|
|
| API | FastAPI routes | src/transcription/api/routes.py |
|
|
| GRAPH | Async processing workflow | src/transcription/services, src/transcription/ai |
|
|
| DBREL | PostgreSQL + SQLModel relational persistence | src/transcription/db |
|
|
| DBDOC | MongoDB document persistence | src/transcription/db, src/transcription/services |
|
|
| OPS | Docker Compose runtime | docker-compose.yml |
|
|
| PROMPTS | Transcription prompt artifact library (Markdown files) | .github/prompts, docs |
|
|
| TESTS | Pytest verification suite | tests |
|
|
|
|
### Satisfaction Mapping
|
|
|
|
- UI satisfies REQ-1, REQ-5.
|
|
- API satisfies REQ-5.
|
|
- GRAPH satisfies REQ-2, REQ-6.
|
|
- DBREL satisfies REQ-3, REQ-10.
|
|
- DBDOC 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.
|
|
|
|
## Requirement Notes
|
|
|
|
- Requirement IDs (`REQ-*`) are stable references for planning, implementation, and test traceability.
|
|
- The model uses compact tables and traceability lists for renderer compatibility while preserving SysML-style requirement IDs and relationship semantics.
|
|
- Requirement categories (functional, interface, performance, and design constraints) are preserved as explicit REQ entries and relationship labels to keep change impact visible.
|
|
- PostgreSQL containerization and optional MongoDB containerization are both treated as extremely lightweight and simple operational choices in this architecture.
|
|
|
|
## Verification Intent
|
|
|
|
- Demonstration: validate end-to-end behavior via running system flows and operator-visible outcomes.
|
|
- 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-level tests.
|
|
|
|
## Glossary
|
|
|
|
- Document-oriented persistence: A storage approach that uses flexible document structures for variable data shapes.
|
|
- Prompt artifact: A single Markdown file that defines one transcription prompt and is revised independently.
|
|
- SysML: Systems Modeling Language used to express structured requirements and traceability.
|
|
- System of record: The authoritative persistent store for canonical business data.
|