🗳️ VoteSafe: Enterprise Biometric Voting Architecture

A highly-secure, full-stack biometric election platform utilizing UIDAI-grade standards.

💻 Explore Portfolio • 🐛 Report Bug • 💡 Request Feature

🚧 Work-in-progress: Upgraded from an Arduino-based R307 prototype to Indian Government UIDAI-standard Mantra MFS110 fingerprint devices for improved accuracy, enterprise reliability, and scalable real-world application.

---

📑 Table of Contents

• 🎯 Core Objective
• 🏛️ System Architecture
• 🔐 Cryptographic Security Flow
• ⚡ Feature Matrix
• 🔄 System Evolution
• 🛠️ Tech Stack
• 📂 Project Topology
• 🚀 Quick Start Guide

---

🎯 Core Objective

To design and deploy a secure, transparent, and duplicate-free digital voting infrastructure utilizing:

• Zero-Exposure Biometric Authentication: Integrating Mantra MFS110 fingerprint sensors—similar to UIDAI identity verification grids.
• Enterprise RBAC: Granular Role-Based Access Control for Election Commissioners, Presiding Officers, Candidates, and Citizens.
• Immutable Ledger Technology: Blockchain-inspired Merkle-tree algorithms using SHA-256 hashing to permanently seal vote records.
• Real-time Tactical Overview: A comprehensive Node.js-powered socket/polling interface for polling booth health and demographic analytics.

---

🏛️ System Architecture

graph TD
    classDef client fill:#1E293B,stroke:#3B82F6,stroke-width:2px,color:#fff
    classDef server fill:#0F172A,stroke:#10B981,stroke-width:2px,color:#fff
    classDef db fill:#334155,stroke:#F59E0B,stroke-width:2px,color:#fff
    classDef hardware fill:#475569,stroke:#EF4444,stroke-width:2px,color:#fff

    %% Frontend Layer
    subgraph "🛡️ Client Layer (React 19 + TypeScript)"
        VD[Voter Terminal]:::client
        AD[Admin/Staff Analytics Dashboard]:::client
    end

    %% Hardware Interface
    subgraph "🖐️ Biometric Edge Node"
        Mantra[Mantra MFS110 Scanner]:::hardware
        RDS[Local Windows RD Service SDK]:::hardware
        Mantra -.->|Optical Fingerprint Read| RDS
        RDS -->|Base64 Auth Template Payload| VD
    end

    %% API Layer
    subgraph "⚙️ Backend API Node (Node.js/Express)"
        Auth[JWT & RBAC Validation Firewall]:::server
        BioGuard[BioShield Cryptography Engine]:::server
        VoteLedger[Merkle-Tree Vote Committer]:::server
        VD & AD ===|Encrypted HTTPS API Calls| Auth
        Auth --> BioGuard
        Auth --> VoteLedger
    end

    %% Storage Layer
    subgraph "🗄️ ACID Persistence"
        PG[(PostgreSQL Matrix)]:::db
        BioGuard -->|AES-256-GCM Vault Data| PG
        VoteLedger -->|SHA-256 Chained Blocks| PG
    end

Loading

---

🔐 Cryptographic Security Flow

sequenceDiagram
    autonumber
    actor V as Voter
    participant R as React Client
    participant M as Mantra Scanner
    participant A as Express Router
    participant E as AES-256 Encryptor
    participant DB as PostgreSQL

    V->>R: Initiates Voting & Places Finger
    R->>M: HTTP Request to Local RD Service (Port 11100)
    Note over M: Hardware verification & biometric mapping
    M-->>R: Returns ISO 19794-2 Fingerprint Template Payload
    R->>A: POST /auth/biometric { template, EPIC_No }
    
    rect rgb(20, 25, 40)
        Note left of E: BioShield Secure Operations Area
        A->>E: Pass raw biometric string
        E->>E: Generate 16-byte cryptographically secure random IV
        E->>E: Execute AES-256-GCM symmetric encryption
        E->>E: Extract AuthTag (16-byte)
    end
    
    A->>DB: Query Voter Reference Data by EPIC
    DB-->>A: Returns Encrypted Template (IV:TAG:Ciphertext)
    A->>E: Decrypt Server Reference & Run 1:1 Fuzzy Match
    
    alt Match Valid & Unvoted
        A-->>R: 200 OK - Issue JWT Bearer Token
        R-->>V: Access Granted to Digital Ballot
    else Match Invalid / Duplicate
        A-->>R: 403 Forbidden / Trigger Database Fraud Alert
        R-->>V: Authentication Rejected. Connection terminated.
    end

Loading

---

⚡ Core Feature Matrix

