🗳️ BlockVote - Secure E-Voting System with Blockchain

A prototype e-voting system built with Next.js that implements blockchain concepts for secure, transparent, and tamper-proof voting.

📋 Project Overview

BlockVote is a comprehensive e-voting platform that combines modern web technologies with blockchain security principles. The system supports three distinct user roles and ensures vote integrity through cryptographic validation.

Current Status: Complete database implementation with Prisma ORM - ready for authentication development.

🎯 Key Features

Blockchain Security: Custom blockchain implementation with proof-of-work
Digital Signatures: Ed25519 cryptographic signatures for vote authenticity
Merkle Tree Validation: Efficient vote integrity verification
Role-Based Access: Admin, Organization, and Voter interfaces
Anti-Tampering: Hash injection and replay attack prevention
Transparent Results: Verifiable election outcomes

👥 User Roles

Role	Capabilities
Admin	System oversight, election monitoring, blockchain validation
Organization	Create elections, manage candidates, invite voters, view results
Voter	Receive credentials via email, cast votes securely

🚀 Current Status (75% Complete)

✅ Completed Features

🔐 Authentication System (100% Complete)

Unified Auth: Custom Prisma-based authentication
JWT Implementation: jose library for Edge Runtime compatibility
Secure Sessions: HttpOnly cookies and access/refresh token rotation
Role-Based Access: Middleware protection for Admin, Organization, and Voter roles
Email Verification: Nodemailer integration for account verification

🔗 Blockchain Infrastructure (100% Complete)

CryptoUtils: Double SHA-256, Ed25519 signatures, canonical serialization
MerkleTree: Vote integrity proofs and validation
Block: Mining, validation, vote storage
Blockchain: Chain validation, security threat detection
BlockchainManager: Multi-election blockchain support

🗄️ Database Layer (100% Complete)

Dual Support: Seamless switching between SQLite (local dev/test) and PostgreSQL (production)
Prisma ORM: Optimized schema with all relationships
Services: Complete CRUD operations for Users, Elections, Votes
Automated Seeding: Ready-to-use test data

🏗️ Project Foundation (100% Complete)

Next.js 15 with TypeScript
Tailwind CSS styling
Complete type definitions
Environment configuration
Zero build errors

🚧 Next Phase - User Interfaces

Admin dashboard refinement
Organization portal
Voter interaction flow
Real-time results visualization

🛠️ Technology Stack

Framework: Next.js 15 with TypeScript
Database: Prisma ORM with hybrid support:
- SQLite: Optimized for local development and testing (zero-config)
- PostgreSQL: Production-grade performance and scalability
Styling: Tailwind CSS
Authentication: Custom JWT (JOSE) + bcrypt + Nodemailer
Blockchain: Custom implementation with Node.js crypto
Email: Nodemailer
UI Components: Radix UI + Lucide React

📁 Project Structure

src/
├── app/                    # Next.js app router
│   ├── admin/             # Admin dashboard pages
│   ├── organization/      # Organization pages
│   ├── voter/            # Voter pages
│   ├── api/              # API routes
│   └── auth/             # Authentication pages
├── components/           # Reusable UI components
├── lib/                 # Core utilities
│   ├── blockchain/      # Blockchain implementation
│   │   ├── crypto-utils.ts    # Cryptographic functions
│   │   ├── merkle-tree.ts     # Vote integrity verification
│   │   ├── block.ts           # Blockchain blocks
│   │   └── blockchain.ts      # Main blockchain logic
│   ├── database/        # Prisma database services
│   │   ├── client.ts          # Database connection
│   │   ├── index.ts           # Service exports
│   │   └── services/          # CRUD operations
│   │       ├── user.service.ts
│   │       ├── election.service.ts
│   │       ├── vote.service.ts
│   │       └── blockchain.service.ts
│   ├── auth/           # Authentication utilities
│   └── email/          # Email service
├── types/              # TypeScript definitions
└── utils/              # General utilities
scripts/                # Development & testing scripts
└── test-blockchain.ts  # Blockchain functionality tests

