transcription/docs/index.md

Document Transcription System (V1)

This project is a personal-scale application for transcribing and preserving historical family documents.

Start Here

Read architecture.md first.

The architecture page is the primary technical reference for:

• runtime topology and infrastructure assumptions
• module boundaries and dependency flow
• processing lifecycle and data ownership
• test strategy and extension path

What The Application Does

At a high level, users upload images/PDFs, jobs are processed asynchronously, and users review original transcriptions plus optional revisions.

Core V1 capabilities:

• upload supported source files (.jpg, .jpeg, .png, .tif, .tiff, .pdf)
• asynchronous job processing with visible status (queued, processing, transcribed, failed)
• immutable original transcription stored on Job.text
• optional single user-authored revision per source (0..1)
• prompt artifacts stored as Markdown files in prompts/

Current Operating Model (V1 Baseline)

• application service: FastAPI + NiceGUI
• persistence baseline: SQLModel with SQLite
• worker: in-process async background loop
• deployment baseline: lightweight Docker Compose app runtime

Planned persistence evolution (PostgreSQL and optional MongoDB) belongs to V2 planning and is tracked separately.

Documentation Map

• Architecture and technical design: architecture.md
• V1 runtime and requirement baseline: requirements.md
• Data model and constraints: schema.md
• Error handling policy and operational guidance: error_handling.md
• V1 requirement evidence matrix: traceability_v1.md
• Operations runbook: runbook.md
• V1 migration and rollback guidance: migration_v1.md
• V1 release checklist: release_checklist_v1.md
• Domain context and transcription policy: intent.md
• Transcription methodology: transcription_methodology.md
• V1 execution plan: ver1/ver1.md
• V2 roadmap: ver2/ver2.md

Glossary

• Prompt artifact: a Markdown file containing one transcription prompt.
• Original transcription: immutable provider output stored on Job.text.
• Revision: optional user-authored text linked to a Source.
• System of record: the authoritative persistent store for canonical application data.