Functional Module	Technical Implementation Details	Status	Technical Paradigm
Authentication Array	Two-Factor BioShield (Password + Fingerprint)	✅ Live	JWT, BCrypt, AES-256
RBAC Portal System	Separate routing for Admin, Candidates, Staff, Voter	✅ Live	React Router v7 Guards
Vote Ledger Integrity	Merkle-Tree Custom Chaining block algorithms	✅ Live	Cryptographic sha256 hashing
Biometric Intake	Integration with Mantra MFS110 RD software stack	🚧 WIP	Local Network Polling (XML/JSON)
Live Command Center	Real-Time array for tracking demographics and fraud	✅ Live	Recharts, Aggregation SQL
Security Auditing	Impersonation and network anomaly detection limits	✅ Live	SQL Triggers, Data Parsing
VVPAT Simulation	Digital interface triggering print logic for paper-trail	🚧 WIP	Web Print Dialog Hooks

---

🔄 System Evolution (Project Life-Cycle)

This project represents highly iterative software development, transitioning out of an experimental hardware state into a scalable digital application pattern.

Architecture Scope	Generation 1 (Legacy)	Generation 2 (Current Focus)
Computing Framework	Arduino / ESP8266 Microcontrollers	High-Concurrency Node.js V8 Engine
Biometric Hardware	R307 Optical Sensor (Low resolution)	Mantra MFS110 (UIDAI grade)
Code Paradigm	Procedural C++ / Flat PHP looping files	TypeScript, React.js 19, Strict Modules
Data Persistence	Flat files / Basic MySQL strings	PostgreSQL (ACID, Relational, Indexed)
Security Topology	Plaintext Serial Network Transmission	AES-256-GCM Vault Cryptography

"By leveraging UIDAI-standard hardware arrays, we mitigated the high False Acceptance Rates (FAR) inherent in hobbyist optical sensors. This overhaul allowed us to evolve the codebase into an Enterprise-ready structural pattern, drastically limiting vulnerability to replay attacks."

---

🛠️ Comprehensive Tech Stack

Operational Layer	Tooling & Infrastructure	Justification / Role
Frontend Framework	React 19 + TypeScript + Vite	Ensuring absolute type safety across complex asynchronous UI events.
Data Visualization	recharts + lucide-react	Real-time GPU-accelerated SVG metrics drawing for administrative dashboards.
Backend Engine	Node.js + Express	Managing non-blocking IO demands for multi-booth synchronization data drops.
Database System	PostgreSQL	Guaranteeing strict compliance with ACID rules necessary for financial/voting schemas.
Security Protocols	jsonwebtoken + native crypto	Handling zero-knowledge biometric template processing and tamper-evident logs.

---

📂 Project Topology

📦 VoteSafe-Biometric
 ┣ 📂 backend                 # The Node.js Core API Ecosystem
 ┃ ┣ 📂 src
 ┃ ┃ ┣ 📂 biometric         # Mantra Web Service Integration Logic
 ┃ ┃ ┣ 📂 middleware        # RBAC, Rate-limiting, JWT Guards
 ┃ ┃ ┣ 📂 routes            # Segmented RESTful API endpoints
 ┃ ┃ ┣ 📂 security          # AES-256-GCM Crypto Engines
 ┃ ┃ ┣ 📜 app.ts            # Express Initialization Mounts
 ┃ ┃ ┣ 📜 db.ts             # Connection Pooling
 ┃ ┃ ┗ 📜 schema.sql        # Database Relational Architecture
 ┃ ┗ 📜 verify_deployment.sh# System health checks
 ┣ 📂 components              # Reusable React UI Elements
 ┃ ┣ 📜 BiometricScanner.tsx# Frontend bridging to local RD Service
 ┃ ┗ 📜 Navbar.tsx
 ┣ 📂 docs                    # Official project reporting
 ┣ 📂 pages                   # Central Application Views
 ┃ ┣ 📜 Admin.tsx           # Fleet Command Control Interface
 ┃ ┣ 📜 CandidateDashboard.tsx
 ┃ ┣ 📜 Vote.tsx            # Secure Ballot Terminal
 ┃ ┗ ...
 ┣ 📜 App.tsx                 # Central Router Tree
 ┣ 📜 package.json
 ┣ 📜 types.ts                # App-wide strictly-typed data models
 ┗ 📜 run_app.command         # Quickstart MacOS executor

---

🚀 Quick Start Guide

Critical Prerequisites

• Node.js v18+
• PostgreSQL v14+ service active on port 5432.
• Mantra RD Service Layer must be installed and active (Listening on port 11100 typical) for full hardware emulation.

Environment Launch

1. Clone the Infrastructure:

   git clone https://github.com/RishvinReddy/Biometric-Voting-System.git
   cd Biometric-Voting-System

2. Synchronize Dependencies:

   npm install && cd backend && npm install

3. Vault Configuration: Create .env.local inside the root tree:

   DATABASE_URL=postgres://user:password@localhost:5432/votesafe
   JWT_SECRET=your_super_secret_key_min_32_chars
   Biometric_SECRET_KEY=exactly_32_character_secret_key!

4. Ignition & Seeding:

   npm run db:init  # Located within /backend

5. Run Development Services:

   # Spawns Express Server on :3001
   npm run dev:server 
   
   # Spawns Vite React Frontend on :5173
   npm run dev:client

---

Designed and Architected by Rishvin Reddy
Engineering Student | Full-Stack Architect
Built for educational, academic, and advanced simulation research purposes.