Hire Me
← Back to projects
Voting App

Voting App

  • pnpm workspaces
  • Turborepo
  • Fastify
  • React Native
  • Metro bundler
  • Vite
  • React
  • PostgreSQL
  • Redis
  • Docker
  • Docker Compose
  • Device fingerprinting
  • Biometric authentication flow design
  • Architecture Decision Records (ADR)
  • PRD-driven development
  • Test-driven development

Voice

One vote per verified human.

A secure, international voting and polling app. Anyone can follow a Poll, but only verified humans can Cast a Ballot, and each one only once. Every Ballot is cryptographically signed, sensitive Polls require on-device biometrics, and stopping manipulation comes before every other feature.

Animated: scrolling the Poll feed, tapping Vote on 'Should public transportation be made free in major cities?', choosing an Option in the bottom sheet, and seeing 'Thanks for your vote' with the Tally bars

Casting a Ballot. A real recording from the Demo 1 video (22 May 2026).


Features

For Participants (mobile app)

  • Phone-verified sign-up. Register with your phone number, confirm it with an SMS code entered in a slide-in sheet, then set up your profile.
  • Poll feed. Browse Polls as cards with creator attribution and time posted. A collapsible top bar, a sidebar and dark mode come built in.
  • Cast a Ballot once. The database rejects a second Ballot on the same Poll, and the API responds with 409.
  • Biometric Gate. Sensitive Polls require Face ID or a fingerprint. The check runs entirely on the device: the server only verifies a challenge signed by the device's registered key, and no biometric data ever leaves the phone.
  • Live or Sealed Tally. Results are hidden until the Poll closes (Sealed, the default), or update live over WebSocket (Live). After voting you see the Tally as bar charts.
  • Create Polls. Voters can create their own Polls once they've earned enough Points by voting.

For Admins (web dashboard)

  • Moderation queue. Approve or reject Polls with a moderation note, and resolve Reports.
  • Participant management. Change roles and ban accounts.
  • Audit Log. Every Admin action is recorded in an append-only log.
  • Analytics dashboard, plus creating Polls directly from the dashboard.

How it looks

Mobile app

Landing screen: 'Raise your voice' with a microphone logo, a Sign Up button and a dark-mode toggle
Landing
Create Account sheet in dark mode with phone number (blurred), username and password fields
Sign up with a phone number
Poll feed titled 'For John' showing a Poll card by @admin, 'Should public transportation be made free in major cities?', with an image and a Vote button
Feed: Poll cards
Sidebar over the feed with a Dark/Light toggle, Profile, Create Poll and Log Out
Sidebar and dark mode
Vote sheet listing three Options: Yes, No, and Undecided
Cast: pick an Option
After voting: 'Thanks for your vote' with Tally bars for each Option, kept at 0% because the Tally is Sealed
Voted: Tally Sealed until close
Create Poll form showing a balance of 0 points, a cost of 10 points, Sealed or Live Tally mode, and a disabled button reading 'Need 10 more points'
Create Poll: gated by Points
Dialog: 'Poll created! Your poll is pending review.'
New Polls wait for review

Admin dashboard

Admin dashboard stats: 7 total Participants, 1 pending Poll, 8 approved, 0 rejected, 5 total Ballots, 5 new Participants and 2 new Polls in the last 7 days
Dashboard: platform stats
Polls table with All, Pending, Approved and Rejected tabs, and an Approve poll dialog with an optional moderation note
Moderation: approve or reject with a note
Participants table with role dropdowns, points, status and Ban buttons, plus a Ban dialog asking for a reason
Participants: roles and bans
Audit Log table with timestamp, actor, action (participant_ban, participant_role_change, create_poll, cast_ballot, admin_create_poll) and entity
Audit Log: every action recorded

Screens from the Demo 1 video, which walks through sign-up, voting, creating a Poll, Admin moderation, and the approved Poll appearing in the feed. Phone numbers are blurred.

Security model

ThreatDefence
Voting twiceOne Ballot per Participant per Poll, enforced by a database constraint, not just app logic
Fake or bulk accountsPhone verification. Device Fingerprints are stored per Participant to spot many accounts on one device
Tampered BallotsEvery Ballot is signed server-side with a private key. Signatures can be verified later
Impersonation on sensitive PollsBiometric Gate: a challenge signed by a key held in the device's Secure Enclave or keystore, checked against the registered public key
Leaked personal dataParticipant Profile fields (name, date of birth, address, contact details) are encrypted in the app layer before they reach PostgreSQL
Credential theftPasswords are hashed with argon2. JWT access tokens plus refresh tokens kept in Redis. Tokens on the phone live in the keychain, never in AsyncStorage
Brute force on authRate limits on auth endpoints (@fastify/rate-limit), plus @fastify/helmet headers
Tracking voters by IPOnly a hash of the IP address is stored with a Ballot
Admin abuseEvery Admin action writes an Audit Log entry

Scrutiny, the fraud pipeline that checks every Cast, is being built in steps. Device Fingerprints, signature checks, IP hashing and auth rate limits are in place. Behavioral timing analysis is planned.

Architecture

