transcription/docs/ver1/implementation_plan_v1.md

Version 1 Implementation Plan

This plan defines the path from current implementation to Version 1 complete, aligned to the updated domain model:

• Document groups one or more content Source records
• Job owns original immutable provider output (text) and processing metadata
• Revision stores optional user-authored edits linked to a Source

The objective is to complete V1 scope with production readiness while keeping non-V1 enhancements out of active delivery.

---

V1 Completion Definition

V1 is complete when all of the following are true:

1. Functional complete
   • Upload, queue, processing, status display, and transcription result inspection work end-to-end.
   • Optional revision workflow is implemented (create/view/update single revision).
2. Data-model complete
   • Runtime behavior, persistence, and tests all align to Document / Source / Job / Revision.
3. Operational complete
   • Error handling, logs, and runbooks support reliable operation.
4. Documentation complete
   • Architecture, requirements, schema, error handling, and index are consistent and current.

---

Phase 1 — Data Contract Stabilization (Schema-First)

Goal: Lock a single canonical contract before further feature work.

Tasks

1. Confirm and document invariants:
   • Job.text is original immutable transcription output.
   • Revision is optional and user-authored.
   • Revisions are derived from the original Job.text.
2. Verify relationship cardinality assumptions:
   • Document -> many Source
   • Document -> many Job
   • Source -> one Job
   • Source -> one Revision
3. Ensure field naming consistency (date_created, date_updated, date_uploaded) across code and docs.
4. Freeze V1 status lifecycle to current implementation (queued, processing, transcribed, failed).

Deliverables

• Updated schema_v1.md and requirements.md traceability alignment.
• Explicit V1 data invariants section in architecture docs.

Exit Criteria

• No conflicting definitions of ownership/cardinality/status remain in docs.

---

Phase 2 — Service Layer Refactor To New Model

Goal: Remove all obsolete Transcript assumptions from service/workflow code.

Tasks

1. Refactor services/transcription.py:
   • Replace transcript CRUD assumptions with job-output + revision operations.
2. Refactor services/jobs.py:
   • Replace old timestamp/relationship accessors with current model fields.
3. Refactor services/documents.py and services/store.py:
   • Ensure upload creates and links Document, Source, and Job correctly.
4. Refactor services/workflows.py:
   • Persist original provider output to Job.
   • Persist failure detail to Job.error_detail.
   • Use Revision only for user-authored edits.

Deliverables

• Service layer fully aligned with new schema.

Exit Criteria

• No service module imports or persists Transcript model artifacts.

---

Phase 3 — UI Contract Alignment

Goal: Align pages/components to source/job/revision semantics.

Tasks

1. Update job detail and related UI components:
   • Display original immutable transcription from Job.text.
   • Display optional revision sourced from Source.revision (0 or 1).
2. Align date fields with new schema naming.
3. Preserve clear user messaging when no revisions exist.

Deliverables

• Updated jobs page and detail components.

Exit Criteria

• UI behavior and labels match documentation and domain model.

---

Phase 4 — Database Bootstrap, Migration, and Safety

Goal: Make schema transition safe in dev/test and repeatable for deployment.

Tasks

1. Update bootstrap compatibility logic in db/operations.py:
   • Remove obsolete transcript-table assumptions.
   • Add forward-compatible patches for current tables only.
2. Define migration/backfill approach for existing local data.
3. Document rollback and recovery steps.
4. Rehearse migration path against representative data.

Deliverables

• Migration/upgrade runbook.
• Validated bootstrap behavior for dev/test.

Exit Criteria

• Migration path is documented and tested with no unresolved data-loss risk.

---

Phase 5 — Test Suite Realignment

Goal: Restore full confidence after the schema redesign.

Tasks

1. Rewrite model tests for:
   • Document, Source, Job, Revision relationships and invariants.
2. Rewrite service/integration tests:
   • Worker success/failure paths using Job.text / Job.error_detail.
   • Optional single-revision creation/update behavior.
3. Update UI tests for new job-detail/revision rendering behavior.
4. Re-enable strict CI quality gates (lint, type, tests).

Deliverables

• Updated test matrix and passing CI.

Exit Criteria

• Critical user flows and failure paths are covered and green.

---

Phase 6 — Reliability, Operations, and Release Readiness

Goal: Ensure V1 is operable and launch-safe.

Tasks

1. Verify error taxonomy behavior across UI/API/service/worker.
2. Confirm structured logging includes relevant identifiers (job_id, document_id, source_id when applicable).
3. Validate retry behavior and terminal failure handling.
4. Finalize release checklist, deployment steps, and rollback procedure.
5. Execute final acceptance run against requirements traceability.

Deliverables

• V1 release checklist and acceptance evidence.
• runbook_v1.md for incident response and operator workflows.
• release_checklist_v1.md for release sign-off.

Exit Criteria

• Stakeholder sign-off and launch readiness achieved.

---

Requirement Traceability Focus

The plan must keep clear evidence against these requirement groups:

• Core flow: REQ-0 to REQ-6
• Runtime and operations constraints: REQ-7 to REQ-12
• Revision workflow: REQ-13

A lightweight traceability table should be maintained with:

• requirement ID
• implementation status (not started / in progress / done)
• validation evidence (test name, screenshot, or runbook step)

---

Suggested Execution Rhythm

• Weekly: requirement status and risk review
• Per PR: contract checks (model names, field names, lifecycle values)
• Milestone checks: end of Phases 2, 4, and 6

---

Scope Discipline Rule (V1 Focus)

• Only work required to satisfy V1 requirements enters this plan.
• Nice-to-have enhancements are captured in a separate backlog document.
• Schema or contract changes after Phase 1 require explicit approval and traceability impact review.

---

Related Local References

• System Overview
• System Design Intent
• Transcription Methodology
• System Architecture
• System Requirements
• Data model
• Error Handling Policy
• Implementation Plan (this document)