OneMan-OneVote — Secure QR Voter Verification

A secure, transaction-based voter identification + booth verification system designed to enforce one-person-one-vote using QR identity tokens.

This repo is split into:

• backend/: Bun + Express + PostgreSQL (Drizzle ORM) API
• frontend/: React + Vite UI (QR generation + booth scanner)

What it does

Flow

1. Registration / Identity issuance: the system creates a voter record and issues a unique QR token.
2. Booth verification: a polling-booth UI scans the QR code and submits the token for verification.
3. Atomic update (transactional): verification is all-or-nothing so a voter can’t be partially verified.
4. Double-vote prevention: once a token/voter is verified, subsequent attempts are rejected.
5. Auditability: verification attempts (success/failure) are recorded for traceability.

Security properties (high level)

• Single-use verification (prevents double voting)
• Token validity periods / expiry
• Server-side validation using schema validation (Zod)

Tech stack

Backend

• Runtime: Bun
• API: Express
• DB/ORM: PostgreSQL + Drizzle
• Other: dotenv, cors, zod, firebase-admin

Frontend

• React + Vite
• QR:
  • react-qr-code (render QR)
  • html5-qrcode / react-qr-reader (scan QR)
• HTTP: axios
• Firebase client: firebase

Prerequisites

• Bun (recommended) or Node.js (Bun scripts are used in this repo)
• PostgreSQL running locally or remotely

Quick start (local dev)

1) Backend

cd backend
bun install

Configure environment

Create a backend/.env (or update the existing one) and set:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/voting_db

Note: an .env.example is not currently included in the repo.

Run migrations

bun run generate
bun run migrate

Start the API

bun run dev

The backend will start on the port defined in the backend source (see backend/src/index.ts).

2) Frontend

cd frontend
bun install
bun dev

Open:

• App: http://localhost:5173

How to use / demo

1. Open the frontend at http://localhost:5173.
2. Click Generate Demo Identity to create a voter + QR token (stored in the database).
3. Open the booth screen at http://localhost:5173/booth.
4. Scan the QR code with a webcam (or copy/paste the token if the UI supports manual entry).

Expected behavior:

• First scan → ✅ Verified
• Second scan → ❌ Denied (already verified)

Project structure

.
├── backend/
│   ├── package.json
│   └── src/
├── frontend/
│   ├── package.json
│   └── src/
└── README.md

Scripts

Backend (backend/package.json)

• bun run dev — start dev server (watch mode)
• bun run start — start server
• bun run generate — generate Drizzle migrations
• bun run migrate — run migrations

Frontend (frontend/package.json)

• bun dev — start Vite dev server
• bun run build — typecheck + build
• bun run preview — preview production build

Notes / next improvements

• Add .env.example files for backend + frontend.
• Document API endpoints and expected request/response payloads.
• Add Docker Compose for Postgres + app services for one-command local setup.

---

If you changed the “full system” recently (new routes, new DB schema, auth model, or new deployment steps), tell me what changed and I’ll revise this README to match it precisely.