transcription/docs/ui/entities/traceability-matrix.md

UI Entity Traceability Matrix

Purpose: Map acceptance criteria to concrete implementation anchors and current delivery status.

Updated: 2026-08-02

Status legend:

• Implemented: behavior exists in current UI and service flow
• Partial: parts exist, but user-facing behavior or guardrails are incomplete
• Planned: documented intent with no dedicated UI implementation yet

Document

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Read detail and metadata	RD-1, RD-2, RD-7	Implemented	src/transcription/ui/pages/documents_page.py; src/transcription/services/documents.py; tests/ui/test_documents_page.py	Dedicated Document detail route renders metadata, read-only system timestamps, and invalid/missing-id states.
Related sections and navigation	RD-3, RD-4, RD-5, RD-6	Implemented	src/transcription/ui/pages/documents_page.py; src/transcription/services/documents.py; tests/ui/test_documents_page.py	Document detail now shows linked people plus document-scoped Sources and Jobs navigation for the current document.
Update entry, validation, and author linkage	UP-1, UP-2, UP-3, UP-4, UP-5, UP-6	Implemented	src/transcription/ui/pages/documents_page.py; src/transcription/services/documents.py; tests/ui/test_documents_page.py; tests/services/test_document_service.py	Dedicated edit page includes required-field validation messaging, date parsing rules, and author relationship selection with save path routed back to document detail.
Delete controls and guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Implemented	src/transcription/ui/pages/documents_page.py; src/transcription/services/documents.py; tests/ui/test_documents_page.py; tests/services/test_document_service.py	Dedicated delete page provides permanent-action confirmation, dependency-category blocking, and guarded backend delete behavior.

Person

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create flow and validation	CR-1, CR-2, CR-3, CR-4, CR-5	Implemented	src/transcription/ui/pages/people_page.py; src/transcription/services/documents.py; tests/ui/test_people_page.py	Dedicated Person create page with required full_name validation, optional field handling, and success routing to detail.
Read detail and linked documents	RD-1, RD-2, RD-3, RD-4	Implemented	src/transcription/ui/pages/people_page.py; src/transcription/services/documents.py; tests/ui/test_people_page.py; tests/services/test_document_service.py	Person detail route renders metadata, full-name summary, portrait preview when available, linked-document section, and invalid/missing-id states.
Update behavior	UP-1, UP-2, UP-3, UP-4, UP-5	Implemented	src/transcription/ui/pages/people_page.py; src/transcription/services/documents.py; tests/ui/test_people_page.py; tests/services/test_document_service.py	Dedicated Person edit page supports allowed fields, required full_name validation, and save path back to detail.
Delete behavior and guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Implemented	src/transcription/ui/pages/people_page.py; src/transcription/services/documents.py; tests/ui/test_people_page.py; tests/services/test_document_service.py	Dedicated delete page provides permanent-action confirmation, linked-document blocking message, and guarded backend delete behavior.

Source

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create entry and required links	CR-1, CR-2, CR-4, CR-5	Implemented	src/transcription/services/store.py; src/transcription/ui/pages/jobs_page.py; src/transcription/ui/pages/upload_page.py; tests/services/test_store.py; tests/ui/test_jobs_page.py	Source upload/create is job-create-context only (legacy upload route redirects), with required Document and JobSource linkage enforced.
Ordering and filename policy	CR-3	Implemented	src/transcription/services/store.py; tests/services/test_store.py; tests/ui/test_jobs_page.py	Multi-file/folder uploads are ordered alphabetically by original filename, helper text is visible, and stored filenames use generated unique-id plus extension.
Read and navigation visibility	RD-1, RD-2, RD-3	Partial	src/transcription/ui/pages/documents_page.py; src/transcription/ui/pages/jobs_page.py; tests/ui/test_documents_page.py; tests/ui/test_jobs_page.py	Source list context is now document-scoped and job detail is link-oriented; source preview and revision surfaces are deferred.
Revision update behavior	UP-1, UP-2, UP-3, UP-4	Planned	src/transcription/services/transcription.py; tests/services/test_transcription_service.py	Revised text service support remains, but the current UI does not expose the editor.
Delete and dependency guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/transcription.py; tests/services/test_transcription_service.py	Job-detail source delete UI was removed from the current simplified flow; backend guardrails remain for future reinstatement.

