Technical Architecture

Entity overview

Seven models. The core voting path is Meeting → VotingSession → Vote. The check-in path is RegisteredVoter ↔ CheckIn ↔ Meeting. Voter token issuance is Meeting → VoterToken ← deviceToken.

Key fields and design decisions

ID strategy

All primary keys use cuid() — collision-resistant IDs generated by Prisma. Room codes are separate cryptographically random strings (see Section 4). deviceToken is a UUID generated client-side with crypto.randomUUID() and persisted in localStorage.

All routes are Next.js App Router Route Handlers (route.ts files). Every route returns JSON. Auth is enforced per-route — there is no middleware layer doing blanket auth.

Public voter routes (no auth required)

Moderator routes (mod token required)

Check-in routes (PIN-authenticated)

Admin routes (global mod + admin password)

The system has three distinct auth contexts: moderator auth, voter pass auth, and check-in PIN auth. None of them use a third-party auth provider — everything is implemented with Node.js crypto.

Moderator token (HMAC-SHA256, 12h TTL)

The token is transported two ways simultaneously: an HttpOnly; Secure; SameSite=Lax cookie (mod_auth) set at login, and in the response body for the client to persist in localStorage. API routes accept either. The dual transport exists because Safari ITP can block third-party cookies; the header fallback (x-mod-auth) via localStorage ensures moderators on Safari aren't silently logged out mid-meeting.

Join token (HMAC-SHA256, 8h TTL)

Issued by /api/join after a voter successfully enters the room. Proves that a specific (meetingId, deviceToken) pair went through the join flow. The vote endpoint requires it — preventing a script from generating random deviceToken values and submitting votes without ever joining.

Moderator login (SHA-256 password hash)

The stored credential is a SHA-256 hex digest of the plaintext password, set via the MOD_PASSWORD environment variable. At login, the supplied password is hashed and compared using timingSafeEqual. On success, a signToken("global") token is issued with a 12-hour TTL and set as an HttpOnly cookie.

Check-in PIN

A plain numeric PIN stored on the Meeting record (checkInPin field). Volunteers enter it on the check-in tablet. Verified at /api/checkin/[roomCode]/verify-pin. The PIN grants access only to check-in operations — not to moderator controls.

Authorization matrix

The POST /api/vote handler is the most security-critical path in the application. Every vote passes through eight sequential checks before a DB write is attempted. A failure at any step returns a 4xx and logs the event.

One-open-at-a-time enforcement

When a moderator opens a session, PATCH /api/sessions/[id] runs a Serializable-isolation transaction:

The application uses HTTP polling rather than WebSockets or SSE. This was a deliberate trade-off: polling is stateless, works through all proxy/CDN layers, and eliminates persistent connection management on a serverless platform.

Voter client polling (/api/active/[roomCode])

• The voter page calls POST /api/active/[roomCode] with the deviceToken in the body every ~3 seconds while a vote is not open
• The endpoint upserts a Heartbeat row (last-seen timestamp) and returns the currently OPEN session or null
• When an OPEN session is returned, the voter UI transitions to the ballot screen
• When the voter is on the ballot screen, polling pauses — the vote is submitted directly and the result is shown from the response
• Heartbeats stop being recorded for CLOSED meetings (no point counting attendees post-adjourn)

Moderator dashboard polling (/api/meetings/[meetingId]/sessions)

• The moderator control panel re-fetches the full session list periodically to pick up vote counts as ballots come in
• The sessions endpoint returns votes with deviceToken for authorized callers — the client computes the tally from the raw votes array (no separate tally field is stored)
• The tally is derived from tallyFromVotes(session.votes) in types/voting.ts — a pure function, no server-side aggregation stored

Display page

The public display page (/display/[roomCode]) polls /api/meetings/[meetingId]/sessions and renders live tallies with Recharts bar and pie charts. Intended to be projected on the auditorium screen during a vote.

HMAC tokens — crypto.createHmac

Two independent HMAC token types. Both use the same MOD_SECRET env var, SHA-256 digest, and timingSafeEqual for constant-time comparison.

Password storage — SHA-256 hex digest

The moderator password is stored as a SHA-256 hex digest in the MOD_PASSWORD env var (not in the database). This is not bcrypt — the trade-off is that SHA-256 is fast (no salting, no stretch), acceptable here because the password gates a single-operator system behind an additional HMAC token layer, and the token is the actual credential for all API calls after login.

GPS geofencing — Haversine formula

Voter pass token claiming — race condition prevention

Rate limiting — Upstash Redis sliding window

Input validation

• All ID fields capped at 128 characters — prevents oversized-payload DoS
• choice field validated as strict enum — no other values accepted
• Room codes normalized to uppercase before DB lookup
• Voter token count capped at 10,000 — prevents mass DB row insertion via the token generation endpoint
• Article question text capped at 2,000 characters
• Meeting title capped at 200 characters
• CSV export sanitized against formula injection (=, +, -, @, \t, \r prefixes are escaped)

Cookie security

Vote secrecy

The GET /api/meetings/[meetingId]/sessions endpoint conditionally includes or excludes deviceToken per vote based on the caller's auth status. Unauthorized callers (voters, public display) receive choice only. Moderators receive deviceToken as well, enabling the unique-voter count in the report. The individual choice → deviceToken mapping is never exposed publicly.

Vercel — Fluid Compute

Each Next.js API route handler deploys as an independent Vercel Function. Fluid Compute reuses function instances across concurrent requests — reducing cold starts compared to traditional one-request-per-instance serverless. The production domain is municipalvote.com aliased to the latest Vercel deployment.

Database — Neon PostgreSQL (two endpoints)

Environment variables

Room code generation

Cron job

GET /api/cron/deactivate-tokens is a Vercel cron route that runs on a schedule to deactivate voter tokens for meetings that have been closed. This prevents tokens from old meetings remaining claimable indefinitely.

Claude is used in exactly one place: parsing a town meeting warrant PDF into structured article data so the moderator doesn't have to enter each article manually.

Endpoint: POST /api/meetings/[meetingId]/import-ballot

The AI result is always shown to the moderator before anything is written to the database — it's a review step, not an autonomous import. The moderator can edit, reorder, or discard articles before confirming.

Test setup

• Vitest 4 — test runner and assertion library
• Prisma client is fully mocked — vi.mock("@/lib/prisma") replaces all DB calls with jest-style mock functions. Tests never hit a real database.
• Next.js NextRequest constructed inline — route handlers are called directly as async functions; no HTTP server is spun up
• 50 test files, 707 tests — all passing
• Playwright configured for E2E against the running dev server

Key test patterns

Coverage areas

• Vote integrity pipeline — all 8 checks tested individually (join token, voter pass binding, geofence, duplicate, etc.)
• HMAC token sign/verify — valid tokens, expired tokens, tampered signatures, wrong meeting scope
• Geofence accuracy cap — boundary conditions at 150m accuracy, rejection above cap
• Amendment position shifting — sibling count, article number inheritance, parent-not-found path
• Reconsider flow — closed sessions cleared and reopened, conflict detection, meeting-adjourned guard
• Serializable transaction conflict paths — simulated via mock return values
• CSV export — formula injection escaping, special character handling
• Rate limiter — mock Redis responses, in-memory fallback behaviour