←

VoxElect: election operations

A role-based, Arabic-first system for an election campaign team: build the voter database, assign scouts and delegates, track turnout live on election day and enter room-level results, without ever recording how anyone voted.

Every room, every delegate, every count.

A role-based, Arabic-first system for an election campaign team: build the voter database, assign scouts and delegates, track turnout live on election day and enter room-level results, without ever recording how anyone voted.

Elections · Admin and field roles · Arabic-first · React 19

  • 10+Roles, from super admin to delegate
  • 4Levels: region, mehwar, markaz, qalam
  • 3Phases: before, on and after the day
  • Dec 2025 → Mar 2026Built in

Product and front end

The product is defined in a set of documents, scope, roles, permissions, flows and screens, and the front end is built against shared typed contracts. The UI is Arabic-first; the docs are in English so the team can author and translate.

  • Product scope, roles, permissions matrix, flows and screen inventory
  • Super admin, operations admin, IT, leadership and viewer dashboards
  • Field roles: district and centre coordinators, scouts, fixed and mobile delegates
  • Voter import, merge review and de-duplication
  • Election-day turnout and results entry
  • Testing with Jest, Playwright and mutation testing

The election cycle

One system across the whole cycle, scoped by geography for every role.

  1. 1Import voter lists
  2. 2Merge and de-duplicate
  3. 3Assign scouts to voters
  4. 4Assign delegates to rooms
  5. 5Live turnout
  6. 6Chase supporters not yet voted
  7. 7Room totals after close
  8. 8Reports and export

What it does

  1. 01

    Admin side

    A command room dashboard, live turnout, scout performance, live results, voter management and profiles, list import, merge review, geography, candidates, settings, audit log, system status and exports.

  2. 02

    Field side

    Scouts update their voters and drive turnout. Fixed delegates sit in one room and mark who voted. Mobile delegates and coordinators watch their centres and districts.

  3. 03

    Vote privacy

    The system never records who a voter chose. Delegates mark turnout per voter, and candidate counts are entered as totals per room after voting ends.

  4. 04

    Matching voters

    The registry number is the primary key, with name, father, date of birth and village as a fallback, and a mismatch is flagged for IT review.

  5. 05

    Election-day locking

    Identity fields and structure lock on the day, one delegate per room, and every change is in the audit log.

  6. 06

    Any region

    Region, mehwar, markaz and qalam are configured per client, so the same system runs Beqaa and Rashaya or anywhere else.

How it was built

  1. Contracts first

    Types live in a shared contracts submodule, so the front end and the API agree on every field before a screen is built.

  2. Permissions as a matrix

    Every role has a view and edit row per module, plus geography scoping and field-level rules for what a scout may change and what only admins can.

  3. Tested like it matters

    Jest for units, Playwright for end-to-end flows and Stryker mutation testing to prove the tests catch real bugs.

Stack

Frontend
React 19, Vite, TanStack Query, Zustand, Zod, Radix UI, Tailwind CSS.
Testing
Jest, Playwright, Stryker.
Docs
Scope, roles, permissions, flows, screens, data dictionary, QA acceptance.