--- 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 - Campaign_Tracker 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.