🔐 Security Features

Blockchain Security

Double SHA-256: Prevents length extension attacks
Digital Signatures: Ed25519 for vote authenticity
Merkle Trees: Efficient vote integrity verification
Canonical Serialization: Prevents hash injection
Proof-of-Work: Light difficulty for block validation

Application Security

JWT Authentication: Stateless secure sessions
bcrypt Hashing: Secure password storage
Role-Based Access: Granular permission control
Input Validation: Comprehensive data sanitization
Audit Logging: Complete action tracking

🚀 Getting Started

Prerequisites

Node.js 18+
npm or yarn

Installation

Clone the repository

git clone https://github.com/mhdthariq/e-voting.git
cd e-voting

Install dependencies

npm install

Configure environment

cp env.example .env
# Edit .env with your configuration

Initialize database

npm run db:setup:dev  # Setup development database with test data

Start development server

npm run dev

Visit http://localhost:3000 to see the application.

Default Test Accounts (Development)

Admin: admin@blockvote.com / admin123!
Organization: org@blockvote.com / org123!
Voters: voter1@blockvote.com / voter123! (voter1-5)

(Automatically created with npm run db:seed)

📊 Development Roadmap

Phase 1: Foundation ✅ (Complete)

Next.js setup and configuration
Project structure and dependencies
Environment configuration

Phase 2: Database Layer ✅ (Complete)

✅ Prisma ORM with multi-environment support
✅ 11 comprehensive database tables
✅ 4 complete database services with CRUD operations
✅ Automated seeding with test data
✅ Production deployment scripts

Phase 3: Authentication 🚧 (Next Priority)

JWT token implementation
Login/logout functionality
Role-based middleware
Session management

Phase 4: Blockchain ✅ (Complete)

✅ Core blockchain classes
✅ Cryptographic security
✅ Vote validation and mining
✅ Multi-election blockchain management

Phase 5: User Interfaces ⏳ (Planned)

Admin dashboard
Organization management
Voter interface
Responsive design

Phase 6: Election Management ⏳ (Planned)

Election lifecycle
Candidate management
Vote processing
Results calculation

Phase 7: Email System ⏳ (Planned)

Voter credential distribution
Election notifications
Results delivery
Template system

Phase 8: Security & Testing ⏳ (Planned)

Penetration testing
Performance optimization
Security audit
Load testing

🧪 Testing

Blockchain Testing

# Test blockchain functionality
npm run test:blockchain

Database Testing

# Test database health
npm run db:health

# Seed test data
npm run db:seed

# Open database GUI
npm run db:studio

Development Commands

# Setup development environment
npm run db:setup:dev

# Reset database (development only)
npm run db:reset:dev

# Check build status
npm run build

📝 API Documentation (Coming Soon)

Authentication Endpoints

POST /api/auth/login - User login
POST /api/auth/logout - User logout
GET /api/auth/me - Get current user

Election Endpoints

GET /api/elections - List elections
POST /api/elections - Create election
PUT /api/elections/:id - Update election
DELETE /api/elections/:id - Delete election

Voting Endpoints

POST /api/votes - Cast vote
GET /api/results/:electionId - Get results

🔍 Blockchain Verification

The system provides multiple ways to verify blockchain integrity:

Hash Validation: Each block hash is cryptographically verified
Signature Verification: All votes are digitally signed
Merkle Proof: Individual vote integrity can be proven
Chain Validation: Complete blockchain integrity checking
Threat Detection: Automatic security threat identification

📧 Email Configuration

Configure email settings in .env:

EMAIL_SERVICE=gmail
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

🚀 Deployment

Production Build

npm run build
npm start

Environment Variables (Production)

Set strong JWT_SECRET
Configure production database
Set up email service credentials
Enable HTTPS
Configure domain settings

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

Development Guidelines

