← Back to DECEC

Phase Requirements

Detailed scope, acceptance criteria, models, and APIs for each phase of the Halifax-first rollout.

Phase 1 — MVP (Halifax County)

Scope

  • Coverage limited to Halifax County across the voter file and voter history datasets.
  • Fuzzy name search supporting typos, nickname variants, diacritics, and hyphenation.
  • Composable filters for status, party, age band, race, gender, districts, precinct, and voter history participation patterns.
  • Results table showing key voter attributes with row counts, paging, and CSV export.
  • Performance goals: <300 ms server latency for typical queries, <2 s p95 total load.

Acceptance Criteria

  • Fuzzy search returns intended records with Jaro–Winkler ≥ 0.88 or trigram similarity ≥ 0.3, ignoring accents and punctuation.
  • Combined filters (e.g., Party=U, Age 18–25, voted in 2020 but not 2022) match validation counts.
  • CSV exports include UTF-8 headers, handle up to 50k rows, and respect privacy banner and Terms link.
  • Accessibility: WCAG 2.2 AA compliance including keyboard navigation, skip links, ARIA for tabular data, high-contrast toggle, and text scaling controls.

Minimal Data Model

voter

Primary key ncid; includes county and registration identifiers, name components, status, party, race, gender, year of birth, calculated age, residential and mailing addresses, precinct and district codes, and registration date.

voter_history

Event-level rows joined by ncid, capturing election identifiers, dates, voting method, county, precinct at vote time, and party at vote.

Search & Filtering Notes

  • Primary engine: PostgreSQL with pg_trgm; Elastic/Lucene optional for later scale.
  • Normalization: lowercase, remove punctuation/diacritics, collapse whitespace; optional nickname table.
  • Ranking: 0.6 × name_sim + 0.2 × county_match + 0.2 × street_token_overlap.
  • Cursor-based pagination using after=<ncid, similarity> with default page size 100.

Key API Endpoints

GET /v1/voters/search?q=…&county=Halifax&party=U&age_min=18&age_max=25&voted_any_of=2020_G,2024_G&not_voted_any_of=2022_G&status=Active&limit=100&cursor=…
GET /v1/voters/{ncid}
GET /v1/exports?...

Data Refresh

Weekly ingestion jobs pull the latest voter file and history, performing idempotent loads with slowly changing dimensions for status and precinct updates. Integrity checks compare counts and null rates against prior loads; freshness messaging reflects NCSBE update cadence.

Phase 2 — Polling Places & Precinct Lists

Scope

  • Ingest election-specific polling place CSVs and early-voting site lists.
  • Expose precinct filters with exports (CSV/PDF) including polling place headers.
  • Provide lightweight precinct maps (vector tiles) with polling place pins and selectable precincts.

Acceptance Criteria

  • Precinct to polling place mappings reflect selected election (e.g., 2025 Municipal).
  • Choosing a precinct returns voters whose current precinct matches, noting file-date nuances.
  • Early-vote sites list name, address, hours, and support exports.

Data Model Additions

  • polling_place: election ID, county, precinct code, place name, address, optional geocodes.
  • early_vote_site: election ID, county, site name, address, schedule metadata.
  • precinct_geom: county, precinct code, geometry for mapping.

Phase 3 — Unregistered Voter Targeting

Scope

  • Ingest AddressNC statewide address points and normalize them.
  • Compute set differences between AddressNC and voter registration to flag likely unregistered households.
  • Provide exports and walking-order views grouped by county, precinct, and custom areas.

Acceptance Criteria

  • Precinct views show totals for all residential addresses, those with registered voters, and candidate addresses with none.
  • Confidence tiers: High (exact suite match), Medium (street+number match with unknown unit), Low (fuzzy-only matches).
  • Limitations are documented, including partial household registration and unit-level caveats.

Matching & Normalization

  • Apply USPS-style canonicalization, directional normalization, and unit standardization.
  • Join keys use (house_number, street_normalized, unit_normalized, city, zip) with Soundex fallback.
  • Geospatial tolerance of 5–10 meters to resolve minor coordinate offsets.

Phase 4 — Expanded Action Tooling

Backlog Priorities

  1. Canvass tooling: turf cutter, printable walk sheets, route optimization, mobile checklist.
  2. Early-vote tracking lenses with daily updates to remove voters from GOTV lists.
  3. Ballot cure workflows highlighting absentee issues.
  4. Contact exports for SMS/phone banks with duplicate suppression and language tags.
  5. Volunteer operations: assignments, progress counters, leaderboards.
  6. Micro-dashboards covering turnout by precinct, first-time voters, and more.
  7. Accessibility enhancements: multilingual UI, RTL support, high-contrast themes, font scaling.
  8. Data QA views: change logs, precinct churn reports.
  9. Role-based access, audit logs, scoped API keys.
  10. Statewide rollout after Halifax stability.
← Back to Goals & Personas Next: Data & Architecture →