BallotNXT is a biometric-enabled election management platform that combines a web-based administration portal with desktop hardware integration for secure voter verification. The system integrates fingerprint authentication, facial verification, and role-based access control to streamline election management workflows. It allows Polling Officers and Booth Level Officers to verify voters using a hybrid approach of traditional credentials, physical fingerprint scanning, and facial recognition.
• Biometric fingerprint authentication
• Face verification using WebRTC
• Custom Windows URI protocol integration (ballotnxt://)
• Role-Based Access Control (RBAC)
• Real-time WebSocket monitoring
• JWT Authentication.
- Multi-Role Dashboards: Distinct interfaces and restricted route access for Admins, Polling Officers (PO), Booth Level Officers (BLO), and standard Voters.
- Hardware Isolation Bypass: A custom URI protocol (
ballotnxt://) that allows the web application to securely trigger local desktop executables, capturing live fingerprint data without violating browser security sandboxes. - Hybrid Biometric Engine: Python-based backend that dynamically controls template extraction and matching to a Java-based SecuGen SDK.
- Facial Verification: WebRTC and Canvas-based frontend integration to verify voter identity via deep-learning facial mapping.
- Security Features: Implementation of
HttpOnlyJWT cookies, double-submit CSRF protection, IP-based rate limiting (Flask-Limiter), and Bcrypt password hashing. - Real-time Monitoring: WebSocket (SocketIO) integration to instantly alert administrators of failed or suspicious biometric login attempts.
| Component | Technology |
|---|---|
| Frontend | HTML5, CSS3, Vanilla JavaScript, WebRTC |
| Backend | Python 3.10+, Flask, WebSockets (Flask-SocketIO) |
| Database | SQLAlchemy (SQLite / MySQL) |
| Security | Flask-JWT-Extended, Flask-Bcrypt, Flask-Limiter |
| Biometric SDK | Java 19, SecuGen FDxSDKPro |
BallotNXT utilizes an Inter-Process Communication (IPC) architecture to solve the browser-to-hardware limitation:
- Initiation: An official inputs their ID on the web portal, generating a short-lived Transaction UUID.
- Trigger: The browser calls
ballotnxt://login?transaction_id=UUID, launching the local Windows scanner application. - Capture: The local app interfaces with the SecuGen scanner, extracts the fingerprint template, and POSTs it directly to the Flask backend.
- Matching: The Python backend spawns a Java SDK subprocess (
FingerprintMatcher.jar) to validate the template against the SQL database. - Resolution: The web frontend polls the server, detects the successful match, issues a secure JWT, and redirects to the dashboard.
BallotNXT/
├── app/ # Core Flask application
│ ├── routes/ # Blueprint controllers (admin, auth, voter, etc.)
│ ├── static/ # Vanilla JS, CSS, and UI assets
│ ├── templates/ # Jinja2 HTML views
│ ├── models.py # SQLAlchemy database schemas
│ └── decorators.py # Custom RBAC decorators
├── biometric_lib/ # SecuGen DLLs and JAR files
├── docs/ # Windows Registry and deployment guides
├── config.py # Environment configurations
├── run.py # WSGI entry point
└── seed.py # Database initialization and demo data
- Python 3.10+
- Java 19 Adoptium Eclipse (Required for the SecuGen Biometric Matcher)
- SecuGen Hamster U20 Pro & Device Drivers
# Clone the repository
git clone
cd BallotNXT
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment variables (see below)
cp .env.example .env
# Initialize the database with demo users
python seed.py
# Run the Flask server
python run.py
Create a .env file in the root directory:
JWT_SECRET_KEY=your_secure_random_string_here
# DB_USER=root
# DB_PASSWORD=your_db_password
# DB_HOST=localhost
# DB_NAME=ballotnxt
To enable the biometric scanner to communicate with the web app:
- Ensure the SecuGen
.dlland.jarfiles are placed in thebiometric_libdirectory. - Run the BallotNXT installer (or follow the guide in
docs/) to register theballotnxt://URI scheme in the Windows Registry.
- Admin / Official Login: Navigate to the login page. Select "Official Login" and enter an ECI ID (e.g.,
ADMIN001). This triggers the local biometric scanner for fingerprint authentication. - Voter Registration (PO): Authenticated Polling Officers can navigate to
/api/voters/add_newto register new voters, capturing their demographic details, facial encodings, and physical fingerprints. - Identity Verification (BLO): Booth Level Officers use the
/blo/verifyendpoint via WebRTC to validate voters against their registered facial profiles in real-time. - Voter Dashboard: Voters log in using standard credentials (EPIC ID + Password) to view their registration and voting status.
This project is intended for educational and academic purposes.
The secugen SDK used in this project is completely proprietary.