Follow TypeScript strict mode (pure TypeScript workflow)
Use ESLint and Prettier for code quality
Test blockchain functionality with npm run test:blockchain
Document security considerations thoroughly
Validate blockchain integrity before commits
Use proper TypeScript imports (no .js extensions)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

Documentation: View roadmap
Current Status: View status
Project Specification: View specs
TypeScript Setup: View guide

💡 Key Concepts

Blockchain vs Traditional Database

Immutability: Votes cannot be changed once recorded
Transparency: All votes are cryptographically verifiable
Decentralization: No single point of failure (in concept)
Consensus: Proof-of-work ensures valid blocks

Privacy Protection

Vote choices are encrypted and anonymous
Only vote counts are publicly visible
Voter identities are protected
Audit trails maintain integrity without revealing votes

🎯 Git Repository Status

Ready for Version Control

✅ Clean project structure with organized directories
✅ Pure TypeScript codebase (no mixed JS/TS files)
✅ Proper .gitignore configured
✅ Test data excluded from version control
✅ No build artifacts or temporary files
✅ Comprehensive documentation

What's Included

Source Code: Complete TypeScript implementation
Documentation: Project specs, roadmap, and setup guides
Configuration: Environment templates and TypeScript configs
Testing: Blockchain functionality tests
Dependencies: All required packages in package.json

What's Excluded (via .gitignore)

Generated Data: /data directory (blockchain test files)
Database Files: *.db, dev.db*, test.db* (generated locally)
Prisma Generated: /src/generated/, /prisma/migrations/
Build Artifacts: .next/, *.tsbuildinfo, /build
Dependencies: node_modules/
Environment: .env* files (use env.example as template)
System Files: .DS_Store, *.pem

For Contributors

Clone repository
npm install to install dependencies
npm run db:setup:dev to setup database with test data
npm run test:blockchain to verify blockchain functionality
npm run db:health to verify database connectivity
npm run dev to start development

The project is ready for collaborative development with a complete database foundation and zero build errors.

Available Test Data

After running npm run db:setup:dev, you'll have:

7 user accounts (1 admin, 1 organization, 5 voters)
1 sample election with 3 candidates
All database tables populated and ready for testing

Built with ❤️ for secure, transparent democracy

Last Updated: October 2025 Database Implementation: Complete ✅ Next Phase: Authentication System

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.husky		.husky
docs		docs
prisma		prisma
public		public
scripts		scripts
src		src
.gitignore		.gitignore
API_INTEGRATION.md		API_INTEGRATION.md
API_SECURITY.md		API_SECURITY.md
APPLY_SECURITY_GUIDE.md		APPLY_SECURITY_GUIDE.md
CHANGELOG_UPCOMING_ELECTIONS.md		CHANGELOG_UPCOMING_ELECTIONS.md
COMPLETED_TASKS.md		COMPLETED_TASKS.md
DATABASE.md		DATABASE.md
DEVELOPMENT_ROADMAP.md		DEVELOPMENT_ROADMAP.md
FIX_ELIGIBLE_VOTERS_COUNT.md		FIX_ELIGIBLE_VOTERS_COUNT.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
ORGANIZATION_ELECTION_STATS_FEATURES.md		ORGANIZATION_ELECTION_STATS_FEATURES.md
PHASE_6_COMPLETE.md		PHASE_6_COMPLETE.md
ProjectDocument.md		ProjectDocument.md
README.md		README.md
SECURITY_SUMMARY.md		SECURITY_SUMMARY.md
SETUP_GUIDE.md		SETUP_GUIDE.md
TYPESCRIPT_SETUP.md		TYPESCRIPT_SETUP.md
UPCOMING_ELECTIONS_FEATURE.md		UPCOMING_ELECTIONS_FEATURE.md
check_admin.ts		check_admin.ts
env.example		env.example
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
jest.setup.ts		jest.setup.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

mhdthariq/e-voting

Folders and files

Latest commit

History

Repository files navigation