flowchart LR
    M["Mobile app<br/>React Native 0.76"] -- "REST + JWT" --> B["Backend<br/>Fastify"]
    A["Admin dashboard<br/>React + Vite"] -- "REST + JWT (Admin)" --> B
    M <-- "Socket.IO<br/>Live Tally" --> B
    B --> P[("PostgreSQL 16<br/>Participants · Polls · Ballots<br/>Audit Log")]
    B --> R[("Redis 7<br/>OTP · refresh tokens<br/>Tally counters · pub/sub")]
    B --> T["Twilio<br/>SMS codes"]
    S["packages/shared<br/>Zod validators + types"] -.-> M & A & B
  • One source of validation. Every request schema is a Zod schema in packages/shared/validators, used by the mobile app, the admin app and the backend.
  • Layered backend. Routes → services → the db/ modules. Routes never talk to the database directly, and every query is parameterized.
  • Domain language. Code uses the terms defined in CONTEXT.md: Cast (not "vote"), Ballot, Tally (not "results"), Scrutiny, Participant. Hard-to-reverse decisions are recorded in docs/adr/.

API

AreaEndpoints
AuthPOST /auth/register · /auth/verify-phone · /auth/refresh · /auth/logout
PollsGET /polls · /polls/:id · /polls/:id/tally · POST /polls · POST /polls/:id/cast
ParticipantsGET /participants/me · PATCH /participants/me/profile · POST /participants/me/devices
Adminpolls (list, create, moderate, delete), participants (role, ban), reports (resolve), audit log, analytics, health

Roles

RoleCastCreate PollsModerateManage roles
Admin✓✓✓✓
Editorial✓✓✓
Organization✓✓own Polls
Voter✓with ≥ 10 Points

Getting started

Requirements

  • Node.js 20+ and pnpm 9+
  • Docker (PostgreSQL, Redis, pgAdmin, Redis Commander)
  • For the mobile app: Android Studio (Android) and/or Xcode (iOS)

Or open the repo in the dev container (.devcontainer/), which sets up the toolchain and the database services for you.

Install and start the services

git clone https://github.com/tarekFerdous/Voice.git
cd Voice
pnpm install
cp .env.example .env              # fill in the values (see below)
docker compose -f docker/docker-compose.yml up -d

Postgres runs the schema (docker/postgres/init.sql) and seed data on first start. pgAdmin is at http://localhost:5050.

Run

pnpm dev:backend                  # Fastify API with hot reload
pnpm dev:admin                    # admin dashboard (Vite)
pnpm --filter @voice/backend seed # optional: seed sample data

For the mobile app, start Metro and run it on a device or emulator:

cd apps/mobile
pnpm start
pnpm android                      # or: pnpm ios

A step-by-step Windows guide for running on a USB-connected Android phone (Metro on port 8082, adb reverse) is in docs/dev-workflow.md.

Environment

VariablePurpose
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DBDatabase
REDIS_URLRedis connection
JWT_SECRET / JWT_REFRESH_SECRETAccess and refresh token signing (openssl rand -hex 64)
PII_ENCRYPTION_KEYHex key for encrypting Participant Profile fields
BALLOT_SIGNING_PRIVATE_KEYPEM private key used to sign Ballots
SMS_PROVIDER_KEYSMS provider (Twilio) for phone verification codes
PGADMIN_EMAIL / PGADMIN_PASSWORDpgAdmin login
NODE_ENVdevelopment / production

PII_ENCRYPTION_KEY and BALLOT_SIGNING_PRIVATE_KEY are read by the backend but aren't in .env.example yet. Add them before starting the API.

Project layout

apps/
  mobile/        React Native app: screens, AuthSheet, VoteCard/VoteModal, Tally charts, keychain auth
  backend/       Fastify API: routes/, service/, db/, redis/, security/, socket/
  Admin/         React + Vite admin dashboard: polls, participants, reports, audit log, analytics
packages/
  shared/        Zod validators, shared types, constants
docker/          docker-compose (Postgres 16, Redis 7, pgAdmin, Redis Commander), schema + seed SQL
docs/            ADRs, dev workflow, agent docs
CONTEXT.md       domain glossary: read before writing code
CLAUDE.md        rules for contributors (human or AI)
WORKFLOW.md      feature workflow: grill → PRD → issues → TDD
.scratch/        local issue tracker (PRDs and issues as markdown)

Development

pnpm test          # all workspaces (Vitest for backend/admin, Jest for mobile)
pnpm lint
pnpm type-check
pnpm build
  • Test first. Write the failing test, then the code. Test behaviour through public interfaces, and mock only at system boundaries (HTTP, database, Redis).
  • Security-critical modules (Ballot signing, Scrutiny, auth) need 100% behaviour coverage.
  • Strict TypeScript everywhere, and no any.
  • New features follow WORKFLOW.md. PRDs and issues live in .scratch/.

Status

Early, active development. The backend API (including Points-gated Poll creation and Live Tally costs), the admin dashboard and the mobile auth, feed, voting and Tally flows are in place. Next up are Scrutiny's behavioral checks and filing Reports from the mobile app.

License

MIT © 2026 tarekFerdous