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	Planned	src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; src/transcription/ui/components/transcript.py	No dedicated Document detail page yet; Document metadata is not rendered as first-class UI.
Related sections and empty states	RD-3, RD-4, RD-5, RD-6	Planned	src/transcription/ui/pages/jobs_page.py	Document-scoped related sections are defined in docs, not yet implemented in a dedicated Document view.
Update entry and validation	UP-1, UP-2, UP-3, UP-4, UP-5, UP-6	Planned	src/transcription/services/documents.py	Service update path exists; no dedicated Document edit UI flow yet.
Delete controls and guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/documents.py	Service delete path exists; no UI delete control or dependency guard UX yet.

Person

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create flow and validation	CR-1, CR-2, CR-3, CR-4, CR-5	Planned	src/transcription/services/documents.py	Person create service exists; no dedicated Person page/form yet.
Read detail and linked documents	RD-1, RD-2, RD-3, RD-4	Planned	src/transcription/services/documents.py; src/transcription/ui	No dedicated Person detail UI in current pages.
Update behavior	UP-1, UP-2, UP-3, UP-4, UP-5	Planned	src/transcription/services/documents.py	Service update exists; no first-class Person edit surface yet.
Delete behavior and guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/documents.py	Service delete exists; relationship-aware UI guard flow is not implemented.

Source

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create entry and required links	CR-1, CR-2, CR-4, CR-5	Partial	src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py	Upload flow creates Document, Job, Source, and JobSource together; first-release job-context-only Source create intent is documented but not exposed as dedicated Source create UI.
Ordering and filename policy	CR-3	Partial	src/transcription/services/store.py	Current implementation persists generated filenames and assigns page_number in upload flow; target policy requires strict alphabetical ordering guidance and UUID.extension convention.
Read and revision visibility	RD-1, RD-2, RD-3	Implemented	src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/job_detail.py; src/transcription/ui/components/transcript.py	Source preview and revision context are available primarily in job detail flow.
Revision update behavior	UP-1, UP-2, UP-3, UP-4	Implemented	src/transcription/services/transcription.py; src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py	Revised text editing and save feedback path exists in job detail revision flow.
Delete and dependency guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/transcription.py	Source delete service path exists; dedicated UI delete control and guardrail messaging are not implemented.

Job

Criteria Group	Acceptance IDs	Status	Primary Implementation Anchors	Notes
Create entry and required links	CR-1, CR-2, CR-5, CR-6	Partial	src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py; src/transcription/ui/pages/jobs_page.py	Current create path is upload-first and implicit; target requires explicit Create job flow from Jobs page.
Source ordering and upload behavior	CR-3	Partial	src/transcription/services/store.py	Current upload path is single-file create and uses service-assigned page defaults; target requires multi-file or folder handling with alphabetical ordering guidance.
Provider/model/prompt visibility	CR-4, RD-4	Partial	src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py	Values are populated in workflow updates but not rendered as first-class fields in current job detail.
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, and invalid/missing id states are present.
Revision update behavior	UP-1, UP-2, UP-3, UP-4	Implemented	src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py; src/transcription/services/transcription.py	Revision editing and save feedback exist in job detail source context.
Lifecycle visibility and retry indicators	UP-5	Partial	src/transcription/services/jobs.py; src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py	Status and retry_count are visible, but lifecycle controls remain system-managed and create-mode visibility targets are still pending.
Delete and dependency guardrails	DL-1, DL-2, DL-3, DL-4, DL-5	Planned	src/transcription/services/jobs.py	Backend delete exists; dedicated UI delete flow and policy messaging are not implemented.

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	Partial	Constraints are documented for Document, Person, Source, and Job; implementation remains mixed across entities.

Suggested Implementation Order

1. Document: add dedicated detail/read surface and metadata rendering.
2. Document: add edit and delete UI with dependency guardrails.
3. Person: add create/read/update/delete pages and relationship-aware delete constraints.
4. Job: add explicit Create job flow from Jobs page with Document selection and source upload controls.
5. Job: render provider/model/prompt_name visibility in create and detail when known.
6. Source: align create flow behavior with documented job-context-only invariant and ordering/filename policy.
7. Source: add delete UI with dependency checks and blocked-delete guidance.