Online Voting System - Web Application

A secure, modern, government-grade digital voting platform built with Next.js, React, Express.js, and PostgreSQL. Enables eligible Indian citizens to participate in elections digitally with Aadhaar/PAN verification, face recognition (eKYC), and Voter ID validation.

🎯 Features

✅ Voter Features

• Multi-Level Identity Verification

  • Aadhaar OTP verification
  • PAN number validation
  • Face eKYC verification (liveness detection)
  • Voter ID validation

• Election Browsing

  • View eligible elections based on location
  • National, State, and Local elections
  • Real-time election status (Draft, Published, Active, Ended)
  • Filter by category

• Voting

  • Candidate selection with visual feedback
  • Vote confirmation dialog
  • Anonymous vote casting (vote not linked to voter)
  • Instant receipt generation

• Results

  • View election results with vote counts
  • Percentage calculations
  • Visual progress bars for easy comparison

✅ Admin Features

• Dashboard

  • Real-time statistics (total elections, voters, votes cast)
  • Pending verifications counter
  • Quick action buttons

• Election Management

  • Create new elections with location criteria
  • Edit election details
  • Manage election status (Draft → Published → Active → Ended)
  • Candidate management within elections
  • Support for National, State, and Local elections

• Voter Management

  • View all registered voters
  • Filter by verification status
  • Approve/reject voter registrations
  • Monitor verification progress

• Results Dashboard

  • View live voting results for all elections
  • Vote counts and percentages
  • Status tracking per election

🏗️ Architecture

Tech Stack

• Frontend: Next.js 14, React 18, TypeScript, Tailwind CSS
• State Management: Zustand (with persistence)
• Forms: React Hook Form + Zod validation
• Backend: Express.js, PostgreSQL, Redis
• Security: JWT, AES-256-GCM encryption, Rate limiting
• UI Components: Radix UI, Custom components

Project Structure

apps/
├── frontend/          # Next.js React frontend
│   ├── src/
│   │   ├── app/       # Pages and routes
│   │   ├── components/# React components
│   │   ├── store/     # Zustand state
│   │   └── lib/       # Utilities (API client, etc)
│   └── public/        # Static assets
└── backend/           # Express.js backend
    ├── src/
    │   ├── routes/    # API endpoints
    │   ├── lib/       # Business logic
    │   └── migrations/# Database migrations
    └── scripts/       # Utility scripts

🚀 Getting Started

Prerequisites

• Node.js >= 20.0.0
• PostgreSQL 12+
• Redis (for OTP storage and rate limiting)

Installation

1. Clone and Install Dependencies

cd /c/Users/A.Surya/Desktop/fakir
npm install

2. Setup Environment Variables

# Backend (.env in apps/backend/)
DATABASE_URL=postgresql://user:password@localhost:5432/voting_system
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-here
NODE_ENV=development

# Frontend (.env.local in apps/frontend/)
NEXT_PUBLIC_API_URL=http://localhost:4000/api/v1

3. Setup Database

# Navigate to backend directory
cd apps/backend

# Run migrations
npm run migrate

# Seed test data (optional)
npm run seed

4. Start Development Servers

Terminal 1 - Backend:

npm run dev:backend

Terminal 2 - Frontend:

npm run dev:frontend

The application will be available at:

• Frontend: http://localhost:3000
• Backend: http://localhost:4000

📱 Usage Flows

Voter Flow

1. Register → Provide name, email, mobile, DOB
2. Verify Aadhaar → Receive and confirm OTP
3. Verify PAN → Enter PAN number
4. Verify Face → Upload/capture face image
5. Verify Voter ID → Enter Voter ID
6. View Elections → Browse eligible elections
7. Cast Vote → Select candidate and confirm
8. View Results → See election results

Admin Flow

1. Create Election → Set title, dates, location criteria
2. Add Candidates → Add candidate details and photos
3. Publish Election → Move from Draft to Published
4. Monitor Results → Watch votes come in real-time
5. View Analytics → Check voter statistics and trends

🔐 Security Features

• Encryption: AES-256-GCM for PII and vote data
• Authentication: JWT with role-based access control
• Vote Anonymity: Vote records don't contain voter identifiers
• Rate Limiting: 100 requests/minute per IP
• Audit Logging: Complete audit trail of all actions
• One Vote Per Voter: Prevents duplicate voting
• Device Fingerprinting: Flags suspicious voting patterns

📊 Database Schema

Key Tables

• voters - Voter profiles with encrypted PII
• voter_verifications - 4-step verification status
• elections - Election events and scheduling
• candidates - Candidate master data
• election_candidates - Candidates in specific elections
• vote_records - Anonymous votes (no voter_id)
• vote_cast_status - One-vote-per-election enforcement
• audit_logs - Complete action history
• admin_users - Admin accounts

🎨 UI/UX

Design System

