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
| Threat | Defence |
|---|---|
| Voting twice | One Ballot per Participant per Poll, enforced by a database constraint, not just app logic |
| Fake or bulk accounts | Phone verification. Device Fingerprints are stored per Participant to spot many accounts on one device |
| Tampered Ballots | Every Ballot is signed server-side with a private key. Signatures can be verified later |
| Impersonation on sensitive Polls | Biometric Gate: a challenge signed by a key held in the device's Secure Enclave or keystore, checked against the registered public key |
| Leaked personal data | Participant Profile fields (name, date of birth, address, contact details) are encrypted in the app layer before they reach PostgreSQL |
| Credential theft | Passwords 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 auth | Rate limits on auth endpoints (@fastify/rate-limit), plus @fastify/helmet headers |
| Tracking voters by IP | Only a hash of the IP address is stored with a Ballot |
| Admin abuse | Every 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 indocs/adr/.
API
| Area | Endpoints |
|---|---|
| Auth | POST /auth/register · /auth/verify-phone · /auth/refresh · /auth/logout |
| Polls | GET /polls · /polls/:id · /polls/:id/tally · POST /polls · POST /polls/:id/cast |
| Participants | GET /participants/me · PATCH /participants/me/profile · POST /participants/me/devices |
| Admin | polls (list, create, moderate, delete), participants (role, ban), reports (resolve), audit log, analytics, health |
Roles
| Role | Cast | Create Polls | Moderate | Manage 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
| Variable | Purpose |
|---|---|
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB | Database |
REDIS_URL | Redis connection |
JWT_SECRET / JWT_REFRESH_SECRET | Access and refresh token signing (openssl rand -hex 64) |
PII_ENCRYPTION_KEY | Hex key for encrypting Participant Profile fields |
BALLOT_SIGNING_PRIVATE_KEY | PEM private key used to sign Ballots |
SMS_PROVIDER_KEY | SMS provider (Twilio) for phone verification codes |
PGADMIN_EMAIL / PGADMIN_PASSWORD | pgAdmin login |
NODE_ENV | development / production |
PII_ENCRYPTION_KEYandBALLOT_SIGNING_PRIVATE_KEYare read by the backend but aren't in.env.exampleyet. 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
