V1 mostly complete except for some testing. Linting in the last step changed nearly every file which is why this commit is so larger.

2026-07-29 17:27:21 -05:00
parent bc21a97019
commit a3b3bab571
37 changed files with 1383 additions and 410 deletions
@@ -0,0 +1,56 @@
+## 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](architecture.md) first.
+
+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 or PDFs as content sources for handwritten, typed, or typeset documents, run asynchronous transcription jobs, review optional revisions, and search across accepted text.
+
+Core capabilities:
+
+- document grouping with one or more content sources and metadata capture
+- asynchronous transcription with visible job status
+- immutable original transcription persisted with each job (plus provider/model/prompt metadata)
+- transcription prompt management with one Markdown file per prompt for human refinement over time
+- optional revisions for user-authored edits of original immutable transcription text
+- 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
+
+- Architecture and technical design: [architecture.md](architecture.md)
+- Runtime and deployment requirements: [requirements.md](requirements.md)
+- Error handling policy and operational guidance: [error_handling.md](error_handling.md)
+- Domain context and transcription policy: [intent.md](intent.md)
+- Transcription Methodology: [transcription_methodology.md](transcription_methodology.md)
+- Data model: [schema.md](schema.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.