## Document Transcription System (V1)

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

## Start Here

Read [architecture.md](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](architecture.md)
- V1 runtime and requirement baseline: [requirements.md](requirements.md)
- Data model and constraints: [schema.md](schema.md)
- Error handling policy and operational guidance: [error_handling.md](error_handling.md)
- V1 requirement evidence matrix: [traceability_v1.md](traceability_v1.md)
- Operations runbook: [runbook.md](runbook.md)
- V1 migration and rollback guidance: [migration_v1.md](migration_v1.md)
- V1 release checklist: [release_checklist_v1.md](release_checklist_v1.md)
- Domain context and transcription policy: [intent.md](intent.md)
- Transcription methodology: [transcription_methodology.md](transcription_methodology.md)
- V1 execution plan: [ver1/ver1.md](ver1/ver1.md)
- V2 roadmap: [ver2/ver2.md](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.