generated from john/python-template
81 lines
2.4 KiB
Markdown
81 lines
2.4 KiB
Markdown
# UI Documentation
|
|
|
|
This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.
|
|
|
|
## Document Types
|
|
|
|
### user-journey.md
|
|
|
|
A product and UX contract for a user-facing entity.
|
|
|
|
Use this document to describe:
|
|
- what the user is trying to do
|
|
- which screen or action starts the workflow
|
|
- which fields the user sees and edits
|
|
- validation rules
|
|
- expected success and failure outcomes
|
|
- where the user goes next
|
|
|
|
### schema-mapping.md
|
|
|
|
A field-level mapping between schema, UI, and implementation.
|
|
|
|
Use this document to describe:
|
|
- the authoritative schema fields for an entity
|
|
- which fields are shown, hidden, editable, or system-managed
|
|
- current implementation behavior
|
|
- intended target behavior
|
|
- implementation gaps between current code and intended UX
|
|
|
|
### acceptance-criteria.md
|
|
|
|
An implementation-ready checklist for CRUD behavior and quality gates.
|
|
|
|
Use this document to describe:
|
|
- testable acceptance statements by flow (Create, Read, Update, Delete)
|
|
- success and failure behaviors
|
|
- first-release constraints
|
|
- cross-criteria quality gates
|
|
|
|
### traceability-matrix.md
|
|
|
|
A criteria-to-code mapping that identifies implementation anchors and status.
|
|
|
|
Use this document to describe:
|
|
- acceptance criteria group to implementation file mapping
|
|
- delivery status (implemented, partial, planned)
|
|
- ordered implementation priorities
|
|
|
|
## Organization Rules
|
|
|
|
- Store documents under `docs/ui/entities/<entity-name>/`.
|
|
- Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
|
|
- Create `acceptance-criteria.md` for user-facing entities.
|
|
- Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
|
|
- Keep one shared `traceability-matrix.md` under `docs/ui/entities/` to map criteria to implementation anchors.
|
|
- Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
|
|
|
|
## Current Entity Plan
|
|
|
|
User-facing entities:
|
|
- `document`
|
|
- `person`
|
|
- `source`
|
|
- `job`
|
|
|
|
Supporting entities:
|
|
- `document-person`
|
|
- `job-source`
|
|
|
|
## Relationship to Core Docs
|
|
|
|
These UI docs complement, but do not replace:
|
|
- `docs/schema_v2.md`
|
|
- `docs/requirements_v2.md`
|
|
- `docs/architecture_v2.md`
|
|
|
|
When there is a conflict:
|
|
- schema definitions come from the database model and schema docs
|
|
- user interaction intent comes from the user-journey docs
|
|
- implementation truth comes from code and is recorded in schema-mapping docs as current-state evidence
|