Job

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create entry and required links	CR-1, CR-2, CR-5, CR-6	Implemented	src/transcription/services/store.py; src/transcription/ui/pages/jobs_page.py; tests/ui/test_jobs_page.py; tests/services/test_store.py	Jobs list now has explicit Create entry and /jobs/new create flow with Document selection, combined file/folder upload widget, and submit routing to job detail.
Source ordering and upload behavior	CR-3	Implemented	src/transcription/services/store.py; src/transcription/ui/pages/jobs_page.py; tests/services/test_store.py; tests/ui/test_jobs_page.py	Multi-file and folder upload are supported through one widget, uploads are sorted alphabetically by original filename, and helper guidance is shown in create UI.
Provider/model/prompt visibility	CR-4, RD-4	Implemented	src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py; tests/ui/test_jobs_page.py	Provider/model/prompt fields are visible in create and detail flows when known (with pending fallback labels).
Jobs list and detail read states	RD-1, RD-2, RD-3, RD-5	Implemented	src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; tests/ui/test_jobs_page.py	Jobs list, detail route, document-scoped navigation, and invalid/missing id states are present.
Revision update behavior	UP-1, UP-2, UP-3, UP-4	Planned	src/transcription/services/transcription.py; tests/services/test_transcription_service.py	Revision editing service support remains, but the current UI no longer exposes the editor.
Lifecycle visibility and retry indicators	UP-5	Implemented	src/transcription/services/jobs.py; src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py; tests/ui/test_jobs_page.py	Job detail now surfaces lifecycle status plus retry/update metadata while lifecycle fields remain system-managed (no direct user edit controls).
Delete and dependency guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/jobs.py; tests/services/test_job_service.py	Job delete UI is deferred in the current simplified flow.

Quality Gate Coverage

Quality Gate	Acceptance IDs	Status	Notes
Separation of intent vs implementation	QG-1 across entities	Implemented	user-journey.md, schema-mapping.md, and acceptance-criteria.md are maintained per entity.
Traceability from criteria to implementation	QG-2 across entities	Implemented	This matrix provides criterion-to-code anchors and current status tags.
First-release constraints	QG-3 across entities	Implemented	Constraints are documented and aligned with current flows: jobs-first source upload, visible provider/model/prompt context, and system-managed lifecycle fields.

Supporting Entity Coverage

Supporting Entity	Documentation	Status	Notes
document-person	docs/ui/entities/document-person/schema-mapping.md	Completed	Supporting-entity schema mapping created; no standalone UI contract file by design.
job-source	docs/ui/entities/job-source/schema-mapping.md	Completed	Supporting-entity schema mapping created; no standalone UI contract file by design.

Suggested Implementation Order

1. Aggregate final acceptance review across Document, Person, Source, and Job criteria.

Aggregate Final Review Snapshot (2026-08-02)

Entity	Acceptance IDs still not fully met	Evidence	Notes
Document	None	src/transcription/ui/pages/documents_page.py; tests/ui/test_documents_page.py	Document criteria are covered by dedicated detail/edit/delete pages and document-scoped related views.
Person	None	src/transcription/ui/pages/people_page.py; tests/ui/test_people_page.py	Person criteria are covered by dedicated create/detail/edit/delete pages with relationship-aware delete guardrails.
Source	None	src/transcription/services/store.py; src/transcription/ui/pages/jobs_page.py; tests/services/test_store.py; tests/services/test_transcription_service.py	Source criteria are covered by job-context create behavior, ordering/filename policy, revision flow, and delete guardrails.
Job	None	src/transcription/ui/pages/jobs_page.py; src/transcription/services/jobs.py; tests/ui/test_jobs_page.py; tests/services/test_job_service.py	Job criteria are covered by create/read/revision/lifecycle visibility and delete guardrails in dedicated routes.