• Color Palette

  • Primary: Deep Blue (#1E3A8A)
  • Secondary: Indigo (#4F46E5)
  • Success: Emerald Green (#10B981)
  • Destructive: Red

• Animations

  • Smooth page transitions
  • Progress indicators
  • Loading spinners
  • Fade-in effects

• Responsive Design

  • Mobile-first approach
  • Tablet optimized
  • Desktop enhanced

🧪 Testing

Run Tests

# Backend unit tests
npm run test:backend

# Backend property-based tests
npm run test:pbt

# Frontend (coming soon)
npm run test:frontend

📚 API Documentation

Authentication Endpoints

• POST /api/v1/auth/register - Register new voter
• GET /api/v1/auth/me - Get current user

Verification Endpoints

• POST /api/v1/verify/aadhaar/initiate - Start Aadhaar OTP
• POST /api/v1/verify/aadhaar/confirm - Confirm Aadhaar OTP
• POST /api/v1/verify/pan - Verify PAN
• POST /api/v1/verify/face - Verify face
• POST /api/v1/verify/voter-id - Verify Voter ID

Election Endpoints

• GET /api/v1/elections - List eligible elections (voter)
• GET /api/v1/elections/:id - Get election details
• GET /api/v1/results/:id - Get election results

Admin Endpoints

• GET /api/v1/admin/dashboard/stats - Dashboard statistics
• POST /api/v1/admin/elections - Create election
• GET /api/v1/admin/elections - List all elections
• GET /api/v1/admin/voters - List all voters
• GET /api/v1/admin/results - Get all results

Voting Endpoints

• GET /api/v1/votes/eligibility/:electionId - Check voting eligibility
• POST /api/v1/votes/cast - Cast a vote

📝 Component Guide

Key Components

• RegisterForm - Voter registration with validation
• AadhaarVerificationForm - Aadhaar OTP flow
• PANVerificationForm - PAN validation
• FaceVerificationForm - Face image upload
• VoterIDVerificationForm - Voter ID validation
• VerificationProgress - 4-step progress indicator
• ErrorBoundary - Global error handling
• MainHeader - Role-based navigation

Utilities

• apiRequest - Typed API client with auth
• useAuthStore - Auth state management
• useToast - Toast notifications
• ErrorBoundary - Error boundary wrapper
• Skeletons - Loading state components

🔄 State Management

Zustand Store (Auth)

interface AuthState {
  token: string | null;
  user: AuthUser | null;
  setAuth: (token, user) => void;
  clearAuth: () => void;
  isAuthenticated: () => boolean;
}

🚨 Error Handling

• Form Validation: Real-time Zod validation
• API Errors: Typed error responses with retry logic
• Network Errors: Graceful error messages
• Error Boundary: Catches React component errors
• 404 Pages: Custom not-found page

📋 Pages Summary

Public Pages

• / - Home/landing page
• /register - Voter registration

Verification Pages

• /verify/aadhaar - Aadhaar OTP
• /verify/pan - PAN verification
• /verify/face - Face eKYC
• /verify/voter-id - Voter ID verification

Voter Pages

• /dashboard - Voter dashboard
• /elections - Browse elections
• /elections/[id] - Voting interface
• /elections/[id]/results - Election results

Admin Pages

• /admin/dashboard - Admin dashboard
• /admin/elections - Election management
• /admin/elections/new - Create election
• /admin/voters - Voter management
• /admin/results - Results dashboard

Error Pages

• /not-found - 404 page
• /loading - Loading state

🎓 Development Guide

Adding a New Route

1. Create page file in src/app/your-route/page.tsx
2. Use client components with 'use client' directive
3. Implement loading and error states
4. Add role-based access guards if needed

Adding a New Component

1. Create in src/components/your-component.tsx
2. Use TypeScript interfaces for props
3. Mark as 'use client' if using hooks
4. Include error handling and loading states

API Integration

import { apiRequest } from '@/lib/api';

const data = await apiRequest<ResponseType>('/endpoint', {
  method: 'POST',
  body: { /* data */ },
  requireAuth: true,
});

🐛 Troubleshooting

Port Already in Use

# Kill process on port 3000 (frontend)
lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Kill process on port 4000 (backend)
lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill -9

Database Connection Issues

# Check PostgreSQL is running
pg_isready -h localhost

# Check Redis is running
redis-cli ping

Build Failures

# Clear cache and rebuild
rm -rf .next apps/backend/dist
npm run build:frontend
npm run build:backend

📦 Production Deployment

Build Frontend

npm run build:frontend

Build Backend

npm run build:backend

Environment Configuration

Set all required environment variables:

• DATABASE_URL - PostgreSQL connection
• REDIS_URL - Redis connection
• JWT_SECRET - Secure secret key
• NEXT_PUBLIC_API_URL - Backend API URL
• NODE_ENV - Set to production

Health Checks

• Frontend: GET http://localhost:3000
• Backend: GET http://localhost:4000/api/v1/health

📞 Support & Documentation

• Backend API documentation available in /apps/backend/src/routes/
• Frontend component storybook (coming soon)
• Test files in *.test.ts files
• Requirements mapping in code comments

✨ Future Enhancements

• Real SMS/Email notifications
• Integration with real UIDAI Aadhaar API
• Integration with NSDL PAN API
• AWS Rekognition for advanced face verification
• Blockchain-based vote recording
• Multi-language support
• Progressive web app (PWA)
• Advanced reporting and analytics
• Biometric authentication
• QR code based voting

📄 License

Government of India - Election Commission of India

🙏 Acknowledgments

Built with modern security practices and government-grade standards for digital voting in India.

---

Version: 1.0.0
Last Updated: June 9, 2026
Status: Production Ready