transcription/docs/index.md

Document Transcription System

This project is a production application for transcribing and preserving historical family documents. It is intentionally designed for personal-scale use, with a simplicity-first architecture that is easy to operate and easy to extend.

Start Here

Read architecture.md first.

Then review ver1/ver1.md for completion scope.

The architecture page is the primary technical reference and defines:

• deployed topology and infrastructure limits
• module boundaries and dependency flow
• processing life cycle and data ownership
• test strategy, risk controls, and extension path

What The Application Does

At a high level, users upload images of handwritten, typed, or typeset documents, run asynchronous transcription jobs, review and edit transcript revisions, and search across accepted text.

Core capabilities:

• document upload and metadata capture
• asynchronous transcription with visible job status
• transcription prompt management with one Markdown file per prompt for human refinement over time
• revision history for transcript edits
• full-text search over accepted transcripts
• export of transcript data

Production Operating Model

The system runs with minimal operational overhead:

• PostgreSQL in a dedicated Docker container is considered extremely lightweight and simple for this system
• MongoDB in a dedicated Docker container is also considered extremely lightweight and simple for document-centric persistence
• a three-container deployment (app, PostgreSQL, MongoDB) is a simple and acceptable baseline
• no required queue or search-engine containers in the baseline setup

This operating model keeps deployment and maintenance simple while preserving clean boundaries for future scale.

Documentation Map

• Version 1 implementation plan: ver1/ver1.md
• Architecture and technical design: architecture.md
• Architecture decision records (ADR index): adr/README.md
• Runtime and deployment requirements: requirements.md
• Error handling policy and operational guidance: error_handling.md
• Domain context and transcription policy: intent.md

Glossary

• Document-oriented persistence: Storing data as flexible records instead of fixed relational rows.
• Prompt artifact: A single Markdown file that defines one transcription prompt and is edited independently.
• System of record: The authoritative persistent store for canonical data.