Daniel Covington
hace 3 días
commit
2484a48e28
Se han modificado 30 ficheros con 5914 adiciones y 0 borrados
Dividir vista
Opciones de diferencias
-
+5 -0.gitignore
-
+24 -0Initial Description.txt
-
+119 -0Initial Documents/Access_Schema.txt
-
BINInitial Documents/Client Database Plan.xlsx
-
+105 -0_bmad-output/implementation-artifacts/1-1-project-initialization-solution-scaffold.md
-
+67 -0_bmad-output/implementation-artifacts/1-10-municipality-account-profile.md
-
+67 -0_bmad-output/implementation-artifacts/1-11-municipality-operational-addresses.md
-
+67 -0_bmad-output/implementation-artifacts/1-12-municipality-service-contacts.md
-
+64 -0_bmad-output/implementation-artifacts/1-13-municipality-prior-cycle-service-defaults-view.md
-
+69 -0_bmad-output/implementation-artifacts/1-2-workspace-shell-ant-design-foundation.md
-
+68 -0_bmad-output/implementation-artifacts/1-3-keycloak-realm-configuration-oidc-integration.md
-
+67 -0_bmad-output/implementation-artifacts/1-4-keycloak-role-mapping-application-authorization.md
-
+68 -0_bmad-output/implementation-artifacts/1-5-shared-audit-logging-infrastructure.md
-
+67 -0_bmad-output/implementation-artifacts/1-6-legacy-anti-corruption-data-access-layer.md
-
+68 -0_bmad-output/implementation-artifacts/1-7-legacy-schema-compatibility-validation-gate.md
-
+67 -0_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md
-
+68 -0_bmad-output/implementation-artifacts/1-9-seed-system-reference-values-rule-defaults.md
-
+102 -0_bmad-output/implementation-artifacts/sprint-status.yaml
-
+204 -0_bmad-output/planning-artifacts/architecture.md
-
+236 -0_bmad-output/planning-artifacts/client-database-plan-extract.txt
-
+1446 -0_bmad-output/planning-artifacts/epics.md
-
+290 -0_bmad-output/planning-artifacts/implementation-readiness-report-2026-05-05.md
-
+397 -0_bmad-output/planning-artifacts/prd.md
-
+270 -0_bmad-output/planning-artifacts/sprint-change-proposal-2026-05-05.md
-
+98 -0_bmad-output/planning-artifacts/ux-color-themes.html
-
+451 -0_bmad-output/planning-artifacts/ux-design-directions.html
-
+871 -0_bmad-output/planning-artifacts/ux-design-specification.md
-
+450 -0_bmad-output/planning-artifacts/validation-report-2026-04-03.md
-
+6 -0docs/index.md
-
+33 -0docs/source-2026-08-primary-ballot-envelope-tracking.md
+ 5
- 0
.gitignore
Ver fichero
| @@ -0,0 +1,5 @@ | |||
| _bmad/ | |||
| .agents/ | |||
| .claude/ | |||
| gitea_token | |||
| package-lock.json | |||
+ 24
- 0
Initial Description.txt
Ver fichero
| @@ -0,0 +1,24 @@ | |||
| looking at the Client Database Plan.xlsx and Access_Schema.txt in the Initial Documents Folder , We want build a municipality election-services and job-tracking application that modernizes an existing Access-based production system. The goal is to keep as much of the current schema and workflow as possible while extending it to better support client account management, election-specific planning, service configuration, scheduling, production tracking, and operational reporting. The application must handle both permanent municipality data and recurring election-cycle work, including addressing, sorting, blue envelopes, office copies, transportation, contacts, key dates, and production details. We dont want to add or delete anything from the original tables in access we can make new tables and queries that join the tables via and ID field | |||
| Continue the `$bmad-create-architecture` workflow from where we left off in `C:\Users\danielc.NTP\Desktop\Brians Client Route Reports App`. | |||
| Current status: | |||
| - `Step 3` is already approved and saved in `_bmad-output/planning-artifacts/architecture.md` (with `stepsCompleted: [1,2,3]`). | |||
| - We were at `Step 4: Core Architectural Decisions`. | |||
| - You already drafted Step 4 and were waiting for A/P/C. | |||
| - Treat this message as my choice: `C` (continue/save Step 4), then move to Step 5. | |||
| Important confirmed constraints/preferences: | |||
| - Legacy Access tables are immutable (no add/delete/alter on original Access tables). | |||
| - New capabilities must be extension tables + join queries/views by ID fields. | |||
| - Election-cycle entities are separate from permanent municipality entities. | |||
| - Desktop PC only (no tablet support). | |||
| - Stack preference: .NET 10 ASP backend + TypeScript-first React frontend. | |||
| Please: | |||
| 1) Save finalized Step 4 to `_bmad-output/planning-artifacts/architecture.md`. | |||
| 2) Update frontmatter `stepsCompleted` to include `4`. | |||
| 3) Load Step 5 and continue with normal A/P/C workflow. | |||
| 4) Show me the Step 5 draft and menu. | |||
+ 119
- 0
Initial Documents/Access_Schema.txt
Ver fichero
| @@ -0,0 +1,119 @@ | |||
| Table: Colors | |||
| ------------- | |||
| Column: Filepath Type: 130 Size: 255 Nullable: True | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: Name Type: 130 Size: 255 Nullable: True | |||
| Table: Contacts | |||
| --------------- | |||
| Column: BUSINESS_ADDRESS Type: 130 Size: 255 Nullable: True | |||
| Column: BUSINESS_ADDRESS2 Type: 130 Size: 255 Nullable: True | |||
| Column: BUSINESS_ADDRESS3 Type: 130 Size: 255 Nullable: True | |||
| Column: CONTACT_NAME Type: 130 Size: 255 Nullable: True | |||
| Column: EMAIL Type: 130 Size: 255 Nullable: True | |||
| Column: FAXNUM Type: 5 Size: Nullable: True | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: JURISCODE Type: 130 Size: 255 Nullable: True | |||
| Column: MAILING_ADDRESS Type: 130 Size: 255 Nullable: True | |||
| Column: MAILING_ADDRESS2 Type: 130 Size: 255 Nullable: True | |||
| Column: MAILING_ADDRESS3 Type: 130 Size: 255 Nullable: True | |||
| Column: PHONENUM1 Type: 130 Size: 255 Nullable: True | |||
| Column: PHONENUM2 Type: 130 Size: 255 Nullable: True | |||
| Column: RESIDENTIAL_ADDRESS Type: 130 Size: 255 Nullable: True | |||
| Column: RESIDENTIAL_ADDRESS2 Type: 130 Size: 255 Nullable: True | |||
| Column: RESIDENTIAL_ADDRESS3 Type: 130 Size: 255 Nullable: True | |||
| Column: TITLE Type: 130 Size: 255 Nullable: True | |||
| Column: TownshipName Type: 130 Size: 255 Nullable: True | |||
| Column: TownshipNum Type: 130 Size: 255 Nullable: True | |||
| Table: CustomOfficeCopyJob | |||
| -------------------------- | |||
| Column: Amount Type: 3 Size: Nullable: True | |||
| Column: Donedate Type: 7 Size: Nullable: True | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: Jcode Type: 130 Size: 15 Nullable: True | |||
| Column: Precinct Type: 130 Size: 20 Nullable: True | |||
| Column: StartingBallotNumber Type: 3 Size: Nullable: True | |||
| Column: Status Type: 130 Size: 100 Nullable: True | |||
| Table: InkjetRecords | |||
| -------------------- | |||
| Column: ADDRESS1 Type: 130 Size: 255 Nullable: True | |||
| Column: ADDRESS2 Type: 130 Size: 255 Nullable: True | |||
| Column: ADDRESS3 Type: 130 Size: 255 Nullable: True | |||
| Column: ADDRESS4 Type: 130 Size: 255 Nullable: True | |||
| Column: ADDRESS5 Type: 130 Size: 255 Nullable: True | |||
| Column: APPRETURNED Type: 130 Size: 255 Nullable: True | |||
| Column: APPSENT Type: 130 Size: 255 Nullable: True | |||
| Column: BALLOT_NUMBER Type: 130 Size: 255 Nullable: True | |||
| Column: BALRETURNED Type: 130 Size: 255 Nullable: True | |||
| Column: BALSENT Type: 130 Size: 255 Nullable: True | |||
| Column: CassADDRESS1 Type: 130 Size: 255 Nullable: True | |||
| Column: CassADDRESS2 Type: 130 Size: 255 Nullable: True | |||
| Column: CassADDRESS3 Type: 130 Size: 255 Nullable: True | |||
| Column: CassADDRESS4 Type: 130 Size: 255 Nullable: True | |||
| Column: CassADDRESS5 Type: 130 Size: 255 Nullable: True | |||
| Column: ColorId Type: 3 Size: Nullable: True | |||
| Column: CountingBoard Type: 130 Size: 255 Nullable: True | |||
| Column: EMAILADDRESS Type: 130 Size: 255 Nullable: True | |||
| Column: FIRSTNAME Type: 130 Size: 255 Nullable: True | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: KitID Type: 3 Size: Nullable: True | |||
| Column: KitLabelID Type: 3 Size: Nullable: True | |||
| Column: LASTNAME Type: 130 Size: 255 Nullable: True | |||
| Column: MIDDLENAME Type: 130 Size: 255 Nullable: True | |||
| Column: PHONENUMBER Type: 130 Size: 255 Nullable: True | |||
| Column: PRECINCT Type: 130 Size: 255 Nullable: True | |||
| Column: SUFFIX Type: 130 Size: 255 Nullable: True | |||
| Column: UOCAVASTATUS Type: 130 Size: 255 Nullable: True | |||
| Column: VOTERID Type: 130 Size: 255 Nullable: True | |||
| Table: Jurisdiction | |||
| ------------------- | |||
| Column: CSZ Type: 130 Size: 255 Nullable: True | |||
| Column: IMB Type: 130 Size: 255 Nullable: True | |||
| Column: IMB_Digits Type: 130 Size: 255 Nullable: True | |||
| Column: JCode Type: 130 Size: 10 Nullable: False | |||
| Column: Mailing_Address Type: 130 Size: 255 Nullable: True | |||
| Column: Name Type: 130 Size: 255 Nullable: True | |||
| Table: Kit | |||
| ---------- | |||
| Column: Cass Type: 11 Size: 2 Nullable: False | |||
| Column: CreatedOn Type: 7 Size: Nullable: True | |||
| Column: ExportedToSnailWorks Type: 7 Size: Nullable: True | |||
| Column: Filename Type: 130 Size: 100 Nullable: True | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: InboundSTID Type: 130 Size: 20 Nullable: True | |||
| Column: InkJetJob Type: 11 Size: 2 Nullable: False | |||
| Column: Jcode Type: 130 Size: 255 Nullable: True | |||
| Column: JobNumber Type: 130 Size: 255 Nullable: True | |||
| Column: JobType Type: 130 Size: 50 Nullable: True | |||
| Column: LabelsPrinted Type: 7 Size: Nullable: True | |||
| Column: OfficeCopiesAmount Type: 3 Size: Nullable: True | |||
| Column: OutboundSTID Type: 130 Size: 20 Nullable: True | |||
| Column: Status Type: 130 Size: 100 Nullable: True | |||
| Table: KitLabels | |||
| ---------------- | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: InBoundIMB Type: 130 Size: 255 Nullable: True | |||
| Column: InBoundIMBDigits Type: 130 Size: 255 Nullable: True | |||
| Column: INBOUNDIMBPNG Type: 130 Size: 0 Nullable: True | |||
| Column: InBoundSerial Type: 130 Size: 255 Nullable: True | |||
| Column: KitID Type: 3 Size: Nullable: True | |||
| Column: OutboundIMB Type: 130 Size: 255 Nullable: True | |||
| Column: OutboundIMBDigits Type: 130 Size: 255 Nullable: True | |||
| Column: OutboundIMBPNG Type: 130 Size: 0 Nullable: True | |||
| Column: OutboundSerial Type: 130 Size: 255 Nullable: True | |||
| Column: SetNumber Type: 5 Size: Nullable: True | |||
| Table: meta_migrations | |||
| ---------------------- | |||
| Column: version Type: 3 Size: Nullable: False | |||
| Table: Settings | |||
| --------------- | |||
| Column: ID Type: 3 Size: Nullable: False | |||
| Column: Name Type: 130 Size: 255 Nullable: True | |||
| Column: Value Type: 130 Size: 255 Nullable: True | |||
BIN
Initial Documents/Client Database Plan.xlsx
Ver fichero
+ 105
- 0
_bmad-output/implementation-artifacts/1-1-project-initialization-solution-scaffold.md
Ver fichero
| @@ -0,0 +1,105 @@ | |||
| # Story 1.1: Project Initialization & Solution Scaffold | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a developer, | |||
| I want the solution scaffolded with ASP.NET Core 10 Web API and Vite React TypeScript, | |||
| so that the team has a working, runnable baseline with the correct project structure for all subsequent stories. | |||
| ## Acceptance Criteria | |||
| 1. Given the initialization commands are run (`dotnet new sln`, `dotnet new webapi`, `npm create vite@latest --template react-ts`) when the solution builds, then both `BriansClientRouteReports.Server` and `brians-client-route-reports-client` compile without errors. | |||
| 2. Given the solution is running locally, when the Vite dev server starts, then the React app loads at the configured local URL with no console errors. | |||
| 3. Given the server is running, when `GET /health` is called, then it returns `200 OK` with a status payload. | |||
| 4. Given the solution structure is created, when reviewed against the architecture decision, then the `.sln` file, server project folder, and client project folder exist at expected paths and `.gitignore` excludes `node_modules`, `bin`, `obj`, and `.env` files. | |||
| ## Tasks / Subtasks | |||
| - [ ] Create baseline solution and projects (AC: 1, 4) | |||
| - [ ] Run `dotnet new sln -n brians-client-route-reports` at repo root. | |||
| - [ ] Run `dotnet new webapi -n BriansClientRouteReports.Server -f net10.0 --use-controllers`. | |||
| - [ ] Add server project to solution: `dotnet sln add .\\BriansClientRouteReports.Server\\BriansClientRouteReports.Server.csproj`. | |||
| - [ ] Run `npm create vite@latest brians-client-route-reports-client -- --template react-ts`. | |||
| - [ ] Add operational baseline hardening files (AC: 4) | |||
| - [ ] Add/update root `.gitignore` with `.env`, `node_modules/`, `bin/`, `obj/`, and common build artifacts. | |||
| - [ ] Ensure folders are exactly: | |||
| - `./BriansClientRouteReports.Server/` | |||
| - `./brians-client-route-reports-client/` | |||
| - `./brians-client-route-reports.sln` | |||
| - [ ] Implement health endpoint (AC: 3) | |||
| - [ ] Ensure server exposes `GET /health` returning JSON payload and HTTP 200. | |||
| - [ ] Add lightweight server integration check for `/health` response shape and status. | |||
| - [ ] Verify local run and build paths (AC: 1, 2, 3) | |||
| - [ ] Validate `dotnet build` succeeds for server and solution. | |||
| - [ ] Validate client install and dev start (`npm install`, `npm run dev`) succeeds with no runtime console errors on first render. | |||
| - [ ] Capture exact run commands in README or implementation notes for handoff. | |||
| ## Dev Notes | |||
| - This story is the implementation foundation for all subsequent stories in Epic 1. | |||
| - Do not add domain models, workflow logic, or auth integration here; keep scope to scaffold + health + runnability. | |||
| - Preserve architecture separation: independent server and client lifecycle with explicit boundary. | |||
| ### Technical Requirements | |||
| - Backend stack: ASP.NET Core 10 Web API (`net10.0`) with controllers template option enabled. | |||
| - Frontend stack: Vite + React + TypeScript (`react-ts`). | |||
| - Node requirement from Vite docs: Node.js `20.19+` or `22.12+`. | |||
| - Must retain ability to run server/client independently in local development. | |||
| ### Architecture Compliance | |||
| - Use selected starter architecture exactly as documented. | |||
| - Keep immutable-legacy policy in mind: this story must not introduce data-layer assumptions that alter legacy schemas. | |||
| - Keep future role-based and UX work unblocked by maintaining clean folder and naming patterns. | |||
| ### File Structure Requirements | |||
| - Required outputs: | |||
| - `brians-client-route-reports.sln` | |||
| - `BriansClientRouteReports.Server/BriansClientRouteReports.Server.csproj` | |||
| - `brians-client-route-reports-client/package.json` | |||
| - Keep server and client sibling directories at repo root. | |||
| ### Testing Requirements | |||
| - Minimum for this story: | |||
| - Build verification (`dotnet build` and client install/run). | |||
| - Health endpoint verification (`GET /health` returns `200` and JSON payload). | |||
| - Smoke-level client render check (no console errors on first load). | |||
| ### Project Structure Notes | |||
| - This repository currently centers planning artifacts in `_bmad-output/planning-artifacts`. | |||
| - Implementation outputs for stories are stored in `_bmad-output/implementation-artifacts`. | |||
| - Keep story-driven changes traceable and avoid editing planning docs during implementation unless explicitly requested. | |||
| ### References | |||
| - Story source and ACs: `_bmad-output/planning-artifacts/epics.md` (Story 1.1 section) | |||
| - Starter commands and rationale: `_bmad-output/planning-artifacts/architecture.md` (Selected Starter section) | |||
| - UX/build context and component roadmap: `_bmad-output/planning-artifacts/ux-design-specification.md` (Implementation Roadmap / Component Strategy) | |||
| - Vite CLI and template usage + Node version: https://vite.dev/guide/ | |||
| - .NET template behavior and options (`webapi`, `--use-controllers`, `net10.0`): https://learn.microsoft.com/dotnet/core/tools/dotnet-new-sdk-templates | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Sprint source file: `_bmad-output/implementation-artifacts/sprint-status.yaml` | |||
| - Requirement source files: `epics.md`, `architecture.md`, `ux-design-specification.md` | |||
| ### Completion Notes List | |||
| - Comprehensive context generated for Story 1.1 with explicit guardrails, commands, and scope boundaries. | |||
| - Story is intentionally constrained to scaffold readiness and health-check baseline. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-1-project-initialization-solution-scaffold.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-10-municipality-account-profile.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.10: Municipality Account Profile | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a client services staff member, | |||
| I want to create and maintain municipality account profiles linked to legacy jurisdiction identifiers, | |||
| so that permanent municipality data is managed in the extension layer without modifying legacy Access tables. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a client services user navigates to municipality management **When** they create a new municipality profile **Then** it is saved to the extension layer with a required link to a valid legacy jurisdiction identifier (ID/JCode) | |||
| 2. **Given** a municipality profile is created **When** the profile is loaded **Then** the anti-corruption layer resolves the legacy join and displays combined extension and legacy data together in the workspace grid | |||
| 3. **Given** a profile field is updated **When** saved **Then** the change is recorded in the audit log with actor identity and timestamp | |||
| 4. **Given** a user attempts to create a profile without a valid legacy jurisdiction identifier **When** the form is submitted **Then** the save is rejected with a clear validation message identifying the required legacy link **And** no INSERT, UPDATE, or DELETE operations are performed on legacy Access tables at any point | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.10) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-10-municipality-account-profile.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-11-municipality-operational-addresses.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.11: Municipality Operational Addresses | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a client services staff member, | |||
| I want to store and update municipality operational mailing and delivery addresses, | |||
| so that election services reference current address information without depending on legacy records. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a municipality profile exists **When** a client services user adds an address **Then** they can specify mailing or delivery address type, and the record is saved to the extension address table linked to the municipality profile | |||
| 2. **Given** an address is updated **When** saved **Then** the previous address is preserved in history, the new address is marked as current, and the change is logged with actor and timestamp | |||
| 3. **Given** an address record is saved **When** retrieved **Then** it includes address type, street, city, state, zip, and effective date fields | |||
| 4. **Given** a municipality profile is viewed **When** addresses are displayed **Then** mailing and delivery addresses are shown with clear type labels and current/historical status | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.11) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-11-municipality-operational-addresses.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-12-municipality-service-contacts.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.12: Municipality Service Contacts | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a client services staff member, | |||
| I want to manage municipality service-contact records including primary and secondary contacts, | |||
| so that the right people can be reached during election operations without consulting legacy records. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a municipality profile exists **When** a client services user adds a contact **Then** they can designate it as primary or secondary contact and save name, role/title, phone, and email | |||
| 2. **Given** a municipality has both a primary and secondary contact **When** the profile is viewed **Then** both contacts are displayed with clear primary/secondary designation labels | |||
| 3. **Given** a contact is updated or removed **When** the change is saved **Then** it is recorded in the audit log with actor identity and timestamp | |||
| 4. **Given** a user attempts to save a contact without required fields (name, contact type) **When** the form is submitted **Then** the save is rejected with inline validation errors identifying the missing fields | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.12) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-12-municipality-service-contacts.md` | |||
+ 64
- 0
_bmad-output/implementation-artifacts/1-13-municipality-prior-cycle-service-defaults-view.md
Ver fichero
| @@ -0,0 +1,64 @@ | |||
| # Story 1.13: Municipality Prior-Cycle Service Defaults View | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a client services staff member, | |||
| I want to view municipality-specific service defaults from prior election cycles as a read-only reference, | |||
| so that I can reference proven configurations when setting up new election-cycle jobs in Epic 2. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a municipality has at least one completed election-cycle job **When** a client services user views the prior-cycle defaults panel **Then** the most recent cycle's service configurations are displayed as read-only reference data | |||
| 2. **Given** a municipality has multiple prior cycles **When** the defaults panel is viewed **Then** the most recent cycle is shown by default with a cycle selector control to navigate older cycles | |||
| 3. **Given** no prior cycles exist for a municipality **When** defaults are requested **Then** the system displays a clear "No prior cycle defaults available" state with guidance to create the first cycle **And** all data in this view is read-only — the apply-to-new-job action is out of scope for this story and delivered in Epic 2 (Story 2.4) | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.13) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-13-municipality-prior-cycle-service-defaults-view.md` | |||
+ 69
- 0
_bmad-output/implementation-artifacts/1-2-workspace-shell-ant-design-foundation.md
Ver fichero
| @@ -0,0 +1,69 @@ | |||
| # Story 1.2: Workspace Shell & Ant Design Foundation | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a any authenticated user, | |||
| I want a consistent tri-pane application layout with the Ant Design visual system applied, | |||
| so that I have a predictable, accessible, and keyboard-navigable operational environment from day one. | |||
| ## Acceptance Criteria | |||
| 1. **Given** the app loads after authentication **When** an authenticated user enters the application **Then** the tri-pane layout renders with a left navigation pane, center content area, and collapsible right panel | |||
| 2. **Given** the Ant Design token configuration is applied **When** the UI renders **Then** colorPrimary is #1F4E79, teal secondary is #0F766E, semantic status colors (success/warning/error/info/overdue) match the UX spec, and compact density profile is active (UX-DR1) | |||
| 3. **Given** a user interacts with any focusable element **When** tabbing through the interface **Then** visible 2px focus indicators are present on all interactive elements with logical tab order (UX-DR9) | |||
| 4. **Given** the viewport is 1280–1599px **When** the layout renders **Then** the right panel is collapsible and the tri-pane adapts to compact mode (UX-DR15) | |||
| 5. **Given** the viewport is below 1280px **When** the layout renders **Then** a reduced read mode with a support notice is displayed and full editing is not available | |||
| 6. **Given** any status indicator renders **When** viewed **Then** status is conveyed with both color and a text label or icon — never color alone (UX-DR12) | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.2) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-2-workspace-shell-ant-design-foundation.md` | |||
+ 68
- 0
_bmad-output/implementation-artifacts/1-3-keycloak-realm-configuration-oidc-integration.md
Ver fichero
| @@ -0,0 +1,68 @@ | |||
| # Story 1.3: Keycloak Realm Configuration & OIDC Integration | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a any team member, | |||
| I want to authenticate using Keycloak single sign-on via OpenID Connect, | |||
| so that I can securely access the application with my organizational credentials. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a user navigates to the application while unauthenticated **When** they load any protected route **Then** they are redirected to the Keycloak login page for the configured realm | |||
| 2. **Given** a user enters valid Keycloak credentials **When** authentication succeeds **Then** they receive a JWT access token, are redirected to their role-specific workspace, and the authentication event is logged to the audit service within 5 seconds (NFR7) | |||
| 3. **Given** a user's access token expires **When** they make an authenticated request **Then** the refresh token flow silently renews the session or redirects to login if the refresh token is also expired | |||
| 4. **Given** an invalid or expired token is presented to the API **When** the request is processed **Then** the API returns 401 Unauthorized and the failed authentication attempt is captured in the audit log | |||
| 5. **Given** the application is deployed **When** traffic is inspected **Then** all communication is over TLS 1.2+ (NFR4) and sensitive token data is not exposed in URLs or logs | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.3) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-3-keycloak-realm-configuration-oidc-integration.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-4-keycloak-role-mapping-application-authorization.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.4: Keycloak Role Mapping & Application Authorization | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a developer, | |||
| I want Keycloak roles mapped to application permission policies enforced on API routes and frontend features, | |||
| so that each user sees only the capabilities appropriate to their operational role. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a Keycloak user has the ClientServices role **When** they authenticate and navigate **Then** they can access municipality profile and election-cycle creation routes and cannot access admin-only or production-only routes | |||
| 2. **Given** a Keycloak user has the Admin role **When** they authenticate **Then** they can access all application routes including admin-sensitive functions | |||
| 3. **Given** a user without a recognized application role authenticates **When** they access any protected route **Then** they receive 403 Forbidden and the unauthorized access attempt is logged with actor identity | |||
| 4. **Given** a privileged operation is performed **When** it completes **Then** the authorization check result, actor, and resource are captured by the audit logging service within 5 seconds (NFR6, NFR7) **And** roles ClientServices, Production, Transportation, Support, and Admin are managed entirely in Keycloak Admin Console — FR27 is satisfied without a custom role management UI | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.4) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-4-keycloak-role-mapping-application-authorization.md` | |||
+ 68
- 0
_bmad-output/implementation-artifacts/1-5-shared-audit-logging-infrastructure.md
Ver fichero
| @@ -0,0 +1,68 @@ | |||
| # Story 1.5: Shared Audit Logging Infrastructure | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a system, | |||
| I want all security-relevant and operational events captured by a shared logging service, | |||
| so that audit history is uniformly available across all application features from day one without per-feature implementation. | |||
| ## Acceptance Criteria | |||
| 1. **Given** any security-relevant action occurs (auth event, permission check, privileged update) **When** the action completes **Then** the event is written to the audit log within 5 seconds including actor identity, timestamp (UTC), action type, resource identifier, and outcome (NFR7) | |||
| 2. **Given** audit records are persisted **When** the retention policy is evaluated **Then** records are retained for at least 365 days and are not purgeable by standard application operations (NFR7) | |||
| 3. **Given** any application feature calls the audit logging service **When** the call is made **Then** it succeeds using the shared service contract — the calling feature does not implement its own audit persistence | |||
| 4. **Given** an audit record is written **When** retrieved for review **Then** it is append-only — no update or delete operations are available on audit records | |||
| 5. **Given** the audit service is unavailable **When** an auditable action occurs **Then** the action is blocked or queued — auditable operations must not silently proceed without capture | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.5) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-5-shared-audit-logging-infrastructure.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-6-legacy-anti-corruption-data-access-layer.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.6: Legacy Anti-Corruption Data Access Layer | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a developer, | |||
| I want a dedicated read-only data access layer for legacy Access-derived entities using fixed join keys, | |||
| so that legacy data is available to all features without any risk of schema mutation or direct table coupling. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a feature requests municipality or jurisdiction data **When** the anti-corruption layer is called **Then** it returns data joined by ID, JCode/JurisCode, or KitID without modifying any legacy table structure or content (NFR12) | |||
| 2. **Given** the anti-corruption layer executes any query **When** the operation is inspected **Then** only SELECT operations are permitted — INSERT, UPDATE, and DELETE on legacy entities are blocked at the layer boundary | |||
| 3. **Given** legacy data is returned through the layer **When** mapped to the application domain **Then** it is converted to strongly-typed domain model objects before being returned to any calling feature | |||
| 4. **Given** any application code outside the layer attempts to query legacy tables directly **When** reviewed in code **Then** no such direct access exists — the anti-corruption layer is the sole access point for legacy data | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.6) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-6-legacy-anti-corruption-data-access-layer.md` | |||
+ 68
- 0
_bmad-output/implementation-artifacts/1-7-legacy-schema-compatibility-validation-gate.md
Ver fichero
| @@ -0,0 +1,68 @@ | |||
| # Story 1.7: Legacy Schema Compatibility Validation Gate | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a an administrator, | |||
| I want to run a compatibility check that confirms legacy table schemas are unchanged against the approved baseline, | |||
| so that every release can be gated on legacy integrity before deployment. | |||
| ## Acceptance Criteria | |||
| 1. **Given** the compatibility check is triggered **When** it runs against the live database **Then** it compares all legacy table structures (column names, types, constraints) against the approved schema baseline stored at initialization | |||
| 2. **Given** a structural change is detected on any legacy table **When** the check completes **Then** it returns a failure status with a detailed report identifying the affected table, column, and change type (NFR12) | |||
| 3. **Given** no schema drift is detected **When** the check completes **Then** it returns a pass confirmation with timestamp, number of tables verified, and zero drift count | |||
| 4. **Given** the check is integrated into the release pipeline **When** it fails **Then** the release is blocked automatically and a failure report is surfaced to the administrator | |||
| 5. **Given** an administrator is logged in **When** they navigate to the compatibility check feature **Then** they can trigger the check manually and view the most recent check history with timestamps | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.7) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-7-legacy-schema-compatibility-validation-gate.md` | |||
+ 67
- 0
_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md
Ver fichero
| @@ -0,0 +1,67 @@ | |||
| # Story 1.8: Legacy Identifier Linking for Extension Records | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a system user, | |||
| I want extension records to store and validate legacy identifier references on creation, | |||
| so that all new capabilities join deterministically to legacy Access records in workflows and reports. | |||
| ## Acceptance Criteria | |||
| 1. **Given** a new extension record is created (municipality profile, election job, service config) **When** it is saved **Then** it stores the appropriate legacy identifier (ID, JCode/JurisCode, or KitID) as a required foreign reference | |||
| 2. **Given** an extension record references a legacy identifier **When** the anti-corruption layer executes a join **Then** it returns the correct legacy record with no ambiguity across all active records | |||
| 3. **Given** an extension record is submitted with an invalid or non-existent legacy identifier **When** validation runs before save **Then** the save is rejected with a descriptive validation error identifying the invalid reference | |||
| 4. **Given** the nightly integrity check runs **When** it evaluates all extension-to-legacy joins **Then** it reports referential consistency and flags any records that fail to resolve, targeting 99.9% consistency (NFR13) | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.8) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md` | |||
+ 68
- 0
_bmad-output/implementation-artifacts/1-9-seed-system-reference-values-rule-defaults.md
Ver fichero
| @@ -0,0 +1,68 @@ | |||
| # Story 1.9: Seed System Reference Values & Rule Defaults | |||
| Status: ready-for-dev | |||
| ## Story | |||
| As a a developer, | |||
| I want the system seeded with default reference values, required-field rules, and escalation rule defaults, | |||
| so that Epics 2–5 are immediately functional without requiring administrator configuration before use. | |||
| ## Acceptance Criteria | |||
| 1. **Given** the application initializes for the first time **When** the seed operation runs **Then** operational status sets, service template defaults, and extension-layer reference values are populated in the database | |||
| 2. **Given** the seed runs **When** required-field rules are evaluated **Then** default readiness fields for election-cycle jobs are defined and evaluable by Epic 2's readiness status feature (FR29) | |||
| 3. **Given** the seed runs **When** escalation rule defaults are checked **Then** at least one default rule exists covering overdue milestone alert scenarios (FR30) | |||
| 4. **Given** the seed operation is run multiple times **When** it completes **Then** no duplicate records are created — the operation is fully idempotent | |||
| 5. **Given** Epic 6 admin UIs update reference values or rules **When** the changes are saved **Then** they persist independently of the seed — rerunning the seed does not overwrite admin-managed values | |||
| ## Tasks / Subtasks | |||
| - [ ] Implement story behavior in aligned backend/frontend modules (AC: #1) | |||
| - [ ] Add or update API/service/UI components required by the story scope | |||
| - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures | |||
| - [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4) | |||
| - [ ] Add validation/error handling and UX state updates as needed | |||
| - [ ] Validate and document completion evidence | |||
| - [ ] Verify build/tests for touched modules | |||
| - [ ] Capture changed files and any migration/config implications | |||
| ## Dev Notes | |||
| - Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables. | |||
| - Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations. | |||
| - Keep changes scoped to this story; do not pull forward Epic 2+ features. | |||
| ### Project Structure Notes | |||
| - Backend: `BriansClientRouteReports.Server/` | |||
| - Frontend: `brians-client-route-reports-client/` | |||
| - Story artifacts: `_bmad-output/implementation-artifacts/` | |||
| ### References | |||
| - Story source: `_bmad-output/planning-artifacts/epics.md` (Epic 1 / Story 1.9) | |||
| - Architecture constraints: `_bmad-output/planning-artifacts/architecture.md` | |||
| - UX patterns: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ## Dev Agent Record | |||
| ### Agent Model Used | |||
| GPT-5 Codex | |||
| ### Debug Log References | |||
| - Story generated from epic source and architecture/UX planning artifacts. | |||
| ### Completion Notes List | |||
| - Story context created and marked ready-for-dev. | |||
| ### File List | |||
| - `_bmad-output/implementation-artifacts/1-9-seed-system-reference-values-rule-defaults.md` | |||
+ 102
- 0
_bmad-output/implementation-artifacts/sprint-status.yaml
Ver fichero
| @@ -0,0 +1,102 @@ | |||
| # generated: 2026-05-05T12:00:44-04:00 | |||
| # last_updated: 2026-05-05T12:09:17-04:00 | |||
| # project: Brians Client Route Reports App | |||
| # project_key: NOKEY | |||
| # tracking_system: file-system | |||
| # story_location: _bmad-output/implementation-artifacts | |||
| # STATUS DEFINITIONS: | |||
| # ================== | |||
| # Epic Status: | |||
| # - backlog: Epic not yet started | |||
| # - in-progress: Epic actively being worked on | |||
| # - done: All stories in epic completed | |||
| # | |||
| # Epic Status Transitions: | |||
| # - backlog -> in-progress: Automatically when first story is created (via create-story) | |||
| # - in-progress -> done: Manually when all stories reach 'done' status | |||
| # | |||
| # Story Status: | |||
| # - backlog: Story only exists in epic file | |||
| # - ready-for-dev: Story file created in stories folder | |||
| # - in-progress: Developer actively working on implementation | |||
| # - review: Ready for code review (via Dev's code-review workflow) | |||
| # - done: Story completed | |||
| # | |||
| # Retrospective Status: | |||
| # - optional: Can be completed but not required | |||
| # - done: Retrospective has been completed | |||
| # | |||
| # WORKFLOW NOTES: | |||
| # =============== | |||
| # - Epic transitions to 'in-progress' automatically when first story is created | |||
| # - Stories can be worked in parallel if team capacity allows | |||
| # - SM typically creates next story after previous one is 'done' to incorporate learnings | |||
| # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) | |||
| generated: '2026-05-05T12:00:44-04:00' | |||
| last_updated: '2026-05-05T12:09:17-04:00' | |||
| project: 'Brians Client Route Reports App' | |||
| project_key: 'NOKEY' | |||
| tracking_system: 'file-system' | |||
| story_location: '_bmad-output/implementation-artifacts' | |||
| development_status: | |||
| epic-1: in-progress | |||
| 1-1-project-initialization-solution-scaffold: ready-for-dev | |||
| 1-2-workspace-shell-ant-design-foundation: ready-for-dev | |||
| 1-3-keycloak-realm-configuration-oidc-integration: ready-for-dev | |||
| 1-4-keycloak-role-mapping-application-authorization: ready-for-dev | |||
| 1-5-shared-audit-logging-infrastructure: ready-for-dev | |||
| 1-6-legacy-anti-corruption-data-access-layer: ready-for-dev | |||
| 1-7-legacy-schema-compatibility-validation-gate: ready-for-dev | |||
| 1-8-legacy-identifier-linking-for-extension-records: ready-for-dev | |||
| 1-9-seed-system-reference-values-rule-defaults: ready-for-dev | |||
| 1-10-municipality-account-profile: ready-for-dev | |||
| 1-11-municipality-operational-addresses: ready-for-dev | |||
| 1-12-municipality-service-contacts: ready-for-dev | |||
| 1-13-municipality-prior-cycle-service-defaults-view: ready-for-dev | |||
| epic-1-retrospective: optional | |||
| epic-2: backlog | |||
| 2-1-municipality-to-cycle-kanban-entry-point: backlog | |||
| 2-2-create-election-cycle-job: backlog | |||
| 2-3-election-cycle-key-dates: backlog | |||
| 2-4-prior-cycle-defaults-application: backlog | |||
| 2-5-election-cycle-readiness-status-publication: backlog | |||
| 2-6-spreadsheet-import-column-mapping: backlog | |||
| epic-2-retrospective: optional | |||
| epic-3: backlog | |||
| 3-1-addressing-service-configuration: backlog | |||
| 3-2-envelope-service-configuration-purple-blue: backlog | |||
| 3-3-office-copy-service-configuration: backlog | |||
| 3-4-sorting-service-configuration: backlog | |||
| 3-5-transportation-service-events: backlog | |||
| epic-3-retrospective: optional | |||
| epic-4: backlog | |||
| 4-1-schedule-update-milestone-dates: backlog | |||
| 4-2-milestone-timeline-views-cutoffriskqueuepanel: backlog | |||
| 4-3-missing-conflicting-milestone-detection: backlog | |||
| 4-4-milestone-ownership-reassignment: backlog | |||
| epic-4-retrospective: optional | |||
| epic-5: backlog | |||
| 5-1-production-status-updates-at-checkpoints: backlog | |||
| 5-2-exception-blocker-logging: backlog | |||
| 5-3-blocked-job-resolution-with-blockerresolutiondrawer: backlog | |||
| 5-4-status-transition-history-provenancetimelinepanel: backlog | |||
| 5-5-current-historical-process-state-view: backlog | |||
| 5-6-transportation-report-date-sorted-dispatch: backlog | |||
| epic-5-retrospective: optional | |||
| epic-6: backlog | |||
| 6-1-sorting-report-by-municipality: backlog | |||
| 6-2-sorting-report-by-mail-date: backlog | |||
| 6-3-report-filtering-saved-presets-unified-export: backlog | |||
| 6-4-report-to-source-traceability: backlog | |||
| 6-5-extension-layer-data-correction: backlog | |||
| 6-6-admin-configuration-uis-reference-values-required-field-rules-escalation-rules: backlog | |||
| 6-7-parity-governance-legacy-report-sunset: backlog | |||
| 6-8-source-reconciliation-data-quality-queue: backlog | |||
| epic-6-retrospective: optional | |||
+ 204
- 0
_bmad-output/planning-artifacts/architecture.md
Ver fichero
| @@ -0,0 +1,204 @@ | |||
| --- | |||
| stepsCompleted: | |||
| - 1 | |||
| - 2 | |||
| - 3 | |||
| inputDocuments: | |||
| - _bmad-output/planning-artifacts/prd.md | |||
| - _bmad-output/planning-artifacts/ux-design-specification.md | |||
| - _bmad-output/planning-artifacts/validation-report-2026-04-03.md | |||
| - Initial Description.txt | |||
| - Initial Documents/Access_Schema.txt | |||
| - Initial Documents/Client Database Plan.xlsx | |||
| - _bmad-output/planning-artifacts/client-database-plan-extract.txt | |||
| workflowType: 'architecture' | |||
| project_name: 'Brians Client Route Reports App' | |||
| user_name: 'Daniel' | |||
| date: '2026-04-03' | |||
| --- | |||
| # Architecture Decision Document | |||
| _This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._ | |||
| ## Project Context Analysis | |||
| ### Requirements Overview | |||
| **Functional Requirements:** | |||
| The system scope covers end-to-end municipal election operations with 34 FRs organized into 7 architectural capability domains: | |||
| - Municipality & account management (FR1-F4) | |||
| - Election-cycle setup & planning (FR5-F8) | |||
| - Service configuration (FR9-F13) | |||
| - Scheduling & milestone management (FR14-F17) | |||
| - Production tracking & exception handling (FR18-F21) | |||
| - Operational reporting & exports (FR22-F26) | |||
| - Role governance + legacy compatibility/data integrity (FR27-F34) | |||
| Architecturally, this implies a modular domain model with strict separation between: | |||
| - Permanent municipality entities (long-lived master data) | |||
| - Election-cycle entities (repeatable operational lifecycle data) | |||
| **Non-Functional Requirements:** | |||
| Key architecture-driving NFRs include: | |||
| - Performance: p95-like expectations on page loads, updates, and report generation | |||
| - Security: transport encryption, at-rest protection, RBAC enforcement, audit logging | |||
| - Scalability: 10x job growth and 150 concurrent users under load constraints | |||
| - Accessibility: keyboard-operable critical workflows and WCAG-aligned operation | |||
| - Compatibility/integrity: immutable legacy schema and high referential join consistency | |||
| - Reliability/recoverability: availability targets, audit reconstruction, recovery safeguards | |||
| These NFRs strongly favor a service-oriented architecture with explicit quality gates, observability, and data-contract validation. | |||
| **Scale & Complexity:** | |||
| This project is high complexity due to regulated operations, date-critical workflows, multi-role coordination, and brownfield constraints. | |||
| - Primary domain: internal govtech operations web platform (data-intensive line-of-business) | |||
| - Complexity level: high | |||
| - Estimated architectural components: ~14-18 major components/services (provisional; to be validated after topology and integration boundary decisions) | |||
| ### Technical Constraints & Dependencies | |||
| - Legacy Access tables are immutable (no add/drop/alter of original tables). | |||
| - All new behavior must be implemented through extension tables and join queries/views. | |||
| - Join keys are fixed and must remain deterministic: `ID`, `JCode`/`JurisCode`, `KitID`. | |||
| - Permanent municipality and election-cycle data must remain model-separated while joinable in reports/workflows. | |||
| - Reporting output parity with existing operational consumers must be preserved. | |||
| - Browser-targeted desktop web app with keyboard-first usability and dense data interaction. | |||
| - Existing process expectations are anchored to Access-era workflows and spreadsheet export patterns. | |||
| ### Critical Tensions to Resolve Early | |||
| - **Scope tension (platform):** PRD includes tablet-friendly secondary target, while confirmed UX direction is PC-only. | |||
| Architectural baseline should treat PC-only as controlling scope unless PRD is revised. | |||
| - **Compliance specificity tension:** govtech expectations (clearance/residency/procurement evidence) are present but need explicit system-level enforcement decisions. | |||
| - **Performance vs density tension:** dense grid workflows, live operational state, and sub-second update targets may conflict without careful query/index/cache strategy. | |||
| - **Parity vs modernization tension:** preserving legacy report parity while improving data model and workflows introduces dual-truth risk during transition. | |||
| ### Architectural Pressure Points | |||
| - Introduce an **anti-corruption data access layer** between modern services and legacy Access structures. | |||
| - Separate architecture into **operational write path** (extension tables) and **report read path** (join/materialized/query layer) to reduce coupling. | |||
| - Treat join-key integrity as a platform concern with scheduled validation and release-gate checks. | |||
| - Model pre-commit validation as a shared orchestration capability (required fields, dependencies, policy checks). | |||
| - Ensure deterministic state refresh semantics for dense grids, risk queues, and provenance views. | |||
| - Define explainable blocker payloads so UI can present clear reasons and one-click corrective actions. | |||
| ### Migration & Parity Governance | |||
| - Run legacy and modern reports in parallel during transition windows. | |||
| - Define parity acceptance thresholds per report type and field criticality. | |||
| - Implement discrepancy triage workflow with owner assignment and closure status tracking. | |||
| - Require parity evidence as a formal cutover gate before legacy process deprecation. | |||
| - Maintain backward-compatible export schemas for existing downstream consumers where mandated. | |||
| ### Compliance Evidence Model (Govtech) | |||
| - Define security evidence artifacts for privileged actions and authentication events. | |||
| - Define data residency attestation artifacts aligned to municipality policy constraints. | |||
| - Define accessibility evidence artifacts (keyboard coverage, contrast checks, critical-flow audits). | |||
| - Bind evidence generation to release gates rather than post-release documentation. | |||
| - Assign ownership and retention rules for each evidence artifact category. | |||
| ### Cross-Cutting Concerns Identified | |||
| - Data integrity and compatibility enforcement across all read/write paths | |||
| - Authorization boundaries and privileged operation controls | |||
| - Auditability/provenance for every sensitive status transition | |||
| - Validation orchestration (required-field, dependency, policy checks pre-commit) | |||
| - Operational reporting consistency and deterministic filtering/sorting behavior | |||
| - Performance under peak election windows (query shaping, caching, export throughput) | |||
| - Accessibility and keyboard operability in dense grid/form workflows | |||
| - Error handling and recovery UX linked to exception workflows | |||
| ### Assumptions & Risk Flags (Architecture-Level) | |||
| - Assumption: legacy identifiers are sufficiently clean for deterministic joins at operational scale. | |||
| - Assumption: extension-table growth can be managed without degrading report latency. | |||
| - Risk flag: key-mapping inconsistencies may produce silent report drift unless reconciliation controls are explicit. | |||
| - Risk flag: migration period may require side-by-side parity verification and discrepancy triage workflow. | |||
| - Risk flag: compliance evidence generation must be designed in, not added after implementation. | |||
| ## Starter Template Evaluation | |||
| ### Primary Technology Domain | |||
| Full-stack municipal operations web application using an ASP.NET backend and TypeScript-first React frontend. | |||
| ### Starter Options Considered | |||
| - ASP.NET Core SPA template (`dotnet new react`): convenient single template, but less aligned with modern frontend tooling and independent frontend lifecycle. | |||
| - ASP.NET Core 10 Web API + Vite React TypeScript: clean backend/frontend boundary, modern frontend DX, and explicit fit for the requested stack. | |||
| - Next.js full-stack starter: strong option generally, but misaligned with explicit requirement for a .NET ASP application backend. | |||
| ### Selected Starter: ASP.NET Core 10 Web API + Vite React TypeScript | |||
| **Rationale for Selection:** | |||
| This aligns directly with the requested architecture (`.NET 10 ASP` + `TypeScript-first React`), supports modern frontend workflows, and preserves flexibility for immutable-legacy integration patterns on the backend. | |||
| **Initialization Command:** | |||
| ```bash | |||
| dotnet new sln -n brians-client-route-reports | |||
| dotnet new webapi -n BriansClientRouteReports.Server -f net10.0 --use-controllers | |||
| dotnet sln add .\BriansClientRouteReports.Server\BriansClientRouteReports.Server.csproj | |||
| npm create vite@latest brians-client-route-reports-client -- --template react-ts | |||
| ``` | |||
| **Architectural Decisions Provided by Starter:** | |||
| **Language & Runtime:** | |||
| Backend on C#/.NET 10 Web API, frontend on React + TypeScript with Node-based toolchain. | |||
| **Styling Solution:** | |||
| Vite React TypeScript starter defaults to CSS-based setup, enabling incremental adoption of a design system without early framework lock-in. | |||
| **Build Tooling:** | |||
| Backend built via .NET SDK tooling; frontend built via Vite for fast local iteration and production bundling. | |||
| **Testing Framework:** | |||
| Backend includes .NET test ecosystem compatibility; frontend starter includes a TypeScript-ready React project structure that can layer Vitest and Playwright in implementation stories. | |||
| **Code Organization:** | |||
| Clear server/client repo boundaries with explicit API contracts between them, supporting modular domain design and safer migration from legacy Access workflows. | |||
| **Development Experience:** | |||
| Hot reload on both backend and frontend, strong TypeScript ergonomics, and independent deploy/test pipelines for server and client. | |||
| **Note:** Project initialization using this command should be the first implementation story. | |||
| ## Approved Correct Course Addendum (2026-05-05) | |||
| ### New Source Integration Boundary | |||
| A late source document was approved for inclusion: Google Sheet `AUGUST 2026 PRIMARY Ballot Envelope Imprinting and Tracking Scheduled .xlsx`. | |||
| To support this safely, architecture adds an explicit ingestion boundary: | |||
| - Source intake adapter (approved template/file detection) | |||
| - Template-version and header validation | |||
| - Mapping registry from source columns to extension entities | |||
| - Validation engine for required fields and join-key integrity | |||
| - Staging store for pre-publish review | |||
| - Publish service with audit and provenance capture | |||
| ### Provenance and Reconciliation Model | |||
| For spreadsheet-origin data, the platform must persist: | |||
| - Source file identifier | |||
| - Source row reference | |||
| - Import timestamp | |||
| - Importing user | |||
| A reconciliation process must compare source-origin values against operational report outputs, with deterministic mismatch reporting and triage workflow ownership. | |||
| ### Security and Role Handling for Contact Data | |||
| Imported contact and proofing-related fields are role-protected and auditable. | |||
| - Least-privilege visibility by role | |||
| - All sensitive field changes captured in audit stream | |||
| - No bypass around SafeCommitRail-equivalent validation for publish-sensitive updates | |||
+ 236
- 0
_bmad-output/planning-artifacts/client-database-plan-extract.txt
Ver fichero
| @@ -0,0 +1,236 @@ | |||
| SHEETS: Database Fields, Transportation Report, Sorting Report by Client, Sort Report by Date, Current Data | |||
| === Database Fields === | |||
| | | | | | | | | | | | | | | | | | | | TMB Training | TMB Reachout | |||
| | Bold | is a database field | |||
| | Red | Is a database field looked up from another table or calculated | |||
| | Blue | Is field type | |||
| Municipality Table | |||
| | JurisCode | | | | Lookup | | | Lookup from Clerk List | |||
| | Municipality Name | | | | Lookup | | | Lookup from Clerk List | |||
| | Address | | | | Lookup | | | Lookup from Clerk List | |||
| | County | | | | Lookup | | | Lookup from Clerk List | |||
| | Phone Number | | | | Alpha Numeric | | | Data Entry for now | |||
| | Delivery Address if different from BRE | | | | Alpha Numeric | | | Data Entry | |||
| | PS Cust # | | | | Alpha Numeric | | | Data Entry for now | |||
| | PCS # | | | | Alpha Numeric | | | Data Entry for now | |||
| | NetSort FC # | | | | Alpha Numeric | | | Data Entry | |||
| | NetSort NP/STD # | | | | Alpha Numeric | | | Data Entry | |||
| | CRID | | | | Alpha Numeric | | | Data Entry | |||
| | NP Auth# | | | | Alpha Numeric | | | Data Entry | |||
| | Contact name 1 (primary) | | | | Alpha Numeric | | | Data Entry | |||
| | Contact email 1 (snailworks) | | | | Alpha Numeric | | | Data Entry | |||
| | Contact name 2 | | | | Alpha Numeric | | | Data Entry | |||
| | Other Contact emails | | | | Alpha Numeric | | | Data Entry | |||
| Election Table | JurisCode | | | | Lookup | | | Lookup from Municipality Table | |||
| | Municipality Name | | | | Lookup | | | Lookup from Municipality Table | |||
| | Contact name 1 (primary) | | | | Lookup | | | Lookup from Municipality Table | |||
| | Contact email 1 (snailworks) | | | | Lookup | | | Lookup from Municipality Table | |||
| | Contact name 2 | | | | Lookup | | | Lookup from Municipality Table | |||
| | Other Contact emails | | | | Lookup | | | Lookup from Municipality Table | |||
| | Addressing | Y/N | | | | | | Data Entry | |||
| | | If Y | Addressing Qty | Qty | | | | Data Entry | Default from last election | |||
| | | If Y | Data Files Scheduled | Date | | | | Data Entry | |||
| | | If Y | KCI Env Purple | Y/N | | | | Data Entry | Default from last election | |||
| | | If Y | Customer Envelope PU Date | Date | | | | Data Entry | |||
| | | If Y | Proof Sent | Date | | | | Data Entry | |||
| | | If Y | Proof Approved | Date | | | | Data Entry | |||
| | | If Y | KCI Purple Env Delivery | Date | | | | Data Entry | |||
| | | If Y | Office Copies | Qty | | | | Data Entry | |||
| | | If Y | Address File Tracking | Y/N | | | | Data Entry | Default from last election | |||
| | | | If Y | Snailworks login created | Date / Prevously setup | | | Data Entry | |||
| | | If Y | KCI Provided Blue | Y/N | | | | Data Entry | |||
| | | | If Y | Blue Quantity | Qty | | | Calculated | Total of other quantities | |||
| | | | If Y | KCI Blue Generic | Qty | | | Data Entry | |||
| | | | If Y | KCI Blue NP Permit | Qty | | | Data Entry | |||
| | | | If Y | KCI Blue Custom | Qty | | | Data Entry | |||
| | | | If Y | Blue KCI Delivery Date | Date | | | Data Entry | |||
| | KCI Sorting | Y/N | |||
| | | If Y | Sort Qty | Qty | | | | Data Entry | Default from last election | |||
| | | If Y | Ballot Sort PU Date | Date | | | | Data Entry | |||
| | | If Y | MailDate | Date | | | | Data Entry | |||
| | | If Y | Class | NP / Std / First | | | | Data Entry | Default from last election | |||
| | | If Y | Sort File Tracking | Y/N | | | | Data Entry | |||
| | | If Y | Daily Sort | Y/N | | | | Data Entry | Default from last election | |||
| | | If Y | Permit/Meter | Permit / Meter | | | | Data Entry | Default from last election | |||
| | | If Y | Tray Delivery Date | Date | | | | Data Entry | |||
| === Transportation Report === | |||
| Transportation Report | |||
| Can we output in an Excel or CSV file? | |||
| Run by date - all dates today or greater - sort by date earliest to latest | |||
| Run for all dates that exist in Customer Envelope PU Date or Blue KCI Delivery Date or Tray Delivery Date or Ballot Sort PU Date | |||
| Date 1 | |||
| | County | sort alpha | |||
| | | Municipality Name | sort apha | |||
| | | JurisCode | |||
| | | Address | |||
| | | County | |||
| | | Delivery Address if different from BRE | |||
| | | Phone Number | |||
| | | Contact name 1 (primary) | |||
| | | Contact email 1 (snailworks) | |||
| | | Contact name 2 | |||
| | | Other Contact emails | |||
| | | Customer Envelope Pickup | |||
| | | If Customer Envelope PU Date = Date 1 | Addressing Qty | |||
| | | Blue Envelope Delivery | |||
| | | If Blue KCI Delivery Date = Date 1 | Blue Quantity | |||
| | | Tray Delivery Date | |||
| | | if Tray Delivery Date = Date 1 | Create note to deliver trays | |||
| | | Ballot Pickup Date (sorting) | |||
| | | if Ballot Sort PU Date = Date 1 | Sort Qty | |||
| Date 2 = next date after date 1 | |||
| | County | sort alpha | |||
| | | Municipality Name | sort apha | |||
| | | JurisCode | |||
| | | Address | |||
| | | County | |||
| | | Delivery Address if different from BRE | |||
| | | Phone Number | |||
| | | Contact name 1 (primary) | |||
| | | Contact email 1 (snailworks) | |||
| | | Contact name 2 | |||
| | | Other Contact emails | |||
| | | Customer Envelope Pickup | |||
| | | If Customer Envelope PU Date = Date 2 | Addressing Qty | |||
| | | Purple Envelope Delivery | |||
| | | If KCI Purple Env Delivery = Date 2 | Addressing Qty | |||
| | | Blue Envelope Delivery | |||
| | | If Blue KCI Delivery Date = Date 2 | Blue Quantity | |||
| | | Tray Delivery Date | |||
| | | if Tray Delivery Date = Date 2 | Create note to deliver trays | |||
| | | Ballot Pickup Date (sorting) | |||
| | | if Ballot Sort PU Date = Date 2 | Sort Qty | |||
| Date 3…... | |||
| === Sorting Report by Client === | |||
| Sorting Report by Municipality | |||
| Can we output in an Excel or CSV file? | |||
| Run for all KCI Sorting = Y | |||
| | Municipality Name | sort apha | |||
| | Contact name 1 (primary) | |||
| | Contact email 1 (snailworks) | |||
| | Contact name 2 | |||
| | Other Contact emails | |||
| | MailDate | |||
| | Ballot Sort PU Date | |||
| | Sort Qty | |||
| | Class | |||
| | Sort File Tracking | | |||
| | Daily Sort | |||
| | Permit/Meter | |||
| | PS Cust # | |||
| | PCS # | |||
| | NetSort FC # | |||
| | NetSort NP/STD # | | |||
| | CRID | |||
| | NP Auth# | |||
| === Sort Report by Date === | |||
| Sorting Report by Mail Date | |||
| Can we output in an Excel or CSV file? | |||
| Run for all KCI Sorting = Y | |||
| | Municipality Name | |||
| | Contact name 1 (primary) | |||
| | Contact email 1 (snailworks) | |||
| | Contact name 2 | |||
| | Other Contact emails | |||
| | MailDate | sort earliest to latest | |||
| | Ballot Sort PU Date | |||
| | Sort Qty | |||
| | Class | |||
| | Sort File Tracking | | |||
| | Daily Sort | |||
| | Permit/Meter | |||
| | PS Cust # | |||
| | PCS # | |||
| | NetSort FC # | |||
| | NetSort NP/STD # | | |||
| | CRID | |||
| | NP Auth# | |||
| === Current Data === | |||
| JurisCode | Municipality Name | County | PS Cust # | PCS # | Addressing | Tracking | Class | NetSort FC # | NetSort NP/STD # | CRID | NP Auth# | KCI Env | Env P-UpDate | Data Files | Return Env | KCI Sorting | Daily Sort | Permit/Meter | MailDate | Contacted? | Proof Sent | Proof Approved | SnailworksLogin | Contact email 1 (snailworks) | Other Contact emails | Contact name 1 (primary) | Contact name 2 | TMB Training | TMB Reachout | |||
| 1160 | Algoma Twp | Kent | 10861 | 10861 | | N | NP | | 201160 | 2467155 | 1835562 | Yes | | | | | | meter | | | | | | dclerk@algomatwp.org | | Heidi McCann | | | | |||
| 1360 | Allendale Twp | Ottawa | 4736 | 47361 | | Y | NP | 401360 | 201360, 101360 | 8083010 | 1000085 | Yes | | | | | | meter | | | | | | clerk@allendalemi.gov | | Jody Hansen | | | | |||
| 1840 | Alpine Twp | Kent | 5665 | 5665 | | Y | NP | | 201840 | 2409356 | 1928026 | Yes | | | | | | meter | | | | | | M.Jespersen@alpinetwp.org | | Michelle Jespersen | | | | |||
| 8940 | Blendon Twp | Ottawa | 11791 | 11791 | | n | NP | | 208940 | 8083009 | 1882388 | yes | | | | | | meter | | | | | | Clerk@blendontownship-mi.gov | deputyclerk@blendontownship-mi.gov | Robin Overway | Jennifer Mokma | | | |||
| 9110 | Bloomfield Township | Oakland | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | dmondock@bloomfieldtwp.org | | Deana Mondock | | | | |||
| 12240 | Byron Twp | Kent | 6667 | 6667 | | n | NP | | 112240 | 2409448 | 771449 | Yes | | | | | | permit | | | | | | peggy@byrontownship.org | Heather@byrontownship.org | Peggy Sattler | | | | |||
| 12500 | Caledonia Twp | Kent | 6336 | 6336 | | n | NP | 412500 | 212500 | 23692775 | 1833695 | yes | | | | | | meter | | | | | | sskidmore@caledoniatownship.org | | Stephanie Skidmore | | | | |||
| 13080 | Cannon Twp | Kent | 9488 | 9488 | | n | NP | 413080 | 213080 | 2466477 | 1837258 | Yes | | | | | | meter | | | | | | nancyp@CANNONTWP.ORG | | Nancy Popma | | | | |||
| 13120 | Canton Twp | Wayne | 10756 | dont need | | N | N/A | N/A | N/A | | N/A | Yes | | | | | | N/A | | | | | | not tracking | katherine.baker@cantonmi.gov | Katie Baker | | | | |||
| 13660 | Cascade Charter Twp | Kent | 8898 | 8898 | | N | NP | 413660 | 213660, 113660 | 6857595 | 1835610 | YES | | | | | | meter | | | | | | jjager@cascadetwp.org | | Jennifer Jager | | | | |||
| 17680 | Charter Township of Comstock | Kalamazoo | 12792 | 12792 | yes | YES | std | | 217680 | 7781407 | N/A | no | 46107 | 46090 | | | | meter | | | | | | | | | | | | |||
| 59000 | Charter Township of Northville | Wayne | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | kanderson@twp.northville.mi.us | | Katie Anderson | | | | |||
| 5920 | City of Battle Creek | Calhoun | 9307 | 9307 | | Y | std | | 205920 | 12729386 | N/A | no | | | | | | meter | | | | | | vlhouser@battlecreekmi.gov | cityclerk@battlecreekmi.gov | Victoria Houser | | | | |||
| 17020 | City of Coldwater | Branch | 12544 | 12544 | | Y | NP | | 217020 | 3179938 | 876699 | No | | | | | | | | | | | | schavez@coldwater.org | | Shauna Chavez | | | | |||
| 24120 | City of East Lansing | Ingham | 9090 | 9090 | yes | n | NP | 424120 | 224120 | 4365352 | 613996 | Yes | 46107 | 46090 | 46100 | yes | yes | Meter | 46108 | yes | | | | agordon@cityofeastlansing.com | | Amy Gordon | | | | |||
| 27380 | City of Farmington | Oakland | 12704 | 12704 | | n | std | | 227380 | 42044680 | STD mail | Yes | | | | | | meter | | | | | | mbachman@farmgov.com | | Meaghan Bachman | | | | |||
| 27440 | City of Farmington Hills | Oakland | 9218 | 9218 | | N | NP | | 227440 | 3569620 | 716814 | no | | | | | | meter | | | | | | ahopper@fhgov.com | | Ashley Hopper | | | | |||
| 33340 | City of Grand Haven | Ottawa | 3446 | 3446 | | n | NP | | 233340 | 5016184 | 919979 | n | | | | | | meter | | | | | | mariaboersma@grandhaven.org | | Maria Boersma | | | | |||
| 33420 | City of Grand Ledge | Eaton | 11535 | 11535 | | y | | 433420 | 233420, 133420 | 31216124 | 1835615 | Y | | | | | | | | | | | | gnewman@cityofgrandledge.com | DHengesbach@cityofgrandledge.com | Gregory Newman | | | | |||
| 34000 | City of Grand Rapids | Kent | 11988 | 11988 | | Yes | NP | 434000 | 234000, 134000 | 5098256 | 727255 | N | | | | | | | | | | | | jhondorp@grand-rapids.mi.us | amorgan@grand-rapids.mi.us | Joel Hondorp | | | | |||
| 34160 | City of Grandville | Kent | 5602 | not yet | | y | NP | 434160 | 134160 | 3376063 | 719553 | n | | | | | | meter | | | | | | poleym@cityofgrandville.com | | Marci Poley | Brittany Cooley | | | |||
| 35520 | City of Grosse Pointe Farms | Wayne | 12637 | | | n | | | | | | yes | | | | | | | | | | | | | | | | | | |||
| 39800 | City of Hudsonville | Ottawa | 7332 | 7332 | | n | NP | | 239800 | 2410934 | 1006657 | Yes | | | | | | meter | | | | | | Jgruppen@hudsonville.org | | Jill Gruppen | | | | |||
| 40000 | City of Huntington Woods | Oakland | 11991 | 11991 | | n | NP | 440000 | 240000 | 3804310 | 1836644 | no | | | | | | meter | | | | | | hbarckholtz@hwmi.org | | Heidi Barckholtz | | | | |||
| 42160 | City of Kalamazoo | Kalamazoo | 11792 | 11792 | | no | n/a | | 242160 | 42032302 | N/A | Yes | | | | | | n/a | | | | | | mcmillonam@kalamazoocity.org | | Amanda McMillon | | | | |||
| 46000 | City of Lansing | Ingham | 9159 | 91502 | | Yes | NP | 446000 | 246000, 146000 | 3030341 | 719997 | No | 46107 | 46083 | tbd/insert test | yes | yes | permit | 46108 | yes | | | | chris.swope@lansingmi.gov | Robin.Stites@lansingmi.gov | Chris Swope | | | | |||
| 49000 | City of Livonia | Wayne | 9530 | dont need | | N | NP | N/A | N/A | | N/A | no | | | | | | | | | | | | lmiller@livonia.gov | ddemarco@livonia.gov | Lori Miller | | | | |||
| 50560 | City of Madison Hts | Oakland | 12734 | dont need | | n | NP | | | | | no | | | | | | n/a | | | | | | CherylRottmann@Madison-Heights.org | | Cheryl Rottman | | | | |||
| 55280 | City of Montrose | Genesee | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | CLERK@CITYOFMONTROSE.US | | Tina Rush | | | | |||
| 56320 | City of Muskegon | Muskegon | 10532 | 10532 | | N | NP/Out of state FC | | 256320 | 4711835 | 721891 | No | 45004 | | | | | meter | | | | | | | | Shelly Stibitz | | | | |||
| 58980 | City of Northville | Wayne | 11434 | 11434 | | Y | std | | 258980 | 2630908 | | Yes | | | | | | meter | | | | | | msmith@ci.northville.mi.us | | Mike Smith | | | | |||
| 59140 | City of Norton Shores | Muskegon | 8905 | 89051 | | N | NP | | 259140, 159140 | 2835194 | 718268 | No | | | | | | METER | | | | | | | | Rachel Pavlich | | | | |||
| 59440 | City of Novi | Oakland | 9222 | 9222 | | n | NP | | 259440 | 2725509 | 718944 | No | | | | | | meter | | | | | | | | | | | | |||
| 59920 | City of Oak Park | Oakland | 12729 | 12729 | | N | NP | | 259920 | 4119986 | 765065 | Yes | | | | | | meter | | | | | | jlwilliams@oakparkmi.gov | enorris@oakparkmi.gov | Ed Norris | Jo Lynn Williams-Elliott | | | |||
| 65060 | City of Plymouth | Wayne | 10762 | dont need | | Yes | Confirm | | | | N/A | yes | | | | | | N/A | | | | | | sbridgman@plymouthmi.gov | nanderson@plymouthmi.gov | Sydney Bridgman | Nancy Anderson | | | |||
| 69080 | City of Rockford | Kent | 5942 | 59421 | | n | NP | | 269080 | 36543032 | 1916530 | no | | | | | | meter | | | | | | | | Kris Murphy | | | | |||
| 69420 | City of Romulus | Wayne | 9385 | dont need | | Y | n/a | | | | | no | | | | | | n/a | | | | | | dhockenhull@romulusgov.com | ebragg@romulusgov.com | D’Sjonaun Hockenhull | Ellen Craig-Bragg | | | |||
| 70040 | City of Royal Oak | Oakland | 9179 | 9179 | | Yes | NP | 370040 | 170040, 270040 | 4581404 | 698086 | YES | | | | | | Mix/Meter out of region, permit in region | | | | | | DeannaB@romi.gov | | Deanna Braswell | | | | |||
| 79000 | City of Taylor | Wayne | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | sel-rifaai@ci.taylor.mi.us | | Sara El-Rifaai | | | | |||
| 80700 | City of Troy | Oakland | 9939 | 9939 | | n | NP | 480700 | 180700 | 2414883 | 727724 | no | | | | | | meter | | | | | | Cheryl.Stewart@troymi.gov | | Cheryl Stewart | | | | |||
| 82960 | City of Walker | Kent | 2301 | 82960 | | n | NP | 482960 | 282960 | 3415884 | 915252 | yes | | | | | | | | | | | | jmarion@walker.city | | Jessica Marion | | | | |||
| 84000 | City of Warren | Macomb | 10606 | run LS job | | N | NP P127 | | 184000 | 5175213 | 714827 | n/a | | | | | | 127 Theirs | | | | | | sBuffa@cityofwarren.org | | Sonja Buffa | | | | |||
| 88940 | City of wyoming | Kent | 4003 | 40031 | | n | NP | 388940 | 288940 | 7579559 | 766179 | yes | 46107 | | | y | | meter | | | | | | | | Kelli VandenBerg | Rhonda Galligan | | | |||
| 89260 | City of Zeeland | Ottawa | 11188 | 11188 | | n | std | | 289260 | 8083005 | N/A | YES | | | | | | meter | | | | | | CHumphrey@cityofzeeland.com | | Cindy Humphrey | | | | |||
| 18500 | Courtland twp | Kent | 4245 | 4245 | | n | NP | | 218500 | 14380003 | 765302 | yes | | | | | | meter | | | | | | clerk@courtlandtwpmi.gov | | Susan Hartman | | | | |||
| 19660 | Dalton Township | Muskegon | 8986 | 8986 | | no | NP | | 119660/219660 | 29384512 | 1833688 | | | | | | | | | | | | | | | | | | | |||
| 21420 | Delhi Township | Ingham | 11870 | 11870 | yes | n | NP | | 221420 | 3150019 | 793190 | YES | 46111 | 46090 | 46097 | y | | meter | | | | | | evan.hope@delhitownshipmi.gov | gloria.loongo@delhitowshipmi.gov | Evan Hope | Gloria Loongo | | | |||
| 23800 | East Bay Twp | Grand Traverse | 9540 | dont need | | Y | NP | | | | | no | | | | | | | | | | | | scourtade@eastbaytwp.org | HCouturier@eastbaytwp.org | Sue Courtade | Holly Couturier | | | |||
| 26320 | Erie Township | Monroe | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | kcousino@erietownship.com | | Kimberly Cousino | | | | |||
| 31240 | Gaines Twp | Kent | 6283 | 6283 | | n | NP | | 131240 | 2410908 | 1835609 | y | | | | | | meter | | | | | | | | Michael Brew | Amber Vandermolen | | | |||
| 33300 | Grand Blanc Township | Genesee | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | henry@twp.grand-blanc.mi.us | | Lynn Henry | | | | |||
| 33360 | Grand Haven Twp | Ottawa | 9484 | 9484 | | n | NP | | 233360 | 3439808 | 1216398 | n | | | | | | Permit | | | | | | mariaboersma@grandhaven.org | | Maria Boersma | | | | |||
| 34020 | Grand Rapids Charter Twp | Kent | 8596 | 34020 | | Yes | NP | 434020 | 234020 | 3804323 | 1835636 | Yes | | | | | | meter | | | | | | erobinette@grandrapidstwp.org | dknoll@grandrapidstwp.org | Ed Robinette (added "1") | Deborah Knoll | | | |||
| 34560 | Grattan Twp | Kent | 4191 | 4191 | | n | PS FIRST | | 234560 | 25138151 | 1923510 | Yes | | | | | | meter | | | | | | clerk@grattantownship.org | | Otto McLaughlin | | | | |||
| 38660 | Holland Charter Township | Ottawa | 12308 | 12308 | yes | n | std | | 238660 | 13416692 | N/A | tbd | | 46083 | 46100 | | | meter | | | | | | | | | | | | |||
| 40400 | Independence Township | Oakland | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | ELECTIONS@INDTWP.COM | | Cari Neubeck | | | | |||
| 41520 | Jamestown Twp | Ottawa | 11997 | 11997 | | n | NP | | 241520 | 20582361 | 1836943 | n | | | | | | meter | | | | | | | | Candy DeHaan | | | | |||
| 42180 | Kalamazoo Township | Kalamazoo | 11969 | 11969 | yes | n | NP | | 242180, 142180 | 3136307 | 768528 | no | 3.16.26 | 3.17.26 | 3.2 | y | | meter | | | | | | | | | | | | |||
| 47600 | Lincoln Charter Township | Berrien | N/A | N/A | | Kit Promi | N/A | N/A | N/A | N/A | N/A | N/A | | | | | | N/A | | | | | | sloar-porter@lctberrien.org | | Stacy Loar-Porter | | | | |||
| 53140 | Meridian Twp | Ingham | 10270 | 10270 | yes | Y | NP | 453140 | 153140 | 3401212 | 705120 | Yes | 3.26 | 46090 | 46100 | y | | | | | | | | gordon@meridian.mi.us | | Emily Gordon | | | | |||
| 54980 | Monitor Twp | Bay | | dont need | | Y | n/a | | | | | YES | | | | | | | | | | | | clerk@monitortwp.org | | Linda Ferguson | | | | |||
| 56920 | Nelson Twp | Kent | 9349 | 9349 | yes | N | NP | | 256920 | 3427046 | 1933122 | YES | 3.26 | | | y | | meter | | | | | | clerk@nelsontownship.org | | Laura Hoffman | | | | |||
| 59580 | Oakfield Township | Kent | 3501 | 3501 | | n | NP | | 259580, 459580 | 31322157 | 1839642 | yes | | | | | | meter | | | | | | clerk@oakfieldtwp.org | | Sue Trainer | | | | |||
| 61100 | Orion Township | Oakland | 11151 | 11151 | | n | NP | | 261100 | 3005103 | 705939 | n | | | | | | meter | | | | | | | | | | | | |||
| 61400 | Oshtemo Charter Township | Kalamazoo | 11636 | 11636 | NO | n | NP | | 261400 | 3153071 | 854585 | n | 46111 | | | y | | meter | | | | | | | | | | | | |||
| 62460 | Park Township | Ottawa | 9781 | 9781 | yes | Y | np | | 262460 | 2490943 | 1934964 | no | 46107 | | | | | | | | | | | kgreendyke@parktownship.org | | Krista Greendyke | | | | |||
| 64660 | Plainfield Twp | Kent | 3410 | 3410 | yes | n | NP | | 264660 | 3823044 | 750973 | YES | 3.26 | 3.9 | 46100 | y | | meter | | | | | | porzondekt@plainfieldmi.org | | Tina Porzondek | | | | |||
| 75560 | Spencer Twp | Kent | 11187 | 11187 | | n | NP | | 275560 | 12749130 | 1874968 | yes | | | | | | meter | | | | | | clerk@spencertwp.org | | Lisa Wright | | | | |||
| 75840 | Spring Lake Twp | Ottawa | 8681 | 86811 | | Y | FC | | 275840 | 4579356 | | Yes | | | | | | | | | | | | amuskovin@springlaketwp.org | | Andria Muskovin | | | | |||
| 77980 | Tallmadge Charter Township | Kent | 9713 | | | n | std | | 277980 | 7214186 | N/A | yes | | | | | | meter | | | | | | | | | | | | |||
| 79300 | Texas Township | Kalamazoo | 12572 | 12572 | yes | n | std | | 279300 | 3135114 | N/A | Yes | 46111 | 46091 | 46100 | yes | | meter | | | | | | emilyb@texastownship.org | | Emily Beutel | | | | |||
| | this color means double check | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |||
| 79620 | Thornapple Township | Barry | 11641 | 11641 | | Y | NP | | 279620 | 8799409 | 1836688 | Yes | | | | | | meter | | | | | | clerk@thornapple-twp.org | | Cindy Ordway | | | | |||
| 81140 | Tyrone Township | Kent | 12587 | 12587 | | n | NP | | 281140 | 20737717 | 1879982 | yes | | | | | | meter | | | | | | sworley@tyronetownship.org | | | | | | |||
| 81920 | Vergennes Twp | Kent | 6242 | 6242 | | n | NP | | 281920 | 6652537 | 1914002 | YES | | | | | | meter | | | | | | clerk@vergennestwp.org | | Shantell Ford | | | | |||
| 87440 | Williamstown Twp | Ingham | 10141 | 10141 | | Y | NP | | 287440 | 326746 | N/A | YES | | | | | | meter | | | | | | robin@williamstownmi.gov | | Robin Cleavland | | | | |||
| 88820 | Wright Township | Ottawa | 12005 | 12005 | | Y | PS FC | | 288820 | 5983487 | | YES | | | | | | | | | | | | clerk@ocwrighttwp.org | deputyclerk@ocwrighttwp.org | Theresa Frank | Denise Terpstra | | | |||
| 89280 | Zeeland Twp | Ottawa | 10267 | 10267 | yes | n | std | | 289280 | 2466991 | | yes | tbd 3.26.26 | | | | | meter | | | | | | kate.kraak@zeelandtwp.org | kate.kraak@zeelandtwp.org | Kate Kraak | | | | |||
| 65940 | Port Sheldon Township | Ottawa | 11716 | 11716 | yes | n | NP | | 265940 | 4594979 | 1927501 | yes | | 46083 | 46100 | tbd | | | | | | | | | | | | | | |||
| 65560 | City of Portage | Kalamazoo | 9496 | 9496 | yes | n | NP | | 265560 | 3804308 | 727793 | yes | 3.26.26 | 46090 | 46099 | yes | | meter | | y | y | y | | | | | | | | |||
| 52180 | City of Mason | | 11556 | 11556 | yes | n | std | | 252180 | 36061083 | | | | | | | | | | | | | | | | | | | | |||
| | | | | | | | | | | | | | | | 3.18 | yes | | meter | | y | y | y | | | | | | | | |||
+ 1446
- 0
_bmad-output/planning-artifacts/epics.md
La diferencia del archivo ha sido suprimido porque es demasiado grande
Ver fichero
+ 290
- 0
_bmad-output/planning-artifacts/implementation-readiness-report-2026-05-05.md
Ver fichero
| @@ -0,0 +1,290 @@ | |||
| --- | |||
| stepsCompleted: | |||
| - step-01-document-discovery | |||
| - step-02-prd-analysis | |||
| - step-03-epic-coverage-validation | |||
| - step-04-ux-alignment | |||
| - step-05-epic-quality-review | |||
| - step-06-final-assessment | |||
| assessmentDate: "2026-05-05" | |||
| project: "Brians Client Route Reports App" | |||
| documentsSelected: | |||
| prd: "_bmad-output/planning-artifacts/prd.md" | |||
| architecture: "_bmad-output/planning-artifacts/architecture.md" | |||
| epics: "_bmad-output/planning-artifacts/epics.md" | |||
| ux: "_bmad-output/planning-artifacts/ux-design-specification.md" | |||
| --- | |||
| # Implementation Readiness Assessment Report | |||
| **Date:** 2026-05-05 | |||
| **Project:** Brians Client Route Reports App | |||
| ## Step 1 - Document Discovery | |||
| ### PRD Files Found | |||
| **Whole Documents:** | |||
| - `prd.md` (24,991 bytes, modified 2026-05-05 11:49 AM) | |||
| **Sharded Documents:** | |||
| - None found | |||
| ### Architecture Files Found | |||
| **Whole Documents:** | |||
| - `architecture.md` (10,594 bytes, modified 2026-05-05 11:51 AM) | |||
| **Sharded Documents:** | |||
| - None found | |||
| ### Epics & Stories Files Found | |||
| **Whole Documents:** | |||
| - `epics.md` (78,726 bytes, modified 2026-05-05 11:51 AM) | |||
| **Sharded Documents:** | |||
| - None found | |||
| ### UX Design Files Found | |||
| **Whole Documents:** | |||
| - `ux-design-specification.md` (37,892 bytes, modified 2026-05-05 11:51 AM) | |||
| **Sharded Documents:** | |||
| - None found | |||
| ### Issues Found | |||
| - No duplicate whole/sharded document conflicts found. | |||
| - No missing required core planning documents found. | |||
| ### Document Set Confirmation | |||
| Proceeding with the four whole documents listed above as the authoritative assessment set. | |||
| ## Step 2 - PRD Analysis | |||
| ### Functional Requirements | |||
| FR1: Client services staff can create and maintain municipality account profiles linked to existing jurisdiction identifiers. | |||
| FR2: Client services staff can store and update municipality operational mailing and delivery addresses for election services. | |||
| FR3: Client services staff can manage municipality service-contact records, including primary and secondary contacts. | |||
| FR4: Client services staff can view municipality-specific service defaults from prior election cycles. | |||
| FR5: Client services staff can create a new election-cycle job for a municipality without altering legacy Access tables. | |||
| FR6: Client services staff can define election-cycle key dates for data files, proofing, pickups, deliveries, and mail activities. | |||
| FR7: Client services staff can copy configurable planning defaults from the municipality's prior election-cycle job. | |||
| FR8: Operations users can mark required planning fields complete and see readiness status for each election-cycle job. | |||
| FR9: Client services staff can configure addressing service for an election-cycle job, including quantities and dependency fields. | |||
| FR10: Client services staff can configure envelope service options including purple and blue envelope scenarios. | |||
| FR11: Client services staff can configure office-copy requirements and related production details. | |||
| FR12: Client services staff can configure sorting service options including quantity, class, permit/meter, and daily-sort flags. | |||
| FR13: Users can record transportation-relevant service events tied to configured services. | |||
| FR14: Operations users can schedule and update milestone dates for all configured service events. | |||
| FR15: Operations users can view milestone timelines by municipality and by date across active election-cycle jobs. | |||
| FR16: Operations users can detect missing or conflicting required milestones before execution cutoffs. | |||
| FR17: Operations users can reassign milestone ownership and due dates across teams. | |||
| FR18: Production users can update job status at defined process checkpoints. | |||
| FR19: Support and operations users can log exceptions, blockers, and resolution notes against an election-cycle job. | |||
| FR20: Users can record status transitions with timestamped history for key operational events. | |||
| FR21: Users can view current and historical process state for a municipality's election-cycle jobs. | |||
| FR22: Users can generate a transportation report grouped by date and sorted by county and municipality context. | |||
| FR23: Users can generate a sorting report by municipality for all jobs with sorting enabled. | |||
| FR24: Users can generate a sorting report by mail date for all jobs with sorting enabled. | |||
| FR25: Users can export operational reports for downstream consumption in spreadsheet-compatible formats. | |||
| FR26: Users can filter reports by date ranges, municipality, county, and service-status criteria. | |||
| FR27: Administrators can manage user roles and permissions for client services, production, transportation, support, and admin functions. | |||
| FR28: Administrators can manage extension-layer reference values used by planning and status workflows. | |||
| FR29: Administrators can define required-field rules for election-cycle readiness checks. | |||
| FR30: Administrators can configure notification/escalation rules for missed or at-risk milestones. | |||
| FR31: System users can link extension records to existing legacy identifiers (`ID`, `JCode`/`JurisCode`, `KitID`) for unified workflows. | |||
| FR32: Administrators can run compatibility validation checks that confirm legacy-table schemas remain unchanged. | |||
| FR33: Support users can trace report values back to source records across legacy and extension datasets. | |||
| FR34: Authorized users can correct extension-layer data issues without direct edits to immutable legacy tables. | |||
| FR35: Authorized operations users can import election-cycle operational schedule data from approved spreadsheet templates, map rows to legacy-linked municipality identifiers, and stage changes for review before publish. | |||
| FR36: Authorized users can manage proofing/contact workflow status (`Proof Sent`, `Proof Approved`, contact assignments) with full audit history and role-based visibility. | |||
| Total FRs: 36 | |||
| ### Non-Functional Requirements | |||
| NFR1: 95% of authenticated page loads for core workflows complete in 2 seconds or less under normal operating load. | |||
| NFR2: 95% of create/update operations for election-cycle records complete with user confirmation in 1 second or less. | |||
| NFR3: Transportation and sorting report generation completes in 30 seconds or less for standard daily/weekly filters. | |||
| NFR4: 100% of application traffic is encrypted in transit using TLS 1.2+ and verified by quarterly transport-security scans. | |||
| NFR5: 100% of sensitive stored operational data is encrypted at rest with platform-managed AES-256 controls, verified by monthly configuration audits. | |||
| NFR6: 100% of privileged operations enforce role-based authorization checks, and unauthorized requests are blocked and logged. | |||
| NFR7: Security-relevant actions (authentication events and permission-sensitive updates) are logged within 5 seconds and retained for at least 365 days. | |||
| NFR8: The system supports at least 10x growth in active election-cycle job volume without requiring legacy schema changes. | |||
| NFR9: The system supports at least 150 concurrent operational users with p95 response time under 2 seconds and error rate under 1% during peak-period load testing. | |||
| NFR10: MVP screens for forms, tables, and reports meet WCAG 2.1 AA-aligned criteria relevant to keyboard access, labeling, contrast, and focus visibility. | |||
| NFR11: 100% of critical workflows are operable by keyboard-only interaction and validated against an accessibility test checklist in each release. | |||
| NFR12: Legacy Access tables are treated as immutable dependencies, and release gates fail on any unauthorized schema delta against the approved baseline. | |||
| NFR13: Extension-table joins to legacy identifiers maintain at least 99.9% referential consistency, verified by nightly integrity checks and pre-release validation runs. | |||
| NFR14: Exported report datasets preserve required field parity for existing operational consumers. | |||
| NFR15: Planned system availability target is 99.5% monthly during operational hours. | |||
| NFR16: Every key milestone/status update is stored with audit history sufficient for operational reconstruction. | |||
| NFR17: Recovery procedures ensure no committed extension-record updates are lost for the previous 24 hours of operations. | |||
| NFR18: 100% of imported spreadsheet rows store provenance metadata (source file identifier, row reference, import timestamp, importing user). | |||
| NFR19: Import validation detects join-key mismatches and required-field gaps before publish, with deterministic error output and zero silent row drops. | |||
| Total NFRs: 19 | |||
| ### Additional Requirements | |||
| - Immutable legacy-schema policy for Access tables. | |||
| - Join-key integrity across `ID`, `JCode/JurisCode`, and `KitID`. | |||
| - Spreadsheet-compatible import/export integration with operational tooling. | |||
| - Govtech compliance intent: accessibility, security, auditability, and data residency/procurement evidence constraints. | |||
| ### PRD Completeness Assessment | |||
| - PRD contains a complete and explicit FR/NFR set including the newly approved spreadsheet-source scope. | |||
| - Requirements are sufficiently concrete for coverage validation in epics/stories. | |||
| - Readiness risk remains around implementation detail quality, not requirement discovery completeness. | |||
| ## Step 3 - Epic Coverage Validation | |||
| ### Coverage Matrix | |||
| | FR | Epic Coverage | Status | | |||
| | --- | --- | --- | | |||
| | FR1 | Epic 1 / Story 1.10 | Covered | | |||
| | FR2 | Epic 1 / Story 1.11 | Covered | | |||
| | FR3 | Epic 1 / Story 1.12 | Covered | | |||
| | FR4 | Epic 1 / Story 1.13 | Covered | | |||
| | FR5 | Epic 2 / Story 2.2 | Covered | | |||
| | FR6 | Epic 2 / Story 2.3 | Covered | | |||
| | FR7 | Epic 2 / Story 2.4 | Covered | | |||
| | FR8 | Epic 2 / Story 2.5 | Covered | | |||
| | FR9 | Epic 3 / Story 3.1 | Covered | | |||
| | FR10 | Epic 3 / Story 3.2 | Covered | | |||
| | FR11 | Epic 3 / Story 3.3 | Covered | | |||
| | FR12 | Epic 3 / Story 3.4 | Covered | | |||
| | FR13 | Epic 3 / Story 3.5 | Covered | | |||
| | FR14 | Epic 4 / Story 4.1 | Covered | | |||
| | FR15 | Epic 4 / Story 4.2 | Covered | | |||
| | FR16 | Epic 4 / Story 4.3 | Covered | | |||
| | FR17 | Epic 4 / Story 4.4 | Covered | | |||
| | FR18 | Epic 5 / Story 5.1 | Covered | | |||
| | FR19 | Epic 5 / Story 5.2 | Covered | | |||
| | FR20 | Epic 5 / Story 5.4 | Covered | | |||
| | FR21 | Epic 5 / Story 5.5 | Covered | | |||
| | FR22 | Epic 5 / Story 5.6 | Covered | | |||
| | FR23 | Epic 6 / Story 6.1 | Covered | | |||
| | FR24 | Epic 6 / Story 6.2 | Covered | | |||
| | FR25 | Epic 6 / Story 6.3 | Covered | | |||
| | FR26 | Epic 6 / Story 6.3 | Covered | | |||
| | FR27 | Epic 1 / Story 1.4 + 1.9 | Covered | | |||
| | FR28 | Epic 1 seed + Epic 6 / Story 6.6 | Covered | | |||
| | FR29 | Epic 1 seed + Epic 6 / Story 6.6 | Covered | | |||
| | FR30 | Epic 1 seed + Epic 6 / Story 6.6 | Covered | | |||
| | FR31 | Epic 1 / Story 1.8 | Covered | | |||
| | FR32 | Epic 1 / Story 1.7 | Covered | | |||
| | FR33 | Epic 6 / Story 6.4 | Covered | | |||
| | FR34 | Epic 6 / Story 6.5 | Covered | | |||
| | FR35 | Epic 2 / Story 2.6 | Covered (new) | | |||
| | FR36 | Epic 3 / Story 3.2 acceptance additions | Covered (new) | | |||
| ### Missing Requirements | |||
| - No uncovered FRs found. | |||
| - Traceability note: the epics FR coverage map block currently lists FR1-FR34 only; FR35-FR36 are implemented in stories but should be added to the formal mapping section for consistency. | |||
| ### Coverage Statistics | |||
| - Total PRD FRs: 36 | |||
| - FRs covered in epics/stories: 36 | |||
| - Coverage percentage: 100% | |||
| ## Step 4 - UX Alignment Assessment | |||
| ### UX Document Status | |||
| - Found: `_bmad-output/planning-artifacts/ux-design-specification.md` | |||
| ### Alignment Issues | |||
| - FR35/FR36 are now represented in UX addendum flows, but the original UX body still assumes pre-import workflow; import/reconciliation is currently captured as addendum rather than integrated into core journey sections. | |||
| ### Confirmed Alignments | |||
| - PRD deterministic reporting and traceability goals align with UX components (`DispatchRunBuilder`, `ProvenanceTimelinePanel`) and architecture parity/reconciliation controls. | |||
| - Performance-sensitive dense operations model is consistently reflected across PRD, UX, and architecture. | |||
| - New source integration is aligned across all three artifacts via approved addendums (import workflow, provenance, reconciliation queue). | |||
| ### Warnings | |||
| - Low warning: merge addendum updates into base UX journey sections in a future documentation cleanup pass for clarity. | |||
| ## Step 5 - Epic Quality Review | |||
| ### Epic Structure Validation | |||
| - User-value orientation: Pass | |||
| - Epics are framed around coordinator, production, transportation, support, and admin outcomes. | |||
| - Epic independence: Pass with minor concerns | |||
| - Sequence is generally valid (Epic 1 foundation, then operational workflows). | |||
| - No blocking dependency found where an epic requires a future epic to be functional. | |||
| ### Story Quality Assessment | |||
| - Story sizing: Generally appropriate for implementation units. | |||
| - Acceptance criteria quality: Mostly strong BDD-style `Given/When/Then` with testable outcomes. | |||
| - Dependency direction: No hard forward dependencies detected; reused components mostly reference prior stories. | |||
| ### Special Implementation Checks | |||
| - Starter template requirement: Pass | |||
| - Epic 1 Story 1.1 includes explicit scaffold and starter commands. | |||
| - Brownfield indicators: Pass | |||
| - Legacy immutability, compatibility checks, and identifier-linking stories are present. | |||
| ### Findings by Severity | |||
| #### Critical | |||
| - None found. | |||
| #### Major | |||
| - None found. | |||
| #### Minor | |||
| - Documentation cohesion: | |||
| - Newly added source-integration changes are captured, but some are in addendum-style sections rather than integrated into original epic narrative blocks. | |||
| - Recommendation: fold addendum content into base sections during next documentation maintenance pass. | |||
| ### Best-Practices Compliance Checklist | |||
| - [x] Epic delivers user value | |||
| - [x] Epic can function independently | |||
| - [x] Stories appropriately sized | |||
| - [x] No forward dependencies that block delivery | |||
| - [x] Data model creation aligned to need timing | |||
| - [x] Clear acceptance criteria | |||
| - [x] Traceability to FRs maintained | |||
| ## Summary and Recommendations | |||
| ### Overall Readiness Status | |||
| READY | |||
| ### Critical Issues Requiring Immediate Action | |||
| - No critical or major blockers remain. | |||
| ### Recommended Next Steps | |||
| 1. Keep Story 2.6 and Story 6.8 implementation near the front of backlog execution to reduce source-data risk early. | |||
| 2. Integrate addendum details back into base UX narrative sections during routine documentation maintenance. | |||
| 3. Proceed to sprint planning/implementation sequencing. | |||
| ### Final Note | |||
| This assessment identified no remaining critical or major issues after approved corrections, with one minor documentation-cohesion recommendation. | |||
| Assessor: Codex (AI pair agent) | |||
| Assessment Date: 2026-05-05 | |||
+ 397
- 0
_bmad-output/planning-artifacts/prd.md
Ver fichero
| @@ -0,0 +1,397 @@ | |||
| --- | |||
| stepsCompleted: | |||
| - step-01-init | |||
| - step-02-discovery | |||
| - step-02b-vision | |||
| - step-02c-executive-summary | |||
| - step-03-success | |||
| - step-04-journeys | |||
| - step-05-domain | |||
| - step-06-innovation | |||
| - step-07-project-type | |||
| - step-08-scoping | |||
| - step-09-functional | |||
| - step-10-nonfunctional | |||
| - step-11-polish | |||
| - step-12-complete | |||
| inputDocuments: | |||
| - Initial Description.txt | |||
| - Initial Documents/Access_Schema.txt | |||
| - Initial Documents/Client Database Plan.xlsx | |||
| - _bmad-output/planning-artifacts/client-database-plan-extract.txt | |||
| - https://docs.google.com/spreadsheets/d/1l77Hvw-vmdE8FnByxr7Ink4zMtp66iAc/edit?gid=1537818588 | |||
| - docs/source-2026-08-primary-ballot-envelope-tracking.md | |||
| documentCounts: | |||
| briefCount: 0 | |||
| researchCount: 0 | |||
| brainstormingCount: 0 | |||
| projectDocsCount: 6 | |||
| workflowType: "prd" | |||
| date: "2026-04-03" | |||
| classification: | |||
| projectType: web_app | |||
| domain: govtech | |||
| complexity: high | |||
| projectContext: brownfield | |||
| --- | |||
| # Product Requirements Document - Brians Client Route Reports App | |||
| **Author:** Daniel | |||
| **Date:** 2026-04-03 | |||
| ## Executive Summary | |||
| This product modernizes a production Microsoft Access workflow used to support municipality election mail services and job tracking. The system must preserve existing operational behavior while improving reliability, planning depth, reporting quality, and day-to-day usability for client account and production teams. | |||
| The application will manage two distinct but connected data horizons: permanent municipality account data and recurring election-cycle operational work. It will support planning and execution for addressing, sorting, purple/blue envelope workflows, office copies, transportation events, contacts, key dates, and production status through election completion. | |||
| The modernization strategy is additive and compatibility-first: legacy Access tables remain immutable, and all enhancements are implemented through extension tables and joinable queries/views keyed by existing IDs/Jurisdiction codes. This lowers migration risk, enables phased rollout, and preserves trust in existing production data. | |||
| ### What Makes This Special | |||
| The differentiator is controlled modernization without schema disruption. Instead of replacing the legacy model, the product introduces a structured election-operations layer that overlays current production data and workflows. | |||
| This creates a practical path to improve planning, scheduling, tracking, and reporting while retaining historical continuity and operator familiarity. Teams get modern cross-process visibility and repeatable election-cycle execution without sacrificing the known-good legacy backbone. | |||
| ## Project Classification | |||
| - Project Type: `web_app` (internal operations and reporting application) | |||
| - Domain: `govtech` (municipal election services operations) | |||
| - Complexity: `high` (regulated, date-critical, operations-sensitive workflows) | |||
| - Project Context: `brownfield` (modernizing an existing production Access system) | |||
| ## Success Criteria | |||
| ### User Success | |||
| - Operations staff can create and maintain municipality account profiles, election-cycle jobs, and service configurations without editing legacy Access tables. | |||
| - Teams can see all critical election milestones (data files, envelope pickups/deliveries, sort dates, mail dates, tray deliveries, office-copy status) in one workflow view. | |||
| - Users can generate transportation and sorting reports in exportable formats (CSV/Excel-equivalent) in under 30 seconds for normal daily workloads. | |||
| - At least 80% of operations users report improved cross-team coordination in post-cycle surveys after the first full election cycle. | |||
| ### Business Success | |||
| - Election job setup time is reduced by at least 40% compared to the current Access-centric process within the first full election cycle after launch. | |||
| - Missed or late operational dates (pickup, delivery, sorting milestones) are reduced by at least 60% through centralized scheduling and status visibility. | |||
| - Reporting preparation effort for recurring transportation/sorting updates is reduced by at least 50%. | |||
| - Legacy workflow continuity is preserved with zero required changes to existing Access table schemas. | |||
| ### Technical Success | |||
| - All original Access tables remain unchanged (no add/drop/alter on legacy tables). | |||
| - New capabilities are implemented only via extension tables and join queries/views keyed by existing identifiers (`ID`, `JCode`/`JurisCode`, `KitID` where applicable). | |||
| - Permanent municipality data and election-cycle operational data are separated at the model level while remaining joinable for reporting. | |||
| - Core reporting queries execute within agreed performance targets and support repeatable export jobs. | |||
| - Auditability is available for extension-table updates affecting key operational milestones and statuses. | |||
| ### Measurable Outcomes | |||
| - 95% of active municipality accounts can be represented in the new application with complete required permanent account fields. | |||
| - 95% of active election jobs have complete milestone schedules before production kickoff. | |||
| - 90% of transportation events required for a 7-day lookahead are captured and visible in date-sorted operational reports. | |||
| - 99% of generated operational reports match source-of-truth job records with no critical field omissions. | |||
| - 100% of legacy-table compatibility checks pass during each release gate. | |||
| ## Product Scope | |||
| ### MVP - Minimum Viable Product | |||
| - Municipality account management layer (extension model) joined to legacy jurisdiction/contact records. | |||
| - Election-cycle job planning and service configuration for addressing, sorting, envelopes (purple/blue), office copies, transportation milestones, and key dates. | |||
| - Operational status tracking for production-relevant events and handoffs. | |||
| - Core reports: | |||
| - Transportation report grouped/sorted by date and municipality context. | |||
| - Sorting report by municipality. | |||
| - Sorting report by mail date. | |||
| - Export support for operational reports and baseline role-based access. | |||
| ### Growth Features (Post-MVP) | |||
| - Advanced scheduling views (calendar/board), conflict detection, and reminder workflows. | |||
| - Enhanced production analytics (throughput, cycle times, delay root-cause categories). | |||
| - Configurable templates for recurring election-cycle defaults by municipality. | |||
| - Deeper communication tooling (notification routing, contact role preferences, escalation paths). | |||
| ### Vision (Future) | |||
| - Predictive election operations planning (capacity/risk forecasting by workload and date concentration). | |||
| - Comprehensive cross-election performance benchmarking and trend reporting. | |||
| - Optional integration layer for downstream/adjacent operational systems while preserving immutable legacy core tables. | |||
| ## User Journeys | |||
| ### Journey 1: Client Services Coordinator - Election Setup Success Path | |||
| Opening scene: A coordinator receives notice of an upcoming municipality election and must configure services quickly without breaking legacy records. | |||
| Rising action: They select the municipality, review permanent account details, open a new election cycle record, and configure addressing, envelope options, sorting, office copies, transportation milestones, and key dates using defaults from prior cycles where available. | |||
| Climax: The coordinator validates that all required milestones are complete and publishes the election job to production readiness. | |||
| Resolution: The team starts execution with a complete and date-driven plan, and no one needs to edit Access tables manually. | |||
| ### Journey 2: Production Lead - Edge Case and Recovery Path | |||
| Opening scene: The production lead sees an upcoming mail date but notices missing data-file schedule and unresolved blue envelope quantities. | |||
| Rising action: They open job timeline details, identify missing dependencies, assign updates to client services, and add a risk note with due-by timestamps. | |||
| Climax: The blocking fields are completed before the operational cutoff, and downstream activities (sorting/transport) are rescheduled automatically in the plan view. | |||
| Resolution: The election job avoids delay, and the exception handling history is preserved for post-cycle review. | |||
| ### Journey 3: Operations Administrator - Configuration and Governance | |||
| Opening scene: An administrator needs to manage shared service defaults and reporting visibility while preserving immutable legacy schema constraints. | |||
| Rising action: They maintain extension-table reference values (status sets, service templates, reminder rules, role permissions), verify joins to legacy identifiers, and run compatibility checks. | |||
| Climax: Admin validates that all new features continue to read legacy tables without structural dependency on schema changes. | |||
| Resolution: Teams gain controlled flexibility, while governance confirms compatibility and audit requirements are intact. | |||
| ### Journey 4: Transportation Coordinator - Daily Dispatch Planning | |||
| Opening scene: The transportation coordinator prepares next-day and week-lookahead runs across multiple municipalities. | |||
| Rising action: They execute a date-sorted transportation report that consolidates pickup and delivery events from customer envelope, purple/blue envelope, tray delivery, and ballot sort milestones. | |||
| Climax: Coordinator finalizes grouped stop lists by county and municipality with quantity-driven notes for what must move on each date. | |||
| Resolution: Dispatch execution is clear, predictable, and tied directly to election job milestones. | |||
| ### Journey 5: Support Analyst - Issue Investigation and Reporting | |||
| Opening scene: A municipality asks why a sort-related milestone appears incomplete in a status update. | |||
| Rising action: Support traces the job across extension records and joined legacy identifiers, reviews event-history changes, and compares report output against source records. | |||
| Climax: Analyst identifies a missing status transition and corrects it with a documented reason code. | |||
| Resolution: Client-facing reporting is corrected quickly, and the team retains an auditable issue-resolution trail. | |||
| ### Journey Requirements Summary | |||
| - Role-based workflows for client services, production, operations admin, transportation, and support. | |||
| - Election-cycle record lifecycle with required-field validation and dependency tracking. | |||
| - Exception/risk handling model with assignment, due dates, and status transitions. | |||
| - Date-centric consolidated reporting for transportation and sorting operations. | |||
| - Audit-friendly history for milestone and status changes. | |||
| - Compatibility controls that enforce immutable legacy-table usage while enabling extension growth. | |||
| - Municipality account completeness target is directly supported by Journey 1 and FR1-F4 (account profile, address, contact, and defaults coverage). | |||
| ## Domain-Specific Requirements | |||
| ### Compliance & Regulatory | |||
| - Support municipal/government operational expectations for records accuracy, traceability, and accountability. | |||
| - Maintain audit-ready histories for key election operational milestones and status changes. | |||
| - Ensure accessibility-oriented UI requirements are included for internal government users and procurement expectations. | |||
| - Preserve evidence needed for internal review and external oversight of election-service operational activity. | |||
| - Define security-clearance requirements for privileged functions (admin, audit, and compliance workflows) with documented role criteria and approval controls. | |||
| - Enforce data-residency policy for operational and audit records in approved jurisdictions defined by contracting municipalities. | |||
| - Define procurement compliance acceptance criteria, including required evidence artifacts for accessibility, security, and data-governance claims. | |||
| ### Technical Constraints | |||
| - Enforce immutable legacy-table policy at the application and migration level. | |||
| - Implement least-privilege access with role-segmented permissions across client services, production, transportation, and admin functions. | |||
| - Protect sensitive operational data in transit and at rest using platform-standard encryption controls. | |||
| - Require deterministic join logic between extension and legacy tables to avoid ambiguity in operational reporting. | |||
| ### Integration Requirements | |||
| - Join extension entities with legacy Access-derived entities using existing identifiers (`ID`, `JCode`/`JurisCode`, `KitID`). | |||
| - Support ingest and export workflows aligned with existing operational tools and spreadsheet-driven coordination. | |||
| - Preserve compatibility with existing report consumers by maintaining equivalent output columns for transportation/sorting reports where feasible. | |||
| ### Risk Mitigations | |||
| - Risk: schema drift from legacy expectations. | |||
| Mitigation: block structural changes to legacy tables; validate joins and compatibility in release gates. | |||
| - Risk: missed operational dates in high-volume election windows. | |||
| Mitigation: milestone dependency checks, due-date visibility, and exception escalation. | |||
| - Risk: inconsistent status truth across teams. | |||
| Mitigation: standardized status transitions and auditable update history. | |||
| - Risk: reporting mismatches during migration. | |||
| Mitigation: parallel report validation against legacy outputs before cutover. | |||
| ## Web App Specific Requirements | |||
| ### Project-Type Overview | |||
| The product is a browser-based internal operations application for municipal election-services workflows. It prioritizes data-intensive entry, schedule visibility, and report generation over public marketing and SEO concerns. | |||
| ### Technical Architecture Considerations | |||
| - Architecture: authenticated web application with server-driven data access over legacy-compatible storage abstractions. | |||
| - Interaction model: multi-screen workflow optimized for repeated operational data entry and cross-team status updates. | |||
| - Real-time strategy: near-real-time status refresh for shared operational boards; strict real-time streaming is optional for MVP. | |||
| - Accessibility strategy: keyboard-friendly, readable, and compliant operational UI patterns suitable for government usage contexts. | |||
| ### Browser Matrix | |||
| - Primary: current and previous major versions of Chrome and Edge (Windows-first operations environment). | |||
| - Secondary: current Firefox and Safari support for management/reporting access. | |||
| - Graceful degradation: advanced visualizations may be simplified when unsupported; core data workflows must remain functional. | |||
| ### Responsive Design | |||
| - Primary target: desktop and laptop breakpoints for office operations. | |||
| - Tablet and mobile optimization are out of current MVP scope; narrow viewports are supported only as non-primary read-only fallbacks where feasible. | |||
| - Full create/edit operational workflows are desktop-first and required only for desktop/laptop breakpoints in this release. | |||
| ### Performance Targets | |||
| - Standard list/detail page loads: under 2 seconds for common filtered datasets. | |||
| - Save/update actions: user-visible confirmation within 1 second under normal load. | |||
| - Operational report generation: under 30 seconds for daily and weekly planning windows. | |||
| - Background checks (dependency/validation): complete without blocking UI interactions where possible. | |||
| ### SEO Strategy | |||
| - Public SEO is out of scope. The application is private/authenticated and focused on internal operational workflows. | |||
| ### Accessibility Level | |||
| - Minimum baseline: WCAG 2.1 AA-aligned patterns for internal forms, tables, and reporting screens. | |||
| - Required capabilities: keyboard navigation, clear labels/error messaging, focus management, and sufficient contrast for dense operational views. | |||
| ### Implementation Considerations | |||
| - Exclude native-device feature assumptions and CLI-first interaction patterns from scope. | |||
| - Prioritize maintainable component patterns for tables, timelines, status chips, and export actions. | |||
| - Validate that every new UI workflow maps cleanly to extension entities and joined legacy keys. | |||
| ## Project Scoping & Phased Development | |||
| ### MVP Strategy & Philosophy | |||
| **MVP Approach:** Compatibility-first operations MVP focused on replacing fragile spreadsheet/manual coordination while preserving legacy Access table integrity. | |||
| **Resource Requirements:** Product owner/domain lead, full-stack engineer, data engineer/DBA, QA analyst, and part-time operations SME support. | |||
| ### MVP Feature Set (Phase 1) | |||
| **Core User Journeys Supported:** | |||
| - Election setup by client services coordinator | |||
| - Production lead dependency and exception management | |||
| - Transportation planning and dispatch preparation | |||
| - Support issue trace and correction workflow | |||
| **Must-Have Capabilities:** | |||
| - Immutable legacy data integration layer | |||
| - Extension-table model for municipality and election-cycle planning | |||
| - Service configuration and milestone scheduling | |||
| - Operational status tracking and exception management | |||
| - Transportation/sorting report generation and export | |||
| - Role-based access and audit-ready change history | |||
| ### Post-MVP Features | |||
| **Phase 2 (Post-MVP):** | |||
| - Proactive reminders, dependency alerts, and conflict detection | |||
| - Enhanced dashboarding for workload balancing and delay hotspots | |||
| - Configurable per-municipality cycle templates and automation rules | |||
| **Phase 3 (Expansion):** | |||
| - Predictive planning and capacity/risk modeling | |||
| - Expanded integrations with adjacent operational systems | |||
| - Portfolio-level optimization across election cycles and regions | |||
| ### Risk Mitigation Strategy | |||
| **Technical Risks:** Legacy join correctness and performance regression. | |||
| Mitigation: compatibility test suites, query baseline checks, staged rollout with parallel report verification. | |||
| **Market Risks:** Under-adoption due to workflow mismatch. | |||
| Mitigation: phased onboarding with operations-team validation and side-by-side report parity during transition. | |||
| **Resource Risks:** Delivery delays from competing election-cycle priorities. | |||
| Mitigation: strict MVP scope, milestone-based releases, and deferment of advanced analytics to post-MVP phases. | |||
| ## Functional Requirements | |||
| ### Municipality & Account Management | |||
| - FR1: Client services staff can create and maintain municipality account profiles linked to existing jurisdiction identifiers. | |||
| - FR2: Client services staff can store and update municipality operational mailing and delivery addresses for election services. | |||
| - FR3: Client services staff can manage municipality service-contact records, including primary and secondary contacts. | |||
| - FR4: Client services staff can view municipality-specific service defaults from prior election cycles. | |||
| ### Election-Cycle Setup & Planning | |||
| - FR5: Client services staff can create a new election-cycle job for a municipality without altering legacy Access tables. | |||
| - FR6: Client services staff can define election-cycle key dates for data files, proofing, pickups, deliveries, and mail activities. | |||
| - FR7: Client services staff can copy configurable planning defaults from the municipality's prior election-cycle job. | |||
| - FR8: Operations users can mark required planning fields complete and see readiness status for each election-cycle job. | |||
| ### Service Configuration | |||
| - FR9: Client services staff can configure addressing service for an election-cycle job, including quantities and dependency fields. | |||
| - FR10: Client services staff can configure envelope service options including purple and blue envelope scenarios. | |||
| - FR11: Client services staff can configure office-copy requirements and related production details. | |||
| - FR12: Client services staff can configure sorting service options including quantity, class, permit/meter, and daily-sort flags. | |||
| - FR13: Users can record transportation-relevant service events tied to configured services. | |||
| ### Scheduling & Milestone Management | |||
| - FR14: Operations users can schedule and update milestone dates for all configured service events. | |||
| - FR15: Operations users can view milestone timelines by municipality and by date across active election-cycle jobs. | |||
| - FR16: Operations users can detect missing or conflicting required milestones before execution cutoffs. | |||
| - FR17: Operations users can reassign milestone ownership and due dates across teams. | |||
| ### Production Tracking & Exception Handling | |||
| - FR18: Production users can update job status at defined process checkpoints. | |||
| - FR19: Support and operations users can log exceptions, blockers, and resolution notes against an election-cycle job. | |||
| - FR20: Users can record status transitions with timestamped history for key operational events. | |||
| - FR21: Users can view current and historical process state for a municipality's election-cycle jobs. | |||
| ### Operational Reporting & Exports | |||
| - FR22: Users can generate a transportation report grouped by date and sorted by county and municipality context. | |||
| - FR23: Users can generate a sorting report by municipality for all jobs with sorting enabled. | |||
| - FR24: Users can generate a sorting report by mail date for all jobs with sorting enabled. | |||
| - FR25: Users can export operational reports for downstream consumption in spreadsheet-compatible formats. | |||
| - FR26: Users can filter reports by date ranges, municipality, county, and service-status criteria. | |||
| ### Role Administration & Workflow Governance | |||
| - FR27: Administrators can manage user roles and permissions for client services, production, transportation, support, and admin functions. | |||
| - FR28: Administrators can manage extension-layer reference values used by planning and status workflows. | |||
| - FR29: Administrators can define required-field rules for election-cycle readiness checks. | |||
| - FR30: Administrators can configure notification/escalation rules for missed or at-risk milestones. | |||
| ### Legacy Compatibility & Data Integrity Operations | |||
| - FR31: System users can link extension records to existing legacy identifiers (`ID`, `JCode`/`JurisCode`, `KitID`) for unified workflows. | |||
| - FR32: Administrators can run compatibility validation checks that confirm legacy-table schemas remain unchanged. | |||
| - FR33: Support users can trace report values back to source records across legacy and extension datasets. | |||
| - FR34: Authorized users can correct extension-layer data issues without direct edits to immutable legacy tables. | |||
| - FR35: Authorized operations users can import election-cycle operational schedule data from approved spreadsheet templates, map rows to legacy-linked municipality identifiers, and stage changes for review before publish. | |||
| - FR36: Authorized users can manage proofing/contact workflow status (`Proof Sent`, `Proof Approved`, contact assignments) with full audit history and role-based visibility. | |||
| ## Non-Functional Requirements | |||
| ### Performance | |||
| - NFR1: 95% of authenticated page loads for core workflows complete in 2 seconds or less under normal operating load. | |||
| - NFR2: 95% of create/update operations for election-cycle records complete with user confirmation in 1 second or less. | |||
| - NFR3: Transportation and sorting report generation completes in 30 seconds or less for standard daily/weekly filters. | |||
| ### Security | |||
| - NFR4: 100% of application traffic is encrypted in transit using TLS 1.2+ and verified by quarterly transport-security scans. | |||
| - NFR5: 100% of sensitive stored operational data is encrypted at rest with platform-managed AES-256 controls, verified by monthly configuration audits. | |||
| - NFR6: 100% of privileged operations enforce role-based authorization checks, and unauthorized requests are blocked and logged. | |||
| - NFR7: Security-relevant actions (authentication events and permission-sensitive updates) are logged within 5 seconds and retained for at least 365 days. | |||
| ### Scalability | |||
| - NFR8: The system supports at least 10x growth in active election-cycle job volume without requiring legacy schema changes. | |||
| - NFR9: The system supports at least 150 concurrent operational users with p95 response time under 2 seconds and error rate under 1% during peak-period load testing. | |||
| ### Accessibility | |||
| - NFR10: MVP screens for forms, tables, and reports meet WCAG 2.1 AA-aligned criteria relevant to keyboard access, labeling, contrast, and focus visibility. | |||
| - NFR11: 100% of critical workflows are operable by keyboard-only interaction and validated against an accessibility test checklist in each release. | |||
| ### Integration & Data Compatibility | |||
| - NFR12: Legacy Access tables are treated as immutable dependencies, and release gates fail on any unauthorized schema delta against the approved baseline. | |||
| - NFR13: Extension-table joins to legacy identifiers maintain at least 99.9% referential consistency, verified by nightly integrity checks and pre-release validation runs. | |||
| - NFR14: Exported report datasets preserve required field parity for existing operational consumers. | |||
| - NFR18: 100% of imported spreadsheet rows store provenance metadata (source file identifier, row reference, import timestamp, importing user). | |||
| - NFR19: Import validation detects join-key mismatches and required-field gaps before publish, with deterministic error output and zero silent row drops. | |||
| ### Reliability & Recoverability | |||
| - NFR15: Planned system availability target is 99.5% monthly during operational hours. | |||
| - NFR16: Every key milestone/status update is stored with audit history sufficient for operational reconstruction. | |||
| - NFR17: Recovery procedures ensure no committed extension-record updates are lost for the previous 24 hours of operations. | |||
+ 270
- 0
_bmad-output/planning-artifacts/sprint-change-proposal-2026-05-05.md
Ver fichero
| @@ -0,0 +1,270 @@ | |||
| # Sprint Change Proposal | |||
| ## 1) Issue Summary | |||
| - Trigger: A late source document was added on 2026-05-05: Google Sheet `AUGUST 2026 PRIMARY Ballot Envelope Imprinting and Tracking Scheduled .xlsx`. | |||
| - Context: Current planning artifacts were built from Access schema + initial client database plan artifacts and do not explicitly include this new spreadsheet as an input. | |||
| - Evidence: | |||
| - The added sheet includes operational columns not explicitly modeled as named requirements yet (for example: `Proof Sent`, `Proof Approved`, `Round Trip Y/N`, `Permit/Meter`, `MailDate`, `NP/STD`, `CRID`, contact workflow fields). | |||
| - Existing PRD covers these areas only at a generic level (for example FR6 key dates, FR12 sorting options, FR22-FR26 reporting). | |||
| ## 2) Impact Analysis | |||
| ### Epic Impact | |||
| - Epic 2 (Election-Cycle Job Creation & Planning): impacted | |||
| - Reason: new source has key date and readiness fields that should be importable or reconcilable. | |||
| - Epic 3 (Service Configuration): impacted | |||
| - Reason: envelope, sorting, and tracking detail in the sheet exceeds currently explicit field coverage. | |||
| - Epic 5/6 (Reporting): impacted | |||
| - Reason: report parity and traceability need source-to-field reconciliation for spreadsheet-origin values. | |||
| - Epic 1 and Epic 4: low-to-medium indirect impact | |||
| - Reason: join-key validation, role controls, and milestone validation rules should include imported sheet data. | |||
| ### Story Impact | |||
| - Existing stories needing updates: | |||
| - Story 2.3 (Election-Cycle Key Dates) | |||
| - Story 3.2 (Envelope Service Configuration) | |||
| - Story 3.4 (Sorting Service Configuration) | |||
| - Story 5.6 (Transportation Report) | |||
| - Story 6.4 (Report-to-Source Traceability) | |||
| - New stories recommended: | |||
| - Story 2.6 (new): Spreadsheet Import & Column Mapping | |||
| - Story 6.8 (new): Source Reconciliation & Data Quality Queue | |||
| ### Artifact Conflicts | |||
| - PRD: requires explicit requirements for spreadsheet import/mapping/provenance and contact/proof workflow coverage. | |||
| - Architecture: requires ingestion boundary, mapping registry, validation pipeline, and provenance storage design. | |||
| - UX: requires import/review/reconciliation flow and role-safe handling of contact fields. | |||
| ### Technical Impact | |||
| - Add ingestion flow (manual upload or Google Sheet export import path). | |||
| - Add validation and mapping rules for jurisdiction join-key matching. | |||
| - Add provenance metadata and reconciliation flags. | |||
| - Add role-based field masking/visibility for contact data. | |||
| ## 3) Recommended Approach | |||
| - Selected approach: **Hybrid (Option 1 Direct Adjustment + Option 3 PRD MVP Review)** | |||
| - Why: | |||
| - We can preserve current MVP direction and timeline by adjusting existing epics/stories. | |||
| - We should still update PRD scope language so new source-derived capabilities are explicitly testable. | |||
| - Rollback: **Not recommended** (no implementation rollback value at current stage). | |||
| - Estimated effort: **Medium** | |||
| - Risk: **Medium** | |||
| - Timeline impact: **+1 sprint buffer** unless import/reconciliation is phased (recommended phase-in). | |||
| ## 4) Detailed Change Proposals | |||
| ### PRD Changes | |||
| Change P1 | |||
| Section: Frontmatter `inputDocuments` | |||
| OLD: | |||
| - `Initial Description.txt` | |||
| - `Initial Documents/Access_Schema.txt` | |||
| - `Initial Documents/Client Database Plan.xlsx` | |||
| - `_bmad-output/planning-artifacts/client-database-plan-extract.txt` | |||
| NEW: | |||
| - Keep existing entries | |||
| - Add: `https://docs.google.com/spreadsheets/d/1l77Hvw-vmdE8FnByxr7Ink4zMtp66iAc/edit?gid=1537818588` | |||
| - Add: `docs/source-2026-08-primary-ballot-envelope-tracking.md` | |||
| Rationale: preserve auditability of late requirements input. | |||
| Change P2 | |||
| Section: Functional Requirements (append after FR34) | |||
| OLD: | |||
| - FR34: Authorized users can correct extension-layer data issues without direct edits to immutable legacy tables. | |||
| NEW: | |||
| - FR35: Authorized operations users can import election-cycle operational schedule data from approved spreadsheet templates, map rows to legacy-linked municipality identifiers, and stage changes for review before publish. | |||
| - FR36: Authorized users can manage proofing/contact workflow status (`Proof Sent`, `Proof Approved`, contact assignments) with full audit history and role-based visibility. | |||
| Rationale: explicitly cover newly introduced operational fields and workflow responsibilities. | |||
| Change P3 | |||
| Section: Non-Functional Requirements (append) | |||
| OLD: | |||
| - No explicit ingestion provenance/validation SLA. | |||
| NEW: | |||
| - NFR18: 100% of imported spreadsheet rows must store provenance metadata (source file identifier, row reference, import timestamp, importing user). | |||
| - NFR19: Import validation must detect join-key mismatches and required-field gaps before publish, with deterministic error output and zero silent drops. | |||
| Rationale: prevents hidden data drift and supports regulated traceability expectations. | |||
| ### Epics and Stories Changes | |||
| Change E1 | |||
| Artifact: `epics.md` | |||
| Section: Epic 2 | |||
| OLD: | |||
| - Epic 2 ends at Story 2.5. | |||
| NEW: | |||
| - Add Story 2.6: Spreadsheet Import & Column Mapping | |||
| - Parse approved sheet template columns | |||
| - Map to extension-layer fields | |||
| - Validate `ID/JCode/JurisCode/KitID` match rules | |||
| - Stage records and show publish-ready status | |||
| Rationale: early ingestion capability prevents manual re-entry and late-cycle errors. | |||
| Change E2 | |||
| Artifact: `epics.md` | |||
| Section: Epic 3 Story 3.2 and Story 3.4 acceptance criteria | |||
| OLD: | |||
| - Covers envelope and sorting at a generic configuration level. | |||
| NEW: | |||
| - Add acceptance criteria for explicit support of fields derived from the new source where applicable: | |||
| - proofing status fields | |||
| - daily sort behavior tied to mail date consistency checks | |||
| - permit/meter and related classification flags | |||
| Rationale: aligns service-configuration behavior with real operational source detail. | |||
| Change E3 | |||
| Artifact: `epics.md` | |||
| Section: Epic 6 | |||
| OLD: | |||
| - Story 6.4 covers report-to-source traceability generally. | |||
| NEW: | |||
| - Add Story 6.8: Source Reconciliation & Data Quality Queue | |||
| - Compare imported sheet values versus extension/legacy-joined report outputs | |||
| - Surface mismatches with owner assignment and resolution status | |||
| Rationale: operationalizes parity controls for the newly added source. | |||
| ### Architecture Changes | |||
| Change A1 | |||
| Artifact: `architecture.md` | |||
| Section: Integration/Data Flow | |||
| OLD: | |||
| - No explicit spreadsheet ingestion boundary. | |||
| NEW: | |||
| - Add import adapter boundary: | |||
| - file intake | |||
| - template-version detection | |||
| - mapping registry | |||
| - validation engine | |||
| - staging store | |||
| - publish service | |||
| Rationale: isolates import volatility and protects core domain model integrity. | |||
| Change A2 | |||
| Artifact: `architecture.md` | |||
| Section: Data Integrity & Audit | |||
| OLD: | |||
| - General discrepancy triage is described. | |||
| NEW: | |||
| - Add explicit provenance schema and reconciliation event model for spreadsheet-origin rows. | |||
| Rationale: makes traceability implementation-ready, not implicit. | |||
| ### UX Changes | |||
| Change U1 | |||
| Artifact: `ux-design-specification.md` | |||
| Section: Operational Workflows | |||
| OLD: | |||
| - No dedicated import/reconciliation user flow. | |||
| NEW: | |||
| - Add `ImportReviewWorkspace` flow: | |||
| - upload/import source | |||
| - mapping preview | |||
| - validation issues | |||
| - staged rows | |||
| - publish confirmation | |||
| Rationale: required for safe operational adoption without hidden transformations. | |||
| Change U2 | |||
| Artifact: `ux-design-specification.md` | |||
| Section: Role behavior | |||
| OLD: | |||
| - generic role-based workflow language. | |||
| NEW: | |||
| - Add explicit contact-data visibility rules and edit permissions by role. | |||
| Rationale: protects sensitive contact data and reduces accidental overexposure. | |||
| ## 5) Implementation Handoff | |||
| - Scope classification: **Moderate** | |||
| - Handoff recipients: | |||
| - Product Owner / Scrum Master: update backlog and story sequencing | |||
| - Architect: define ingestion + provenance + reconciliation design additions | |||
| - Dev team: implement new/updated stories after readiness check | |||
| - Success criteria: | |||
| - Planning artifacts explicitly include the new source | |||
| - Import/reconciliation behavior is defined with acceptance criteria | |||
| - Readiness check passes with updated PRD/epics/architecture/UX alignment | |||
| ## 6) Checklist Status | |||
| ### Section 1: Trigger and Context | |||
| - 1.1 Trigger story identified: [x] Done (trigger captured as late planning input change; implementation entry point added as Story 2.6) | |||
| - 1.2 Problem defined: [x] Done | |||
| - 1.3 Evidence gathered: [x] Done | |||
| ### Section 2: Epic Impact | |||
| - 2.1 Current epic impact assessed: [x] Done | |||
| - 2.2 Epic-level changes identified: [x] Done | |||
| - 2.3 Remaining epics reviewed: [x] Done | |||
| - 2.4 Future epic invalidation/new epic need: [x] Done | |||
| - 2.5 Resequencing/priority check: [x] Done | |||
| ### Section 3: Artifact Impact | |||
| - 3.1 PRD conflicts reviewed: [x] Done | |||
| - 3.2 Architecture conflicts reviewed: [x] Done | |||
| - 3.3 UX conflicts reviewed: [x] Done | |||
| - 3.4 Other artifacts reviewed: [x] Done | |||
| ### Section 4: Path Forward | |||
| - 4.1 Option 1 Direct Adjustment: [x] Viable | |||
| - 4.2 Option 2 Rollback: [x] Not viable | |||
| - 4.3 Option 3 MVP Review: [x] Viable | |||
| - 4.4 Recommendation selected: [x] Done (Hybrid) | |||
| ### Section 5: Proposal Components | |||
| - 5.1 Issue summary: [x] Done | |||
| - 5.2 Epic + artifact adjustments: [x] Done | |||
| - 5.3 Recommendation rationale: [x] Done | |||
| - 5.4 MVP impact + action plan: [x] Done | |||
| - 5.5 Handoff plan: [x] Done | |||
| ### Section 6: Final Review and Handoff | |||
| - 6.1 Checklist completeness: [x] Done | |||
| - 6.2 Proposal accuracy: [x] Done | |||
| - 6.3 User approval obtained: [x] Done (approved by user on 2026-05-05) | |||
| - 6.4 sprint-status update: [N/A] Skip (no sprint-status artifact found in implementation artifacts) | |||
| - 6.5 Next steps confirmed: [x] Done (route to implementation-readiness validation, then backlog execution) | |||
+ 98
- 0
_bmad-output/planning-artifacts/ux-color-themes.html
Ver fichero
| @@ -0,0 +1,98 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
| <head> | |||
| <meta charset="utf-8" /> | |||
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | |||
| <title>UX Color Themes - Brians Client Route Reports App</title> | |||
| <style> | |||
| body { | |||
| margin: 0; | |||
| font-family: "Public Sans", "Segoe UI", Arial, sans-serif; | |||
| background: #f3f6fb; | |||
| color: #111827; | |||
| } | |||
| .wrap { | |||
| max-width: 1200px; | |||
| margin: 0 auto; | |||
| padding: 20px; | |||
| } | |||
| h1 { margin: 0 0 8px; font-size: 22px; } | |||
| p { margin: 0 0 18px; color: #4b5563; } | |||
| .grid { | |||
| display: grid; | |||
| grid-template-columns: repeat(3, minmax(0, 1fr)); | |||
| gap: 14px; | |||
| } | |||
| .card { | |||
| background: #fff; | |||
| border: 1px solid #d1d5db; | |||
| border-radius: 10px; | |||
| overflow: hidden; | |||
| } | |||
| .head { | |||
| padding: 10px 12px; | |||
| border-bottom: 1px solid #e5e7eb; | |||
| font-weight: 600; | |||
| font-size: 14px; | |||
| } | |||
| .swatches { | |||
| display: grid; | |||
| grid-template-columns: repeat(2, minmax(0, 1fr)); | |||
| gap: 8px; | |||
| padding: 10px; | |||
| } | |||
| .sw { | |||
| border: 1px solid #e5e7eb; | |||
| border-radius: 8px; | |||
| overflow: hidden; | |||
| font-size: 11px; | |||
| } | |||
| .color { | |||
| height: 38px; | |||
| } | |||
| .label { | |||
| padding: 5px 6px; | |||
| background: #fff; | |||
| color: #374151; | |||
| } | |||
| @media (max-width: 980px) { | |||
| .grid { grid-template-columns: 1fr; } | |||
| } | |||
| </style> | |||
| </head> | |||
| <body> | |||
| <div class="wrap"> | |||
| <h1>Color Theme Visualizer</h1> | |||
| <p>Primary candidate is Theme A (Municipal Calm). Status semantics remain consistent across all options.</p> | |||
| <div class="grid"> | |||
| <section class="card"> | |||
| <div class="head">Theme A - Municipal Calm (Selected)</div> | |||
| <div class="swatches"> | |||
| <div class="sw"><div class="color" style="background:#1F4E79"></div><div class="label">Primary #1F4E79</div></div> | |||
| <div class="sw"><div class="color" style="background:#0F766E"></div><div class="label">Secondary #0F766E</div></div> | |||
| <div class="sw"><div class="color" style="background:#2E7D32"></div><div class="label">Success #2E7D32</div></div> | |||
| <div class="sw"><div class="color" style="background:#B45309"></div><div class="label">Warning #B45309</div></div> | |||
| </div> | |||
| </section> | |||
| <section class="card"> | |||
| <div class="head">Theme B - Slate Ops</div> | |||
| <div class="swatches"> | |||
| <div class="sw"><div class="color" style="background:#334155"></div><div class="label">Primary #334155</div></div> | |||
| <div class="sw"><div class="color" style="background:#0369A1"></div><div class="label">Secondary #0369A1</div></div> | |||
| <div class="sw"><div class="color" style="background:#15803D"></div><div class="label">Success #15803D</div></div> | |||
| <div class="sw"><div class="color" style="background:#D97706"></div><div class="label">Warning #D97706</div></div> | |||
| </div> | |||
| </section> | |||
| <section class="card"> | |||
| <div class="head">Theme C - Civic Teal</div> | |||
| <div class="swatches"> | |||
| <div class="sw"><div class="color" style="background:#0F766E"></div><div class="label">Primary #0F766E</div></div> | |||
| <div class="sw"><div class="color" style="background:#1D4ED8"></div><div class="label">Secondary #1D4ED8</div></div> | |||
| <div class="sw"><div class="color" style="background:#2E7D32"></div><div class="label">Success #2E7D32</div></div> | |||
| <div class="sw"><div class="color" style="background:#B45309"></div><div class="label">Warning #B45309</div></div> | |||
| </div> | |||
| </section> | |||
| </div> | |||
| </div> | |||
| </body> | |||
| </html> | |||
+ 451
- 0
_bmad-output/planning-artifacts/ux-design-directions.html
Ver fichero
| @@ -0,0 +1,451 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
| <head> | |||
| <meta charset="utf-8" /> | |||
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | |||
| <title>UX Design Directions - Brians Client Route Reports App</title> | |||
| <style> | |||
| :root { | |||
| --bg: #f7f9fc; | |||
| --surface: #ffffff; | |||
| --text: #111827; | |||
| --muted: #4b5563; | |||
| --border: #d0d7e2; | |||
| --primary: #1f4e79; | |||
| --accent: #2563eb; | |||
| --ok: #2e7d32; | |||
| --warn: #b45309; | |||
| --err: #b91c1c; | |||
| --radius: 10px; | |||
| } | |||
| * { box-sizing: border-box; } | |||
| body { | |||
| margin: 0; | |||
| background: var(--bg); | |||
| color: var(--text); | |||
| font: 14px/1.5 "Public Sans", "Segoe UI", Arial, sans-serif; | |||
| } | |||
| .topbar { | |||
| position: sticky; | |||
| top: 0; | |||
| z-index: 10; | |||
| background: #0f172a; | |||
| color: #e5e7eb; | |||
| border-bottom: 1px solid #1f2937; | |||
| padding: 12px 18px; | |||
| display: flex; | |||
| flex-wrap: wrap; | |||
| gap: 12px; | |||
| align-items: center; | |||
| justify-content: space-between; | |||
| } | |||
| .topbar h1 { | |||
| margin: 0; | |||
| font-size: 16px; | |||
| letter-spacing: 0.01em; | |||
| font-weight: 600; | |||
| } | |||
| .legend { | |||
| display: flex; | |||
| gap: 8px; | |||
| flex-wrap: wrap; | |||
| } | |||
| .pill { | |||
| border: 1px solid #334155; | |||
| border-radius: 999px; | |||
| padding: 2px 10px; | |||
| font-size: 12px; | |||
| background: #111827; | |||
| color: #cbd5e1; | |||
| } | |||
| .wrap { | |||
| max-width: 1480px; | |||
| margin: 0 auto; | |||
| padding: 20px; | |||
| display: grid; | |||
| gap: 16px; | |||
| grid-template-columns: repeat(12, minmax(0, 1fr)); | |||
| } | |||
| .summary { | |||
| grid-column: span 12; | |||
| background: var(--surface); | |||
| border: 1px solid var(--border); | |||
| border-radius: var(--radius); | |||
| padding: 14px 16px; | |||
| } | |||
| .summary h2 { | |||
| margin: 0 0 6px; | |||
| font-size: 16px; | |||
| } | |||
| .grid { | |||
| grid-column: span 12; | |||
| display: grid; | |||
| grid-template-columns: repeat(2, minmax(0, 1fr)); | |||
| gap: 16px; | |||
| } | |||
| .card { | |||
| background: var(--surface); | |||
| border: 1px solid var(--border); | |||
| border-radius: var(--radius); | |||
| overflow: hidden; | |||
| box-shadow: 0 1px 0 rgba(15, 23, 42, 0.06); | |||
| } | |||
| .card:hover { | |||
| border-color: #9fb6d6; | |||
| box-shadow: 0 8px 28px rgba(31, 78, 121, 0.15); | |||
| transform: translateY(-1px); | |||
| transition: all 0.2s ease; | |||
| } | |||
| .card-head { | |||
| padding: 12px 14px; | |||
| border-bottom: 1px solid var(--border); | |||
| display: flex; | |||
| align-items: center; | |||
| justify-content: space-between; | |||
| gap: 8px; | |||
| } | |||
| .card-head h3 { | |||
| margin: 0; | |||
| font-size: 14px; | |||
| font-weight: 600; | |||
| } | |||
| .tag { | |||
| font-size: 11px; | |||
| border-radius: 999px; | |||
| border: 1px solid #c7d2fe; | |||
| background: #eef2ff; | |||
| color: #3730a3; | |||
| padding: 2px 8px; | |||
| white-space: nowrap; | |||
| } | |||
| .preview { | |||
| background: #f8fafc; | |||
| min-height: 320px; | |||
| padding: 10px; | |||
| } | |||
| .mock { | |||
| height: 100%; | |||
| border: 1px solid #cbd5e1; | |||
| border-radius: 8px; | |||
| background: white; | |||
| overflow: hidden; | |||
| display: grid; | |||
| } | |||
| .mock-top { | |||
| border-bottom: 1px solid #e2e8f0; | |||
| background: #f8fafc; | |||
| height: 34px; | |||
| display: flex; | |||
| align-items: center; | |||
| padding: 0 10px; | |||
| gap: 8px; | |||
| color: #334155; | |||
| font-size: 12px; | |||
| } | |||
| .dot { | |||
| width: 8px; | |||
| height: 8px; | |||
| border-radius: 999px; | |||
| background: #94a3b8; | |||
| } | |||
| .body-a { grid-template-columns: 220px 1fr 280px; } | |||
| .body-b { grid-template-columns: 1fr 340px; } | |||
| .body-c { grid-template-columns: 220px 1fr; grid-template-rows: 1fr 130px; } | |||
| .body-d { grid-template-columns: 1fr; grid-template-rows: 72px 1fr; } | |||
| .body-e { grid-template-columns: 260px 1fr; } | |||
| .body-f { grid-template-columns: 1fr; } | |||
| .pane { | |||
| border-right: 1px solid #e2e8f0; | |||
| padding: 8px; | |||
| background: #fff; | |||
| } | |||
| .pane:last-child { border-right: 0; } | |||
| .pane.soft { background: #f8fafc; } | |||
| .pane.dark { | |||
| background: #0f172a; | |||
| color: #cbd5e1; | |||
| border-right: 1px solid #1e293b; | |||
| } | |||
| .lane { | |||
| margin-bottom: 8px; | |||
| border: 1px solid #e2e8f0; | |||
| border-radius: 6px; | |||
| padding: 6px 8px; | |||
| font-size: 12px; | |||
| background: #ffffff; | |||
| } | |||
| .lane.ok { border-left: 4px solid var(--ok); } | |||
| .lane.warn { border-left: 4px solid var(--warn); } | |||
| .lane.err { border-left: 4px solid var(--err); } | |||
| .data-table { | |||
| width: 100%; | |||
| border-collapse: collapse; | |||
| font-size: 12px; | |||
| } | |||
| .data-table th, | |||
| .data-table td { | |||
| border: 1px solid #e2e8f0; | |||
| padding: 4px 6px; | |||
| text-align: left; | |||
| } | |||
| .data-table th { | |||
| background: #eff6ff; | |||
| color: #1e3a8a; | |||
| font-weight: 600; | |||
| } | |||
| .chip { | |||
| font-size: 11px; | |||
| padding: 1px 6px; | |||
| border-radius: 999px; | |||
| border: 1px solid #dbeafe; | |||
| background: #eff6ff; | |||
| color: #1d4ed8; | |||
| } | |||
| .chip.ok { background: #ecfdf5; border-color: #bbf7d0; color: #166534; } | |||
| .chip.warn { background: #fffbeb; border-color: #fde68a; color: #92400e; } | |||
| .chip.err { background: #fef2f2; border-color: #fecaca; color: #991b1b; } | |||
| .notes { | |||
| padding: 10px 14px 14px; | |||
| border-top: 1px solid var(--border); | |||
| color: #334155; | |||
| font-size: 12px; | |||
| background: #fcfdff; | |||
| } | |||
| .notes strong { color: #0f172a; } | |||
| .footer { | |||
| grid-column: span 12; | |||
| background: var(--surface); | |||
| border: 1px solid var(--border); | |||
| border-radius: var(--radius); | |||
| padding: 12px 14px; | |||
| color: #334155; | |||
| font-size: 13px; | |||
| } | |||
| @media (max-width: 1180px) { | |||
| .grid { grid-template-columns: 1fr; } | |||
| } | |||
| </style> | |||
| </head> | |||
| <body> | |||
| <header class="topbar"> | |||
| <h1>Design Direction Showcase • Brians Client Route Reports App</h1> | |||
| <div class="legend"> | |||
| <span class="pill">PC-first</span> | |||
| <span class="pill">Ant Design Foundation</span> | |||
| <span class="pill">Dense Operations UX</span> | |||
| <span class="pill">Status + Provenance Visible</span> | |||
| </div> | |||
| </header> | |||
| <main class="wrap"> | |||
| <section class="summary"> | |||
| <h2>How to Evaluate</h2> | |||
| Compare directions by layout intuitiveness, risk visibility, editing clarity, and workflow speed under deadline pressure. | |||
| </section> | |||
| <section class="grid"> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 1: Operations Command Desk</h3> | |||
| <span class="tag">Tri-pane control</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock" style="grid-template-rows:34px 1fr;"> | |||
| <div class="mock-top"><span class="dot"></span><span class="dot"></span><span class="dot"></span> Command Desk / Election Cycle Workspace</div> | |||
| <div class="mock body-a"> | |||
| <aside class="pane dark"> | |||
| <div class="lane">Municipalities</div> | |||
| <div class="lane">Election Cycles</div> | |||
| <div class="lane">Saved Filters</div> | |||
| </aside> | |||
| <section class="pane"> | |||
| <table class="data-table"> | |||
| <thead><tr><th>Town</th><th>Cycle</th><th>Milestone</th><th>Status</th></tr></thead> | |||
| <tbody> | |||
| <tr><td>Northfield</td><td>2026-Q3</td><td>Addressing</td><td><span class="chip warn">At Risk</span></td></tr> | |||
| <tr><td>Oak Hills</td><td>2026-Q3</td><td>Sort Complete</td><td><span class="chip ok">On Track</span></td></tr> | |||
| <tr><td>Lakeview</td><td>2026-Q3</td><td>Dispatch</td><td><span class="chip err">Blocked</span></td></tr> | |||
| </tbody> | |||
| </table> | |||
| </section> | |||
| <aside class="pane soft"> | |||
| <div class="lane err">Cutoff Risk Queue</div> | |||
| <div class="lane warn">Dependency Alerts</div> | |||
| <div class="lane">Provenance Details</div> | |||
| </aside> | |||
| </div> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Maximum situational awareness and real-time risk triage.</div> | |||
| </article> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 2: Queue + Inspector</h3> | |||
| <span class="tag">Speed edits</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock" style="grid-template-rows:34px 1fr;"> | |||
| <div class="mock-top"><span class="dot"></span><span class="dot"></span><span class="dot"></span> Priority Queue / Detail Inspector</div> | |||
| <div class="mock body-b"> | |||
| <section class="pane"> | |||
| <div class="lane warn">At-Risk: Millbrook sorting due in 18h</div> | |||
| <div class="lane err">Blocked: Easton transport window conflict</div> | |||
| <div class="lane ok">On Track: Pinecrest office copies</div> | |||
| <div class="lane">Ready: Blue envelope print</div> | |||
| </section> | |||
| <aside class="pane soft"> | |||
| <div class="lane">Inline Edit Fields</div> | |||
| <div class="lane">Safe Commit Checks</div> | |||
| <div class="lane">Reason Code + Save</div> | |||
| <div class="lane">Audit Trail</div> | |||
| </aside> | |||
| </div> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Fast operator throughput with minimal navigation friction.</div> | |||
| </article> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 3: Spreadsheet Plus</h3> | |||
| <span class="tag">Excel-inspired</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock" style="grid-template-rows:34px 1fr;"> | |||
| <div class="mock-top"><span class="dot"></span><span class="dot"></span><span class="dot"></span> Grid Operations / Trusted Commit</div> | |||
| <div class="mock body-c"> | |||
| <aside class="pane soft"> | |||
| <div class="lane">Column Presets</div> | |||
| <div class="lane">Saved Views</div> | |||
| <div class="lane">Bulk Actions</div> | |||
| </aside> | |||
| <section class="pane"> | |||
| <table class="data-table"> | |||
| <thead><tr><th>Municipality</th><th>Cycle</th><th>Envelope</th><th>Dispatch</th><th>Owner</th></tr></thead> | |||
| <tbody> | |||
| <tr><td>Riverside</td><td>Primary</td><td>Purple</td><td>04/07</td><td>D. Hall</td></tr> | |||
| <tr><td>Brighton</td><td>General</td><td>Blue</td><td>04/09</td><td>M. Cole</td></tr> | |||
| <tr><td>Auburn</td><td>General</td><td>Purple</td><td>04/08</td><td>J. Lee</td></tr> | |||
| </tbody> | |||
| </table> | |||
| </section> | |||
| <section class="pane" style="grid-column:2; grid-row:2;"> | |||
| <div class="lane">Validation Console</div> | |||
| <div class="lane ok">Ready to commit 6 updates</div> | |||
| </section> | |||
| </div> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Teams migrating from Access/Excel habits with low retraining cost.</div> | |||
| </article> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 4: Timeline Operations</h3> | |||
| <span class="tag">Deadline-first</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock body-d"> | |||
| <div class="pane soft" style="border-bottom:1px solid #e2e8f0;"> | |||
| <div class="lane">Election Timeline Ribbon • D-10 to D+2</div> | |||
| </div> | |||
| <section class="pane"> | |||
| <div class="lane warn">D-3: Address finalization (2 blockers)</div> | |||
| <div class="lane err">D-2: Transportation route unresolved</div> | |||
| <div class="lane ok">D-1: Office copies complete</div> | |||
| <div class="lane">D-Day: Dispatch verification checklist</div> | |||
| </section> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Production-led teams where timing risk is the primary management lens.</div> | |||
| </article> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 5: Workbench + Modal Deep Work</h3> | |||
| <span class="tag">Focus workflows</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock" style="grid-template-rows:34px 1fr;"> | |||
| <div class="mock-top"><span class="dot"></span><span class="dot"></span><span class="dot"></span> Operations Workbench / Task Focus</div> | |||
| <div class="mock body-e"> | |||
| <aside class="pane soft"> | |||
| <div class="lane">Task Stack</div> | |||
| <div class="lane warn">Urgent (4)</div> | |||
| <div class="lane">Due Today (11)</div> | |||
| </aside> | |||
| <section class="pane"> | |||
| <div class="lane">Primary Work Area</div> | |||
| <div class="lane">Contextual Drawer Opens on Select</div> | |||
| <div class="lane">Commit + Reason Code Modal</div> | |||
| <div class="lane ok">Success Feedback With Next Action</div> | |||
| </section> | |||
| </div> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Reduced cognitive load when users process one high-impact task at a time.</div> | |||
| </article> | |||
| <article class="card"> | |||
| <div class="card-head"> | |||
| <h3>Direction 6: Executive Snapshot + Drilldown</h3> | |||
| <span class="tag">Overview to action</span> | |||
| </div> | |||
| <div class="preview"> | |||
| <div class="mock body-f"> | |||
| <section class="pane"> | |||
| <div style="display:grid; grid-template-columns:repeat(4,1fr); gap:8px; margin-bottom:8px;"> | |||
| <div class="lane ok">On Track: 124</div> | |||
| <div class="lane warn">At Risk: 19</div> | |||
| <div class="lane err">Blocked: 7</div> | |||
| <div class="lane">Needs Review: 11</div> | |||
| </div> | |||
| <table class="data-table"> | |||
| <thead><tr><th>Region</th><th>Upcoming Cutoff</th><th>Primary Risk</th><th>Action</th></tr></thead> | |||
| <tbody> | |||
| <tr><td>North</td><td>04/07</td><td>Addressing Lag</td><td>Open Queue</td></tr> | |||
| <tr><td>South</td><td>04/08</td><td>Route Capacity</td><td>Open Queue</td></tr> | |||
| <tr><td>West</td><td>04/08</td><td>No blockers</td><td>Review</td></tr> | |||
| </tbody> | |||
| </table> | |||
| </section> | |||
| </div> | |||
| </div> | |||
| <div class="notes"><strong>Best for:</strong> Leadership and admins who need rapid oversight before acting at detail level.</div> | |||
| </article> | |||
| </section> | |||
| <section class="footer"> | |||
| Recommended base candidate: <strong>Direction 1 (Operations Command Desk)</strong>, with selective adoption of Direction 3 grid affordances and Direction 2 quick inspector behavior. | |||
| </section> | |||
| </main> | |||
| </body> | |||
| </html> | |||
+ 871
- 0
_bmad-output/planning-artifacts/ux-design-specification.md
Ver fichero
| @@ -0,0 +1,871 @@ | |||
| --- | |||
| stepsCompleted: | |||
| - 1 | |||
| - 2 | |||
| - 3 | |||
| - 4 | |||
| - 5 | |||
| - 6 | |||
| - 7 | |||
| - 8 | |||
| - 9 | |||
| - 10 | |||
| - 11 | |||
| - 12 | |||
| - 13 | |||
| - 14 | |||
| lastStep: 14 | |||
| inputDocuments: | |||
| - _bmad-output/planning-artifacts/prd.md | |||
| - _bmad-output/planning-artifacts/validation-report-2026-04-03.md | |||
| - _bmad-output/planning-artifacts/client-database-plan-extract.txt | |||
| --- | |||
| # UX Design Specification Brians Client Route Reports App | |||
| **Author:** Daniel | |||
| **Date:** 2026-04-03 | |||
| --- | |||
| <!-- UX design content will be appended sequentially through collaborative workflow steps --> | |||
| ## Executive Summary | |||
| ### Project Vision | |||
| Create a browser-based municipal election-services operations platform that modernizes an existing Access production workflow without changing legacy tables. The UX must reduce operational friction across client services, production, transportation, and support while preserving trusted workflow continuity. | |||
| ### Target Users | |||
| - Client Services Coordinators: configure municipality accounts and election-cycle services. | |||
| - Production Leads: monitor milestones, dependencies, and exception recovery. | |||
| - Transportation Coordinators: plan daily and upcoming pickup/delivery operations. | |||
| - Operations Administrators: manage governance, defaults, permissions, and compatibility controls. | |||
| - Support Analysts: investigate data/reporting issues and maintain audit-aligned corrections. | |||
| ### Key Design Challenges | |||
| - Support complex, date-critical election workflows without overwhelming users. | |||
| - Keep permanent municipality data and election-cycle operational data clearly separated but visibly connected. | |||
| - Provide dense operational tables/reports that remain readable, fast, and keyboard-accessible. | |||
| - Preserve legacy trust by making extension-layer behavior transparent and auditable. | |||
| ### Design Opportunities | |||
| - Build role-specific task views so each team sees only the highest-value next actions. | |||
| - Use timeline-first UX patterns to surface schedule risk early and reduce missed milestones. | |||
| - Provide clear traceability UI (source links, status history, reason codes) to improve confidence in reporting. | |||
| - Turn high-friction reporting into one-click operational exports with predictable filters and presets. | |||
| ## Core User Experience | |||
| ### Defining Experience | |||
| The core experience is election-cycle operations planning and execution in one continuous workspace: set up municipality cycle details, track milestones, resolve blockers, and produce operational outputs without context switching. The primary interaction to optimize is "commit a status update with confidence" so teams can act quickly without creating downstream risk. | |||
| ### Platform Strategy | |||
| - Primary and only platform (MVP+current scope): authenticated web app for PC/desktop operations environments. | |||
| - Input model: keyboard + mouse first, with dense grid/timeline interaction and rapid filtering. | |||
| - Tablet/mobile interfaces are out of scope. | |||
| - Offline: not required for MVP; UI must show explicit reconnect/sync state and safe retry behavior. | |||
| - Architecture-facing UX rule: compliance and dependency checks appear pre-commit, in flow. | |||
| ### Effortless Interactions | |||
| - Single-workspace election setup with prior-cycle defaults and progressive required-field checks. | |||
| - "Next Best Action" prompts per record to reduce decision latency. | |||
| - Inline blocker diagnostics: why blocked, impact, and one-click jump to corrective field/action. | |||
| - Fast row-level status updates, plus guarded bulk actions for repetitive operational work. | |||
| - Saved report presets (transport/sort) with deterministic filters and export parity. | |||
| - In-flow trust cues: actor, timestamp, reason code, policy-state chips (clearance/residency relevance). | |||
| ### Critical Success Moments | |||
| - Setup success: coordinator completes a valid election-cycle plan without external checklist lookup. | |||
| - Prevention success: production lead resolves a dependency before cutoff after risk is surfaced early. | |||
| - Dispatch success: transport coordinator generates an accurate date-sorted run in one pass. | |||
| - Trust success: support traces disputed output to source history in under 2 minutes. | |||
| - Governance success: admin executes privileged updates with visible policy checks and no workflow detour. | |||
| - Recovery success: blocked/late milestone resolved from the same screen where risk appears. | |||
| ### Experience Principles | |||
| - Design for operational clarity first; aesthetics support comprehension, not the reverse. | |||
| - Keep timeline truth visible, actionable, and prioritized by urgency/risk. | |||
| - Reduce interaction cost for repetitive work (fewer clicks, fewer mode switches, fewer surprises). | |||
| - Make traceability and policy-state visible at decision points, not after the fact. | |||
| - Preserve legacy mental models while delivering materially faster, safer execution. | |||
| - Every critical action should answer: what changed, why, by whom, and what is next. | |||
| ## Desired Emotional Response | |||
| ### Primary Emotional Goals | |||
| - Primary: users feel in control under pressure. | |||
| - Secondary: users feel confident that data, status, and outputs are trustworthy. | |||
| - Supporting: users feel efficient and focused, not burdened by process overhead. | |||
| - Protective: users feel psychologically safe to correct mistakes without fear of hidden consequences. | |||
| ### Emotional Journey Mapping | |||
| - First-use: "I understand what matters right now" (clarity over overwhelm). | |||
| - In-flow execution: "I can act quickly and safely" (speed with confidence). | |||
| - Completion: "I did this correctly" (verification and closure). | |||
| - Error/block state: "I know exactly what to fix next" (guided recovery, low anxiety). | |||
| - Policy/dependency failure: "I understand why this is blocked and what unlocks it" (explainable constraints). | |||
| - Cutoff-day pressure moment: "I can prioritize the highest-risk item immediately" (calm urgency, not panic). | |||
| - Return use: "This is predictable and dependable" (habit-forming trust). | |||
| ### Micro-Emotions | |||
| - Prioritize: confidence, relief, momentum, trust, accomplishment. | |||
| - Minimize: ambiguity, hesitation, anxiety, blame, rework frustration. | |||
| - Add subtle positive cues: readiness confirmations, completion states, transparent status provenance, and safe-undo confidence for reversible actions. | |||
| - Tone by severity: | |||
| - Info = calm and concise | |||
| - Warning = action-oriented and specific | |||
| - Critical = urgent but non-alarmist, with immediate next step | |||
| ### Design Implications | |||
| - Confidence -> show source, actor, timestamp, and reason code at decision points. | |||
| - Control -> keep next-best-action guidance visible in dense operational views. | |||
| - Trust -> provide pre-commit policy/dependency checks with clear pass/fail feedback. | |||
| - Relief -> make blocked-state recovery one-click from the same working context. | |||
| - Momentum -> optimize repetitive tasks (fast row updates, presets, keyboard-first interaction). | |||
| - Psychological safety -> provide reversible actions where possible and explicit impact preview for irreversible actions. | |||
| - Cognitive load management -> progressive detail (summary first, drill-down on demand) to support both novice and expert operators. | |||
| - High-pressure support -> fixed "priority queue" panel highlighting what must be resolved before cutoff. | |||
| ### Emotional Design Principles | |||
| - Reduce uncertainty before reducing clicks. | |||
| - Every critical action should leave users more confident than before they clicked. | |||
| - Error states must guide, not punish. | |||
| - Trust is built through visible provenance and predictable outcomes. | |||
| - Calm, high-signal interfaces beat visually busy dashboards for deadline work. | |||
| - Explain constraints in plain language at the moment they matter. | |||
| - Support fast experts without sacrificing clarity for occasional users. | |||
| - Urgency messaging must accelerate action without escalating stress. | |||
| ## UX Pattern Analysis & Inspiration | |||
| ### Inspiring Products Analysis | |||
| **Excel** | |||
| - Strength: fast sorting, filtering, and organization of dense tabular data. | |||
| - UX value for this product: operations users can prioritize quickly across many municipalities/jobs without losing context. | |||
| - Pattern to borrow: grid-first workflows with explicit column controls, deterministic sorting, and repeatable views. | |||
| **Word** | |||
| - Strength: direct display-and-edit flow where users can immediately update content in context. | |||
| - UX value for this product: users should update election/job fields inline without disruptive screen changes. | |||
| - Pattern to borrow: clear edit states, obvious commit behavior, and immediate confirmation of applied changes. | |||
| **Why these are inspiration, not templates** | |||
| - Election operations are deadline- and policy-constrained, so interactions must preserve traceability, policy checks, and provenance in ways generic office tools do not require. | |||
| ### Transferable UX Patterns | |||
| - Grid-first operational workspace for high-volume records. | |||
| - Inline editing with explicit editable/read-only affordances. | |||
| - Fast sort/filter/preset workflows for recurring report and dispatch use. | |||
| - Row selection + guarded bulk actions for repetitive updates. | |||
| - Persistent hierarchy: always-visible keys (municipality, cycle, milestone status, risk level). | |||
| - Deterministic state cues: visible "last refreshed" and data-freshness indicators for decision confidence. | |||
| ### Anti-Patterns to Avoid | |||
| - Hidden edit modes that obscure whether a change is pending or committed. | |||
| - Decorative dashboards that reduce scan speed of dense operational data. | |||
| - Multi-step navigation for simple status/date updates that should be inline. | |||
| - Ambiguous save behavior (silent auto-save for high-risk changes). | |||
| - Generic "office app cloning" that ignores policy checks, reason codes, and audit provenance. | |||
| - Non-deterministic sorting/filtering that can produce different operational views for different users. | |||
| ### Design Inspiration Strategy | |||
| **Adopt** | |||
| - Excel-style organization controls for dense data operations. | |||
| - Word-style direct editing with explicit commit confirmations. | |||
| **Adapt** | |||
| - Require pre-commit dependency/policy validation before sensitive status changes. | |||
| - Add role-aware defaults and progressive disclosure (summary first, drill-down when needed). | |||
| - Preserve provenance visibility (actor, timestamp, reason code) near every critical action. | |||
| - Keep interaction consistency: same edit, save, and status-confirm patterns across all operational views. | |||
| **Avoid** | |||
| - Minimalist patterns that hide operational truth. | |||
| - Any flow that separates action from consequence visibility. | |||
| - Any interaction that weakens trust under cutoff pressure. | |||
| ### Decision Rules for Pattern Use | |||
| - If a pattern improves speed but reduces certainty, do not adopt as-is. | |||
| - If a pattern increases clicks but prevents high-impact errors, prefer safety by default. | |||
| - If users cannot explain "what changed and why" from the UI, redesign the interaction. | |||
| - If two users can reach different filtered/sorted conclusions from the same data context, tighten the interaction model. | |||
| ## Design System Foundation | |||
| ### 1.1 Design System Choice | |||
| Ant Design (React + Ant Design v5 token system) for a PC-first municipal operations web application. | |||
| ### Rationale for Selection | |||
| Ant Design is the best fit using first-principles criteria for this product: | |||
| - Operational clarity under pressure: strong support for dense tables, forms, and status-driven workflows. | |||
| - Execution speed with low risk: mature, documented components reduce build time and UX inconsistency. | |||
| - Trust and governance visibility: supports explicit validation, status tags, and auditable interaction patterns. | |||
| - Adoption fit: familiar enterprise interaction model for office-based users. | |||
| Why this over alternatives: | |||
| - Not custom-first: custom systems increase delivery risk and maintenance burden without clear value for this operations-heavy tool. | |||
| - Not utility-only foundation: utility-only approaches can drift in consistency across complex admin workflows. | |||
| ### Implementation Approach | |||
| - Use Ant Design as the base for core UI primitives: `Layout`, `Table`, `Form`, `DatePicker`, `Steps`, `Timeline`, `Tag`, `Modal`, `Drawer`, `Alert`, `Result`. | |||
| - Build domain-specific extension components on top of Ant Design for election operations: | |||
| - Municipality/Cycle Workspace Grid | |||
| - Cutoff Risk Queue Panel | |||
| - Blocker Resolution Drawer | |||
| - Dispatch Run Builder | |||
| - Audit Provenance Side Panel | |||
| - Apply architecture guardrails in UX and data interactions: | |||
| - Legacy Access tables remain immutable. | |||
| - All new capabilities write to extension tables only. | |||
| - Data composition uses join queries/views via ID relationships. | |||
| - Permanent municipality entities remain clearly separated from election-cycle entities in navigation, forms, and reports. | |||
| Implementation exit criteria: | |||
| - Users can complete core cycle setup and status workflows without leaving primary workspace context. | |||
| - All high-risk commits show pre-commit validation and clear recovery guidance. | |||
| - Role-critical views preserve dense data readability and keyboard efficiency on desktop. | |||
| ### Customization Strategy | |||
| - Use Ant Design token theming to create an operations-focused visual profile: | |||
| - High-contrast semantic status colors (on-track, at-risk, blocked, overdue) | |||
| - Compact density profile for high-volume grid work | |||
| - Consistent spacing and typography for long-form operational scanning | |||
| - Establish reusable pattern standards: | |||
| - Inline edit + explicit commit behavior | |||
| - Deterministic filtering/sorting state indicators | |||
| - Provenance visibility (actor, timestamp, reason code) at decision points | |||
| - Restrict customization to tokens and wrapper components first; avoid deep component forks unless required by compliance or workflow-critical needs. | |||
| ## 2. Core User Experience | |||
| ### 2.1 Defining Experience | |||
| The defining experience is operationally safe, high-speed status progression for election-cycle work: users update dates/statuses inline, pass visible dependency/policy checks, and commit changes with immediate confidence in downstream accuracy. | |||
| This experience is built around one promise: | |||
| "Any coordinator can move critical work forward quickly without breaking compliance, traceability, or production readiness." | |||
| ### 2.2 User Mental Model | |||
| Users think in task queues and deadlines, not abstract records. They expect to: | |||
| - Find the right municipality/cycle quickly | |||
| - Sort/filter work by urgency and due date | |||
| - Edit directly where they are looking | |||
| - See instantly whether the change is valid | |||
| - Understand why something is blocked and how to unblock it | |||
| Current mental model carryover: | |||
| - Excel-like control over tabular organization (sort, filter, scan, batch) | |||
| - Word-like in-context editing with clear commit confirmation | |||
| - "One source of truth" expectation during high-pressure cutoff windows | |||
| Likely confusion points to design against: | |||
| - Mixing permanent municipality data with election-cycle data | |||
| - Unclear save/commit state | |||
| - Hidden dependency failures discovered too late | |||
| ### 2.3 Success Criteria | |||
| Users should consistently report: "This just works when it matters." | |||
| Core success indicators: | |||
| - Status/date updates are completed in-line without navigation detours | |||
| - Pre-commit checks prevent invalid transitions before save | |||
| - Blocked-state reasons are explicit and actionable from the same screen | |||
| - Users can verify who changed what and why in seconds | |||
| - High-priority items are clearly surfaced before cutoff risk escalates | |||
| ### 2.4 Novel UX Patterns | |||
| Pattern strategy: familiar-first, innovation-in-guardrails. | |||
| Established patterns to leverage: | |||
| - Dense data grids with deterministic sort/filter behavior | |||
| - Inline field editing with explicit commit actions | |||
| - Role-oriented task queues and saved operational views | |||
| Novel combination for this product: | |||
| - "Safe Commit Rail": dependency/policy validation integrated directly into inline updates | |||
| - "Cutoff Risk Queue": persistent urgency panel tied to timeline and blocker state | |||
| - "Provenance-at-point-of-action": actor/timestamp/reason code visible where decisions are made | |||
| This avoids forcing users to learn a new interaction language while still delivering a materially better operations workflow. | |||
| ### 2.5 Experience Mechanics | |||
| 1. Initiation | |||
| - User lands in role-specific operations workspace (Client Services, Production, Transportation, Support). | |||
| - Default view loads prioritized election-cycle records with saved filters and risk ordering. | |||
| - User selects row/field or bulk selection set for intended update. | |||
| 2. Interaction | |||
| - User edits status/date/service fields inline in the grid or side drawer. | |||
| - System evaluates transition rules in real time (dependencies, policy checks, required reason codes). | |||
| - If valid, commit action is enabled; if invalid, blocker details and direct fix actions are shown. | |||
| 3. Feedback | |||
| - On valid commit, user sees immediate confirmation with changed fields highlighted. | |||
| - Provenance metadata appears with actor, timestamp, and reason code. | |||
| - Related risk indicators and queue ordering refresh deterministically so users trust what changed. | |||
| 4. Completion | |||
| - Record returns to normal state with updated lifecycle status. | |||
| - If follow-up action is needed, "Next Best Action" is presented immediately. | |||
| - User can continue in current context (no forced navigation), preserving momentum during deadline work. | |||
| ## Visual Design Foundation | |||
| ### Color System | |||
| Visual direction: calm operational clarity with high-signal status semantics. | |||
| Core palette: | |||
| - Primary: `#1F4E79` (municipal navy; trust and structure) | |||
| - Secondary: `#0F766E` (teal support/action) | |||
| - Accent: `#2563EB` (interactive focus/action emphasis) | |||
| Semantic status palette: | |||
| - Success / On Track: `#2E7D32` | |||
| - Warning / At Risk: `#B45309` | |||
| - Error / Blocked: `#B91C1C` | |||
| - Info / Neutral Progress: `#2563EB` | |||
| - Overdue / Critical Flag: `#7F1D1D` | |||
| Neutral foundation: | |||
| - Background: `#F7F9FC` | |||
| - Surface: `#FFFFFF` | |||
| - Border: `#D0D7E2` | |||
| - Primary Text: `#111827` | |||
| - Secondary Text: `#4B5563` | |||
| Ant Design token strategy: | |||
| - Configure global tokens first (`colorPrimary`, `colorSuccess`, `colorWarning`, `colorError`, `colorInfo`, `colorBgBase`, `colorText`, `borderRadius`, density-related sizing). | |||
| - Keep status meaning consistent across tables, tags, timelines, and alerts. | |||
| ### Typography System | |||
| Tone: professional, clear, non-decorative, optimized for dense operational reading. | |||
| Type stack: | |||
| - Primary UI text: `Public Sans`, `Segoe UI`, `Arial`, sans-serif | |||
| - Data-heavy/labels fallback: `IBM Plex Sans`, `Segoe UI`, sans-serif | |||
| - Monospace for IDs/reference codes: `IBM Plex Mono`, `Consolas`, monospace | |||
| Type hierarchy (desktop-first): | |||
| - H1: 28px / 36px / 600 | |||
| - H2: 22px / 30px / 600 | |||
| - H3: 18px / 26px / 600 | |||
| - Body default: 14px / 22px / 400 | |||
| - Dense table/body compact: 13px / 20px / 400 | |||
| - Caption/meta: 12px / 18px / 400 | |||
| Typography principles: | |||
| - Prioritize legibility over brand flourish. | |||
| - Keep numeric/date fields highly scannable. | |||
| - Use consistent casing and label patterns for form-heavy workflows. | |||
| ### Spacing & Layout Foundation | |||
| Layout direction: compact, structured, desktop-optimized operational workspace. | |||
| Spacing system: | |||
| - Base unit: 8px | |||
| - Micro spacing for dense table controls: 4px | |||
| - Section spacing rhythm: 16px / 24px / 32px | |||
| Grid and containers: | |||
| - Desktop-first 12-column grid | |||
| - Content max-width bands for readability in wide monitors | |||
| - Persistent side regions for risk queue/filter panels when useful | |||
| Component density rules: | |||
| - Default to compact controls for grid and forms | |||
| - Keep touch-target inflation out of scope (PC-only product) | |||
| - Reserve larger spacing only for high-risk confirmations/modals | |||
| Visual rhythm: | |||
| - Clear row grouping and section boundaries | |||
| - Strong alignment around key operational identifiers (municipality, cycle, status, due date) | |||
| ### Accessibility Considerations | |||
| - WCAG 2.2 AA minimum contrast targets: | |||
| - 4.5:1 for normal text | |||
| - 3:1 for large text and UI components | |||
| - Keyboard-first operation: | |||
| - Visible 2px focus indicators on interactive elements | |||
| - Logical tab order in grids, forms, drawers, and modals | |||
| - Do not rely on color alone: | |||
| - Pair status colors with labels/icons/patterns | |||
| - Motion and feedback: | |||
| - Subtle motion only for orientation, not decoration | |||
| - Respect reduced-motion preferences | |||
| - Dense-data readability: | |||
| - Preserve minimum font sizes and row heights that remain readable during long operational sessions | |||
| ## Design Direction Decision | |||
| ### Design Directions Explored | |||
| Six design directions were explored in the HTML showcase: | |||
| - Direction 1: Operations Command Desk (tri-pane situational control) | |||
| - Direction 2: Queue + Inspector (fast update throughput) | |||
| - Direction 3: Spreadsheet Plus (Excel-like grid-first operations) | |||
| - Direction 4: Timeline Operations (deadline-first sequencing) | |||
| - Direction 5: Workbench + Modal Deep Work (single-task focus) | |||
| - Direction 6: Executive Snapshot + Drilldown (overview-to-action model) | |||
| ### Chosen Direction | |||
| Hybrid direction: | |||
| - Base layout and information hierarchy from Direction 1 | |||
| - Grid interaction and column/preset behavior from Direction 3 | |||
| - Inspector-side quick edit/validation behavior from Direction 2 | |||
| ### Design Rationale | |||
| - Preserves trusted legacy mental model while improving speed. | |||
| - Keeps risk visibility and blocker recovery in constant view. | |||
| - Supports dense, keyboard-first PC workflows without navigation overhead. | |||
| - Provides clear commit confidence through in-flow validation and provenance visibility. | |||
| ### Implementation Approach | |||
| - Primary screen architecture: tri-pane workspace | |||
| - Left: context/navigation (municipality, cycle, saved views) | |||
| - Center: dense editable operations grid | |||
| - Right: risk queue + quick inspector/provenance | |||
| - Interaction model: | |||
| - Inline edits in grid | |||
| - Safe Commit checks before sensitive transitions | |||
| - Immediate row-level confirmation with actor/timestamp/reason code | |||
| - Build order: | |||
| - 1) Workspace shell and layout | |||
| - 2) Grid + filters + presets | |||
| - 3) Inspector and validation rail | |||
| - 4) Risk queue and provenance panel | |||
| ## User Journey Flows | |||
| ### Client Services Coordinator - Election Setup and Publish | |||
| Goal: create a complete election-cycle plan without touching immutable legacy tables and publish a production-ready job. | |||
| ```mermaid | |||
| flowchart TD | |||
| A[Open Municipality Workspace] --> B[Select Municipality] | |||
| B --> C[Load Permanent Data via Legacy Join] | |||
| C --> D[Create Election-Cycle Extension Record] | |||
| D --> E[Apply Prior-Cycle Defaults] | |||
| E --> F[Configure Services: Addressing, Envelopes, Sorting, Office Copies, Transport] | |||
| F --> G[Enter Key Dates and Owners] | |||
| G --> H{Required Fields Complete?} | |||
| H -- No --> I[Show Missing Fields + Jump Links] | |||
| I --> F | |||
| H -- Yes --> J[Run Pre-Commit Validation] | |||
| J --> K{Dependency/Policy Pass?} | |||
| K -- No --> L[Show Blockers + Reason + Corrective Action] | |||
| L --> F | |||
| K -- Yes --> M[Publish to Production Readiness] | |||
| M --> N[Show Confirmation + Provenance + Next Best Action] | |||
| ``` | |||
| ### Production Lead - Dependency Exception Recovery | |||
| Goal: resolve blockers before cutoff and preserve auditable exception history. | |||
| ```mermaid | |||
| flowchart TD | |||
| A[Open Risk Queue] --> B[Select At-Risk Job] | |||
| B --> C[View Timeline + Dependency Panel] | |||
| C --> D{Blocking Dependency Found?} | |||
| D -- No --> E[Confirm On-Track Status] | |||
| E --> F[Return to Queue] | |||
| D -- Yes --> G[Create Exception Record] | |||
| G --> H[Assign Owner + Due-By Timestamp] | |||
| H --> I[Request Required Field Updates] | |||
| I --> J{Updates Completed Before Cutoff?} | |||
| J -- No --> K[Escalate + Replan Downstream Milestones] | |||
| K --> L[Record Escalation Trail] | |||
| J -- Yes --> M[Re-run Validation] | |||
| M --> N[Clear Blocker and Update Status] | |||
| N --> O[Write Audit Trail: actor/time/reason] | |||
| O --> F | |||
| ``` | |||
| ### Transportation Coordinator - Daily Dispatch Planning | |||
| Goal: produce accurate date-sorted runs tied directly to election milestones. | |||
| ```mermaid | |||
| flowchart TD | |||
| A[Open Transportation Report Workspace] --> B[Set Date Range: Next Day / 7-Day Lookahead] | |||
| B --> C[Apply Saved Filters: County, Municipality, Service Status] | |||
| C --> D[Aggregate Pickup/Delivery Events from Extension + Legacy Joins] | |||
| D --> E[Group by Date then County then Municipality] | |||
| E --> F{Missing Critical Event Data?} | |||
| F -- Yes --> G[Flag Record + Open Linked Job for Correction] | |||
| G --> H[Refresh Report After Correction] | |||
| H --> D | |||
| F -- No --> I[Generate Dispatch Stop List] | |||
| I --> J[Review Quantity and Notes] | |||
| J --> K[Export CSV/XLSX-Compatible Output] | |||
| K --> L[Mark Dispatch Plan Ready] | |||
| ``` | |||
| ### Journey Patterns | |||
| Navigation patterns: | |||
| - Role-based entry to a single operations workspace | |||
| - Queue-to-detail-to-queue loop without context loss | |||
| - Inline drill-in from report row to corrective action | |||
| Decision patterns: | |||
| - Required-field gate before publish | |||
| - Dependency/policy gate before commit | |||
| - Escalate-or-resolve branch based on cutoff timing | |||
| Feedback patterns: | |||
| - Immediate pass/fail validation states | |||
| - Explicit blocked reasons with one-click recovery path | |||
| - Provenance feedback after critical updates (actor/time/reason) | |||
| ### Flow Optimization Principles | |||
| - Keep users in one workspace during critical operations. | |||
| - Surface blockers before commit, not after. | |||
| - Make all high-risk actions explainable at point-of-action. | |||
| - Favor deterministic sorting/filtering for shared operational truth. | |||
| - Provide keyboard-first dense workflows for PC operators. | |||
| - Ensure every failure path ends with a clear next action. | |||
| ## Component Strategy | |||
| ### Design System Components | |||
| Use Ant Design foundation components as the default baseline: | |||
| - Layout and navigation: `Layout`, `Menu`, `Breadcrumb`, `Tabs` | |||
| - Data and tables: `Table`, `Tag`, `Tooltip`, `Badge`, `Pagination` | |||
| - Input and forms: `Form`, `Input`, `Select`, `DatePicker`, `Checkbox`, `Radio` | |||
| - Feedback and status: `Alert`, `Result`, `Notification`, `Modal`, `Drawer`, `Spin` | |||
| - Workflow cues: `Steps`, `Timeline`, `Progress` | |||
| - Utility patterns: `Dropdown`, `Popconfirm`, `Empty` | |||
| Coverage conclusion: | |||
| - Base CRUD, filtering, editing, modal/drawer interactions are fully supported. | |||
| - Domain-specific workflow intelligence requires custom composite components. | |||
| ### Custom Components | |||
| ### MunicipalityCycleWorkspaceGrid | |||
| Purpose: primary dense operations surface for municipality + election-cycle records. | |||
| Usage: default center pane in all role workspaces. | |||
| Anatomy: sticky header, column controls, inline editable cells, row status chips, provenance quick-view trigger. | |||
| States: default, sorted, filtered, inline-editing, validation-error, loading, empty. | |||
| Variants: compact (default), review mode (read-heavy). | |||
| Accessibility: keyboard row/cell navigation, sortable headers with ARIA sort state, error messaging tied to fields. | |||
| Interaction behavior: deterministic sort/filter, explicit commit for sensitive fields. | |||
| ### SafeCommitRail | |||
| Purpose: pre-commit dependency and policy gate for high-impact updates. | |||
| Usage: appears when status/date/service changes affect downstream operations. | |||
| Anatomy: validation summary, blocking reasons, corrective links, reason-code selector, commit action. | |||
| States: pass, warning, blocked, submitting, success. | |||
| Variants: inline rail (grid), drawer rail (detail mode). | |||
| Accessibility: focus lands on first blocker, screen-reader summary of pass/fail reasons. | |||
| Interaction behavior: commit disabled until required checks and reason codes are satisfied. | |||
| ### CutoffRiskQueuePanel | |||
| Purpose: persistent urgency queue for deadline-sensitive work. | |||
| Usage: right pane in tri-pane layout; always visible in operations views. | |||
| Anatomy: prioritized cards, countdown/due state, severity badges, owner, quick-open action. | |||
| States: normal, at-risk, blocked, overdue, resolved. | |||
| Variants: compact list, expanded analytical view. | |||
| Accessibility: severity announced with text labels (not color alone), keyboard selection and open action. | |||
| Interaction behavior: queue reorders deterministically after updates. | |||
| ### BlockerResolutionDrawer | |||
| Purpose: in-context recovery workspace for blocked records. | |||
| Usage: opened from blocked status, risk queue, or validation failures. | |||
| Anatomy: blocker details, dependency links, assignment, due-by edit, resolution note, save controls. | |||
| States: open/edit, invalid, saved, escalated. | |||
| Variants: standard blocker, escalation mode. | |||
| Accessibility: focus trap, labeled controls, error summaries. | |||
| Interaction behavior: save writes exception history and returns user to previous context. | |||
| ### DispatchRunBuilder | |||
| Purpose: transform transportation events into date-sorted dispatch output. | |||
| Usage: transportation workspace for next-day and 7-day planning. | |||
| Anatomy: date range controls, filter set, grouped results, quantity notes, export actions. | |||
| States: unfiltered, filtered, data-gap warning, ready-to-export, exported. | |||
| Variants: next-day quick mode, week lookahead mode. | |||
| Accessibility: keyboard filter controls, grouped headings with clear labels. | |||
| Interaction behavior: can deep-link directly to corrective records when gaps are detected. | |||
| ### ProvenanceTimelinePanel | |||
| Purpose: show who changed what, when, and why at point-of-action. | |||
| Usage: side panel and row-level detail context. | |||
| Anatomy: timestamped events, actor, reason code, changed fields, source link. | |||
| States: populated, loading, empty, filtered. | |||
| Variants: compact inline preview, full audit view. | |||
| Accessibility: semantic timeline structure, clear event narration for screen readers. | |||
| Interaction behavior: supports rapid investigation without leaving current workflow. | |||
| ### Component Implementation Strategy | |||
| - Build all custom components as Ant Design wrappers/composites using shared tokens. | |||
| - Keep behavior contracts strict: deterministic sorting/filtering, explicit commit for sensitive transitions, visible provenance. | |||
| - Standardize state models across components: loading, empty, validation error, blocked, success. | |||
| - Enforce accessibility at component level: keyboard pathways, ARIA labels, non-color status cues. | |||
| - Align data boundaries in UI contracts: | |||
| - Legacy entities are read-only source context. | |||
| - Extension entities handle new writes and workflow state. | |||
| - Join identifiers (`ID`, `JCode`/`JurisCode`, `KitID`) are explicit in component data contracts. | |||
| ### Implementation Roadmap | |||
| Phase 1 - Core workflow components: | |||
| - MunicipalityCycleWorkspaceGrid | |||
| - SafeCommitRail | |||
| - CutoffRiskQueuePanel | |||
| Phase 2 - Recovery and reporting components: | |||
| - BlockerResolutionDrawer | |||
| - DispatchRunBuilder | |||
| Phase 3 - Traceability and optimization: | |||
| - ProvenanceTimelinePanel | |||
| - Shared utilities for status chips, reason-code pickers, and validation summaries | |||
| ## UX Consistency Patterns | |||
| ### Button Hierarchy | |||
| Primary action rules: | |||
| - Use one primary button per context (for example: `Publish`, `Commit Update`, `Export Dispatch`). | |||
| - Primary buttons use `colorPrimary` and are placed at decision-completion points. | |||
| - Disable primary buttons when required checks are incomplete; always show why. | |||
| Secondary action rules: | |||
| - Secondary buttons for non-destructive alternatives (`Cancel`, `Back`, `Review Later`). | |||
| - Tertiary/text actions for low-risk utilities (`View History`, `Open Details`). | |||
| Destructive action rules: | |||
| - Destructive actions require explicit confirmation (`Popconfirm` or `Modal`) with impact summary. | |||
| - Require reason code for irreversible operational changes. | |||
| Accessibility: | |||
| - All buttons have clear labels (no icon-only for critical actions). | |||
| - Keyboard focus visible and consistent across all action tiers. | |||
| ### Feedback Patterns | |||
| Success: | |||
| - Immediate inline confirmation after save/commit. | |||
| - Show changed fields + provenance snippet (actor/time/reason). | |||
| Warning: | |||
| - At-risk states use warning chips with clear due-by context. | |||
| - Warning banners include direct corrective action links. | |||
| Error/Blocked: | |||
| - Blocked commits show a structured blocker list with jump-to-fix actions. | |||
| - Error copy is specific, actionable, and non-blaming. | |||
| Info: | |||
| - Neutral informational states for refresh/sync and report generation progress. | |||
| - Use concise, non-intrusive messaging for routine system updates. | |||
| Consistency rules: | |||
| - Never rely on color alone; pair status with icon and text. | |||
| - Use same severity mapping across grid, queue, drawers, timelines, and reports. | |||
| ### Form Patterns | |||
| Structure: | |||
| - Group fields by operational intent: municipality context, cycle data, services, milestones, ownership. | |||
| - Keep permanent municipality context visibly read-only when sourced from legacy tables. | |||
| Validation: | |||
| - Validate required fields progressively as users edit. | |||
| - Reserve hard-block validation for publish/commit checkpoints. | |||
| - Show inline field-level errors plus top-level summary for multi-error states. | |||
| Entry behavior: | |||
| - Use defaults from prior cycle when available, visibly marked as inherited values. | |||
| - Date and quantity fields use strict input formatting and keyboard-friendly controls. | |||
| Commit behavior: | |||
| - Sensitive transitions invoke SafeCommitRail with dependency/policy checks. | |||
| - Reason code required where audit policy requires it. | |||
| ### Navigation Patterns | |||
| Workspace model: | |||
| - Standard tri-pane structure: | |||
| - Left: context and saved views | |||
| - Center: operational grid/work area | |||
| - Right: risk queue + inspector/provenance | |||
| Flow model: | |||
| - Queue -> detail -> corrective action -> queue return, with no context loss. | |||
| - Deep-linking allowed from reports to corrective records. | |||
| State persistence: | |||
| - Preserve filters, sorting, and column presets per user role/workspace. | |||
| - On refresh/re-entry, restore last valid operational view where safe. | |||
| ### Additional Patterns | |||
| Search and filtering: | |||
| - Deterministic filtering/sorting with always-visible active filter chips. | |||
| - Saved filter presets for recurring dispatch and production scenarios. | |||
| - Clear reset behavior and predictable default sort (urgency then due date). | |||
| Modal and overlay: | |||
| - Use drawers for in-context edits and investigation. | |||
| - Use modals for high-risk confirmations and irreversible actions only. | |||
| - Focus management and escape/close behavior standardized. | |||
| Loading, empty, and no-result states: | |||
| - Loading: skeleton/compact spinner with context text. | |||
| - Empty: explain why list is empty and provide next action. | |||
| - No results: show active filter causes and one-click clear/adjust. | |||
| Desktop-first rule: | |||
| - UX patterns are optimized for PC keyboard + mouse workflows. | |||
| - Tablet-first and mobile-first interaction variants are out of scope for current product scope. | |||
| ## Responsive Design & Accessibility | |||
| ### Responsive Strategy | |||
| Primary strategy: desktop-first operational UX for office environments only. | |||
| - Supported interaction model: keyboard + mouse | |||
| - Core layouts optimized for 1280px+ operational screens | |||
| - Dense tri-pane workspace remains default for core workflows | |||
| - No tablet-specific or phone-specific UX targets in current scope | |||
| - If viewport is below supported width, show constrained fallback with guidance to use supported desktop resolution | |||
| ### Breakpoint Strategy | |||
| Desktop-only breakpoint model: | |||
| - Minimum supported operational width: 1280px | |||
| - Standard desktop: 1280px - 1599px | |||
| - Wide desktop: 1600px+ | |||
| Adaptation behavior: | |||
| - 1280px - 1599px: compact tri-pane with collapsible secondary pane | |||
| - 1600px+: full tri-pane with persistent risk/provenance panel | |||
| - Below 1280px: reduced read mode and support notice for full editing workflows | |||
| ### Accessibility Strategy | |||
| Compliance target: WCAG 2.2 AA for all MVP and operationally critical flows. | |||
| Core requirements: | |||
| - Full keyboard operability for create/edit/commit/report/export workflows | |||
| - Visible focus indicators and logical tab order across grid, drawers, modals, and forms | |||
| - Semantic labels and ARIA attributes for custom composite components | |||
| - Color is never the sole indicator of status | |||
| - Clear, actionable error and blocker messaging | |||
| - Screen-reader-readable provenance and validation summaries | |||
| ### Testing Strategy | |||
| Responsive testing: | |||
| - Validate at 1280, 1366, 1440, and 1920 desktop widths | |||
| - Cross-browser desktop matrix: Chrome, Edge, Firefox (current major versions) | |||
| Accessibility testing: | |||
| - Automated scans (axe/Lighthouse or equivalent) in CI for critical pages | |||
| - Manual keyboard-only walkthroughs for core journeys | |||
| - Screen reader spot checks (NVDA + VoiceOver where available) | |||
| - Contrast validation for all semantic states (success/warn/error/info) | |||
| Acceptance checks: | |||
| - Core journeys complete without mouse-only dependencies | |||
| - No critical accessibility violations remain open at release gate | |||
| - Below-minimum viewport behavior is explicit and non-breaking | |||
| ### Implementation Guidelines | |||
| Responsive implementation: | |||
| - Use CSS grid/flex with desktop-first media queries | |||
| - Preserve deterministic column behavior in dense tables | |||
| - Keep right-side risk/provenance panels collapsible, not removed, at narrower desktop widths | |||
| Accessibility implementation: | |||
| - Use semantic HTML first, ARIA second | |||
| - Standardize focus management for modal/drawer open/close flows | |||
| - Provide reusable accessibility helpers in component layer: | |||
| - status text + icon pairings | |||
| - validation summary announcer | |||
| - keyboard shortcut hints where appropriate | |||
| Operational guardrail: | |||
| - Do not invest in touch-target optimization or tablet/mobile navigation patterns in current release scope. | |||
| ## Approved Correct Course Addendum (2026-05-05) | |||
| ### ImportReviewWorkspace Flow | |||
| Add a dedicated flow for source ingestion and operator review: | |||
| - Import source file or approved export | |||
| - Preview column mapping and data typing | |||
| - Show deterministic validation issues by row and field | |||
| - Stage publish-ready rows separately from blocked rows | |||
| - Confirm publish with explicit provenance summary | |||
| ### Reconciliation Queue UX | |||
| Add a role-aware data quality queue: | |||
| - Mismatch list with severity, owner, status, and due date | |||
| - Deep-link from mismatches to affected report rows and traceability views | |||
| - Blocking-warning behavior on export when unresolved high-severity mismatches exist for selected scope | |||
| ### Contact and Proof Workflow Visibility | |||
| For proof/contact fields (`Proof Sent`, `Proof Approved`, contact assignment values): | |||
| - Show explicit role-based visibility and edit affordances | |||
| - Keep actor/timestamp provenance visible where policy allows | |||
| - Preserve deterministic filtering/sorting behavior in all related report and queue views | |||
+ 450
- 0
_bmad-output/planning-artifacts/validation-report-2026-04-03.md
Ver fichero
| @@ -0,0 +1,450 @@ | |||
| --- | |||
| validationTarget: 'C:/Users/danielc.NTP/Desktop/Brians Client Route Reports App/_bmad-output/planning-artifacts/prd.md' | |||
| validationDate: '2026-04-03' | |||
| inputDocuments: | |||
| - Initial Description.txt | |||
| - Initial Documents/Access_Schema.txt | |||
| - Initial Documents/Client Database Plan.xlsx | |||
| - _bmad-output/planning-artifacts/client-database-plan-extract.txt | |||
| validationStepsCompleted: | |||
| - step-v-01-discovery | |||
| - step-v-02-format-detection | |||
| - step-v-03-density-validation | |||
| - step-v-04-brief-coverage-validation | |||
| - step-v-05-measurability-validation | |||
| - step-v-06-traceability-validation | |||
| - step-v-07-implementation-leakage-validation | |||
| - step-v-08-domain-compliance-validation | |||
| - step-v-09-project-type-validation | |||
| - step-v-10-smart-validation | |||
| - step-v-11-holistic-quality-validation | |||
| - step-v-12-completeness-validation | |||
| validationStatus: COMPLETE | |||
| holisticQualityRating: '4/5 - Good' | |||
| overallStatus: 'Warning' | |||
| --- | |||
| # PRD Validation Report | |||
| **PRD Being Validated:** C:/Users/danielc.NTP/Desktop/Brians Client Route Reports App/_bmad-output/planning-artifacts/prd.md | |||
| **Validation Date:** 2026-04-03 | |||
| ## Input Documents | |||
| - PRD: `_bmad-output/planning-artifacts/prd.md` | |||
| - `Initial Description.txt` | |||
| - `Initial Documents/Access_Schema.txt` | |||
| - `Initial Documents/Client Database Plan.xlsx` | |||
| - `_bmad-output/planning-artifacts/client-database-plan-extract.txt` | |||
| ## Validation Findings | |||
| Findings will be appended as validation progresses. | |||
| ## Format Detection | |||
| **PRD Structure (Level 2 Headers):** | |||
| - Executive Summary | |||
| - Project Classification | |||
| - Success Criteria | |||
| - Product Scope | |||
| - User Journeys | |||
| - Domain-Specific Requirements | |||
| - Web App Specific Requirements | |||
| - Project Scoping & Phased Development | |||
| - Functional Requirements | |||
| - Non-Functional Requirements | |||
| **BMAD Core Sections Present:** | |||
| - Executive Summary: Present | |||
| - Success Criteria: Present | |||
| - Product Scope: Present | |||
| - User Journeys: Present | |||
| - Functional Requirements: Present | |||
| - Non-Functional Requirements: Present | |||
| **Classification Metadata:** | |||
| - Domain: `govtech` | |||
| - Project Type: `web_app` | |||
| **Format Classification:** BMAD Standard | |||
| **Core Sections Present:** 6/6 | |||
| ## Information Density Validation | |||
| **Anti-Pattern Violations:** | |||
| **Conversational Filler:** 0 occurrences | |||
| No matches for target filler patterns. | |||
| **Wordy Phrases:** 0 occurrences | |||
| No matches for target wordy-phrase patterns. | |||
| **Redundant Phrases:** 0 occurrences | |||
| No matches for target redundancy patterns. | |||
| **Total Violations:** 0 | |||
| **Severity Assessment:** Pass | |||
| **Recommendation:** PRD demonstrates good information density with minimal violations. | |||
| ## Product Brief Coverage | |||
| **Status:** N/A - No Product Brief was provided as input. | |||
| ## Measurability Validation | |||
| ### Functional Requirements | |||
| **Total FRs Analyzed:** 34 | |||
| **Format Violations:** 0 | |||
| All FR statements follow actor-capability structure (`[Actor] can [capability]`). | |||
| **Subjective Adjectives Found:** 0 (within FRs) | |||
| **Vague Quantifiers Found:** 0 (within FRs) | |||
| **Implementation Leakage:** 0 | |||
| **FR Violations Total:** 0 | |||
| ### Non-Functional Requirements | |||
| **Total NFRs Analyzed:** 17 | |||
| **Missing Metrics:** 10 | |||
| Examples: | |||
| - `NFR4` (line 361): "encrypted in transit using current TLS standards" has no measurable verification criterion. | |||
| - `NFR6` (line 363): role-based authorization requirement is stated without measurable test thresholds. | |||
| - `NFR9` (line 369): concurrent usage support is required but no numeric concurrency target is defined. | |||
| - `NFR11` (line 374): operability requirement has no measurable conformance test scope. | |||
| **Incomplete Template:** 9 | |||
| Examples: | |||
| - `NFR5` (line 362): lacks explicit measurement method and validation context. | |||
| - `NFR7` (line 364): logging requirement lacks measurable completeness/latency expectations. | |||
| - `NFR13` (line 379): referential consistency requirement lacks validation thresholds. | |||
| **Missing Context:** 6 | |||
| Examples: | |||
| - `NFR4` (line 361), `NFR5` (line 362), `NFR12` (line 378): context for operating conditions and acceptance boundaries is not explicit. | |||
| **NFR Violations Total:** 25 | |||
| ### Overall Assessment | |||
| **Total Requirements:** 51 | |||
| **Total Violations:** 25 | |||
| **Severity:** Critical | |||
| **Recommendation:** Many NFRs need refinement to be consistently testable. Add explicit pass/fail metrics, measurement methods, and operational context for security, integration, and accessibility requirements. | |||
| ## Traceability Validation | |||
| ### Chain Validation | |||
| **Executive Summary -> Success Criteria:** Intact | |||
| Vision themes (compatibility-first modernization, dual data horizons, operational reporting) are reflected in User/Business/Technical success criteria. | |||
| **Success Criteria -> User Journeys:** Gaps Identified | |||
| Most criteria are represented by journey outcomes; one measurable target (`95% municipality account completeness`) is not explicitly represented in journey narratives and is only implicit. | |||
| **User Journeys -> Functional Requirements:** Intact | |||
| All five journeys map to FR groups (setup/configuration/scheduling/transport/support/governance). | |||
| **Scope -> FR Alignment:** Intact | |||
| MVP capabilities listed in scope are covered by FR5-F34, with supporting FR22-F26 for core report outputs. | |||
| ### Orphan Elements | |||
| **Orphan Functional Requirements:** 0 | |||
| No FRs were found without business/journey rationale. | |||
| **Unsupported Success Criteria:** 1 | |||
| - Municipality account completeness target is not explicitly reflected in journey text. | |||
| **User Journeys Without FRs:** 0 | |||
| ### Traceability Matrix (Summary) | |||
| | Source | Downstream Coverage | Status | | |||
| |---|---|---| | |||
| | Executive Summary themes | Success Criteria + Scope + FR areas | Covered | | |||
| | Success Criteria | User Journeys + FRs/NFRs | Partially Covered | | |||
| | User Journeys (1-5) | FR9-F33 clusters | Covered | | |||
| | MVP Scope items | FR5-F34 and NFR set | Covered | | |||
| **Total Traceability Issues:** 1 | |||
| **Severity:** Warning | |||
| **Recommendation:** Add one explicit journey statement tying municipality profile completeness to measurable success outcomes for fully closed-loop traceability. | |||
| ## Implementation Leakage Validation | |||
| ### Leakage by Category | |||
| **Frontend Frameworks:** 0 violations | |||
| **Backend Frameworks:** 0 violations | |||
| **Databases:** 0 violations | |||
| **Cloud Platforms:** 0 violations | |||
| **Infrastructure:** 0 violations | |||
| **Libraries:** 0 violations | |||
| **Other Implementation Details:** 0 violations | |||
| ### Summary | |||
| **Total Implementation Leakage Violations:** 0 | |||
| **Severity:** Pass | |||
| **Recommendation:** No significant implementation leakage found. Requirements are expressed as capabilities/constraints rather than build-technology instructions. | |||
| **Note:** A keyword scan flagged "at rest" in `NFR5`; this is not REST API leakage and was treated as a false positive. | |||
| ## Domain Compliance Validation | |||
| **Domain:** govtech | |||
| **Complexity:** High (regulated) | |||
| ### Required Special Sections | |||
| **Accessibility Standards:** Present / Adequate | |||
| Evidence: `Domain-Specific Requirements` and `NFR10-NFR11` reference WCAG 2.1 AA-aligned expectations. | |||
| **Procurement Compliance:** Present / Partial | |||
| Evidence: procurement expectations are mentioned; explicit procurement workflow/gate criteria are not detailed. | |||
| **Security Clearance Requirements:** Missing | |||
| No explicit clearance model or handling requirements were found. | |||
| **Data Residency Requirements:** Missing | |||
| No explicit residency, jurisdictional storage, or geo-boundary controls were found. | |||
| ### Compliance Matrix | |||
| | Requirement | Status | Notes | | |||
| |---|---|---| | |||
| | Accessibility (WCAG 2.1 AA / 508 alignment) | Met | Covered in domain + NFR sections | | |||
| | Procurement compliance expectations | Partial | Mentioned, but acceptance criteria are thin | | |||
| | Security clearance controls | Missing | No section or NFR defining this | | |||
| | Data residency constraints | Missing | No section or NFR defining this | | |||
| ### Summary | |||
| **Required Sections Present:** 2/4 fully met (1 partial, 2 missing) | |||
| **Compliance Gaps:** 3 | |||
| **Severity:** Warning | |||
| **Recommendation:** Add explicit govtech compliance coverage for security-clearance handling and data-residency requirements; tighten procurement compliance with concrete acceptance criteria. | |||
| ## Project-Type Compliance Validation | |||
| **Project Type:** web_app | |||
| ### Required Sections | |||
| **Browser Matrix:** Present | |||
| **Responsive Design:** Present | |||
| **Performance Targets:** Present | |||
| **SEO Strategy:** Present | |||
| **Accessibility Level:** Present | |||
| ### Excluded Sections (Should Not Be Present) | |||
| **Native Features Section:** Absent | |||
| **CLI Commands Section:** Absent | |||
| ### Compliance Summary | |||
| **Required Sections:** 5/5 present | |||
| **Excluded Sections Present:** 0 | |||
| **Compliance Score:** 100% | |||
| **Severity:** Pass | |||
| **Recommendation:** All required `web_app` sections are present and no excluded sections were introduced. | |||
| ## SMART Requirements Validation | |||
| **Total Functional Requirements:** 34 | |||
| ### Scoring Summary | |||
| **All scores >= 3:** 100% (34/34) | |||
| **All scores >= 4:** 79.4% (27/34) | |||
| **Overall Average Score:** 4.72/5.0 | |||
| ### Scoring Table | |||
| | FR # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag | | |||
| |---|---:|---:|---:|---:|---:|---:|---| | |||
| | FR1 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR2 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR3 | 5 | 3 | 5 | 5 | 4 | 4.4 | | | |||
| | FR4 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR5 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR6 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR7 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR8 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR9 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR10 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR11 | 5 | 3 | 5 | 5 | 4 | 4.4 | | | |||
| | FR12 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR13 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR14 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR15 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR16 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR17 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR18 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR19 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR20 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR21 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR22 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR23 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR24 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR25 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR26 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR27 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR28 | 5 | 3 | 5 | 5 | 4 | 4.4 | | | |||
| | FR29 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR30 | 5 | 3 | 5 | 5 | 4 | 4.4 | | | |||
| | FR31 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR32 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR33 | 5 | 4 | 5 | 5 | 5 | 4.8 | | | |||
| | FR34 | 5 | 3 | 5 | 5 | 4 | 4.4 | | | |||
| **Legend:** 1=Poor, 3=Acceptable, 5=Excellent | |||
| **Flag:** X = Score < 3 in one or more categories | |||
| ### Improvement Suggestions | |||
| No FR scored below 3. | |||
| Optional refinements for FR3, FR11, FR28, FR30, FR34: add tighter acceptance boundaries (for example, explicit completion criteria or validation rules) to raise measurability from 3 to 4+. | |||
| ### Overall Assessment | |||
| **Severity:** Pass | |||
| **Recommendation:** Functional Requirements demonstrate good SMART quality overall. | |||
| ## Holistic Quality Assessment | |||
| ### Document Flow & Coherence | |||
| **Assessment:** Good | |||
| **Strengths:** | |||
| - Clear progression from vision to scope to capability contract. | |||
| - Consistent terminology around legacy immutability and extension-model strategy. | |||
| - Strong sectional structure with readable headings for both stakeholders and downstream agents. | |||
| **Areas for Improvement:** | |||
| - Some compliance expectations are scattered across Domain and NFR sections rather than consolidated into explicit govtech compliance acceptance criteria. | |||
| - A few traceability links are implicit rather than explicitly stated (success criterion -> journey mapping). | |||
| ### Dual Audience Effectiveness | |||
| **For Humans:** | |||
| - Executive-friendly: Good | |||
| - Developer clarity: Good | |||
| - Designer clarity: Good | |||
| - Stakeholder decision-making: Good | |||
| **For LLMs:** | |||
| - Machine-readable structure: Excellent | |||
| - UX readiness: Good | |||
| - Architecture readiness: Good | |||
| - Epic/Story readiness: Good | |||
| **Dual Audience Score:** 4/5 | |||
| ### BMAD PRD Principles Compliance | |||
| | Principle | Status | Notes | | |||
| |---|---|---| | |||
| | Information Density | Met | Minimal filler; direct language | | |||
| | Measurability | Partial | FR quality is strong; several NFRs need explicit test metrics | | |||
| | Traceability | Partial | Chain is mostly intact with one implicit success-journey link | | |||
| | Domain Awareness | Partial | Govtech coverage exists but misses explicit clearance/residency requirements | | |||
| | Zero Anti-Patterns | Met | No major density anti-patterns found | | |||
| | Dual Audience | Met | Readable for people and structured for LLM workflows | | |||
| | Markdown Format | Met | Strong section hierarchy and formatting consistency | | |||
| **Principles Met:** 4/7 fully met (3 partial) | |||
| ### Overall Quality Rating | |||
| **Rating:** 4/5 - Good | |||
| ### Top 3 Improvements | |||
| 1. **Make NFRs uniformly testable** | |||
| Add explicit metrics, measurement methods, and operational context to the currently qualitative NFRs. | |||
| 2. **Strengthen govtech compliance specificity** | |||
| Add explicit security-clearance and data-residency requirements with pass/fail criteria. | |||
| 3. **Tighten traceability annotations** | |||
| Add explicit links from each success criterion to one or more journey statements (and/or FR clusters). | |||
| ### Summary | |||
| **This PRD is:** strong, implementation-ready, and well structured, with targeted compliance/measurability refinements needed for excellence. | |||
| **To make it great:** focus on the top 3 improvements above. | |||
| ## Completeness Validation | |||
| ### Template Completeness | |||
| **Template Variables Found:** 0 | |||
| No unresolved template variables remain. | |||
| ### Content Completeness by Section | |||
| **Executive Summary:** Complete | |||
| **Success Criteria:** Complete | |||
| **Product Scope:** Complete | |||
| **User Journeys:** Complete | |||
| **Functional Requirements:** Complete | |||
| **Non-Functional Requirements:** Complete | |||
| ### Section-Specific Completeness | |||
| **Success Criteria Measurability:** Some measurable | |||
| Most criteria are measurable; one user-success statement is qualitative and could be metricized. | |||
| **User Journeys Coverage:** Yes - covers all core user types identified for MVP operations. | |||
| **FRs Cover MVP Scope:** Yes | |||
| **NFRs Have Specific Criteria:** Some | |||
| Several NFRs remain qualitative and need explicit test metrics/methods. | |||
| ### Frontmatter Completeness | |||
| **stepsCompleted:** Present | |||
| **classification:** Present | |||
| **inputDocuments:** Present | |||
| **date:** Missing | |||
| **Frontmatter Completeness:** 3/4 | |||
| ### Completeness Summary | |||
| **Overall Completeness:** 92% (11/12 checks complete) | |||
| **Critical Gaps:** 0 | |||
| **Minor Gaps:** 3 | |||
| - Frontmatter `date` field is not present. | |||
| - One success criterion remains qualitative. | |||
| - Multiple NFRs need stronger measurable criteria. | |||
| **Severity:** Warning | |||
| **Recommendation:** PRD is structurally complete and usable; address minor measurability/frontmatter refinements for full completeness. | |||
+ 6
- 0
docs/index.md
Ver fichero
| @@ -0,0 +1,6 @@ | |||
| # Project Knowledge Index | |||
| ## Sources | |||
| - [August 2026 Primary Ballot Envelope Tracking Source](./source-2026-08-primary-ballot-envelope-tracking.md) | |||
+ 33
- 0
docs/source-2026-08-primary-ballot-envelope-tracking.md
Ver fichero
| @@ -0,0 +1,33 @@ | |||
| # August 2026 Primary Ballot Envelope Tracking Source | |||
| ## Source Metadata | |||
| - Type: Google Sheets (shared workbook) | |||
| - Title: `AUGUST 2026 PRIMARY Ballot Envelope Imprinting and Tracking Scheduled .xlsx` | |||
| - URL: `https://docs.google.com/spreadsheets/d/1l77Hvw-vmdE8FnByxr7Ink4zMtp66iAc/edit?gid=1537818588` | |||
| - Added to project knowledge: 2026-05-05 | |||
| - Added by: project team (late planning input) | |||
| ## Why This Matters | |||
| This source adds real election-cycle operational detail that should be represented in planning and implementation: | |||
| - Jurisdiction and municipality-level planning rows | |||
| - Addressing/tracking and round-trip flags | |||
| - NetSort / NP-STD / CRID / auth and KCI-related fields | |||
| - Envelope and return-envelope flow details | |||
| - Sorting, daily sort, permit/meter, and mail date fields | |||
| - Proofing and contact workflow fields (`Proof Sent`, `Proof Approved`, contact emails/names) | |||
| ## Integration Notes | |||
| - Treat this as a planning and reconciliation source, not a direct legacy-table replacement. | |||
| - Map spreadsheet columns to extension-layer entities and preserve provenance (source row, import timestamp, actor). | |||
| - Validate join keys against legacy identifiers (`ID`, `JCode`/`JurisCode`, `KitID`) before publishing changes. | |||
| - Protect contact data with role-based visibility and audit logging. | |||
| ## Next Workflow Touchpoints | |||
| - `bmad-correct-course` to formalize scope/impact changes | |||
| - `bmad-check-implementation-readiness` after PRD/epic/architecture updates | |||