Blockchain Voting App

A decentralized, transparent, and secure voting application built on blockchain technology to ensure election integrity, voter privacy, and democratic transparency.

Table of Contents

• Problem Statement
• Project Overview
• Features
• Tech Stack
• Installation
• Environment Variables
• Running Locally
• Folder Structure
• API Endpoints
• Deployment
• Screenshots
• Contributing
• License

---

Problem Statement

Traditional voting systems face critical challenges:

• Centralized Data: Election results are vulnerable to manipulation at a single point of authority
• Lack of Transparency: Voters cannot independently verify their vote was counted correctly
• Trust Deficit: Citizens must rely entirely on government institutions without cryptographic proof
• Auditability Issues: No immutable record of voting transactions for audits or recounts
• Privacy Concerns: Identity and vote linkage creates security risks

How This System Improves Election Integrity

Blockchain Voting App addresses these challenges through:

1. Immutable Records: Every vote is recorded as a cryptographic block on a distributed ledger. Once added, votes cannot be altered or deleted without leaving evidence.

2. Decentralized Verification: County nodes maintain independent copies of the blockchain. No single authority can change results—all nodes must agree.

3. End-to-End Verifiability: Voters receive a transaction hash to verify their vote was counted correctly without revealing who they voted for.

4. Cryptographic Security: Voter identity is hashed (never stored on-chain). Votes are encrypted and mathematically secure.

5. Transparent Audit Trail: Complete voting history is publicly accessible via the blockchain explorer for independent audits.

6. Reduced Election Fraud: The distributed nature and cryptographic foundations make it computationally infeasible to commit fraud at scale.

---

Project Overview

Blockchain Voting App is a web-based application that enables secure voting across multiple electoral positions in a single session. Built with scalability and security in mind, it implements blockchain consensus mechanisms to create an verifiable and transparent election system.

Key Capabilities:

• Register voters with biometric ID verification
• Cast ballots for 6 elective positions simultaneously
• Auto-mine votes into blockchain blocks
• Real-time results aggregation across 47 counties
• Independent vote verification using transaction hashes

---

Features

✅ Voter Authentication

• National ID (Huduma Namba) verification
• Identity hashing (never stored on-chain)
• County and constituency-level registration

✅ Secure Voting

• Vote for 6 positions: President, Senator, Women Rep, Governor, MP, MCA
• Encrypted ballot storage
• Draft ballot auto-save functionality

✅ Blockchain Integration

• Automatic block mining after vote submission
• Distributed ledger with county node consensus
• Cryptographic hash verification

✅ Transparency & Verification

• Live results dashboard by position and county
• Blockchain explorer for transaction verification
• Vote receipt with transaction hash

✅ Privacy Protection

• Voter identity never linked to vote on-chain
• Cryptographic vote encryption
• Anonymous vote verification

✅ Accessibility

• ARIA labels and semantic HTML
• Responsive design (desktop & mobile)
• Clear error messaging and validation

---

Tech Stack

Layer	Technology
Frontend	React 18, Vite
Styling	CSS3 (Grid, Flexbox, Animations)
State Management	React Hooks (useState, useCallback, useMemo)
Backend	Node.js + Express.js
Database	MongoDB
Authentication	JWT (JSON Web Tokens)
Cryptography	SHA-256 hashing
Storage	LocalStorage (client-side persistence)

---

Installation

Prerequisites

• Node.js 16.x or higher
• npm 8.x or higher
• MongoDB 5.x or higher (for backend)
• Git for version control

Clone Repository

git clone https://github.com/yourusername/blockchain-voting-app.git
cd blockchain-voting-app

Install Dependencies

# Install frontend dependencies
npm install

# Install backend dependencies (if backend is in separate folder)
cd backend
npm install
cd ..

---

Environment Variables

Frontend (.env)

Create a .env file in the root directory:

VITE_API_URL=http://localhost:5000
VITE_APP_NAME=Blockchain Voting App
VITE_ELECTION_YEAR=2027

Backend (.env)

Create a .env file in the backend directory:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/voting_app
JWT_SECRET=your_jwt_secret_key_here
NODE_ENV=development
CORS_ORIGIN=http://localhost:3000

Important: Never commit .env files to version control. Add to .gitignore:

.env
.env.local
.env.*.local

---

Running Locally

Start Frontend (React + Vite)

# From the root directory
npm run dev

The app will be available at http://localhost:5173

Start Backend (Node.js + Express)

# From the backend directory
cd backend
npm run dev

The API will be available at http://localhost:5000

Access the Application

1. Open http://localhost:5173 in your browser
2. Click "Cast Your Ballot" to begin voter registration
3. Enter your details (National ID, name, county, constituency, ward)
4. Vote for all 6 positions
5. Confirm and submit your ballot
6. Receive your transaction hash for future verification

---

Folder Structure

blockchain-voting-app/
├── public/                          # Static assets
│   ├── index.html
│   ├── manifest.json
│   └── robots.txt
│
├── src/
│   ├── components/                  # React components
│   │   ├── LandingPage.jsx         # Hero and overview
│   │   ├── RegistrationForm.jsx    # Voter verification
│   │   ├── BallotScreen.jsx        # Voting interface
│   │   ├── ConfirmBallot.jsx       # Review & confirmation
│   │   ├── Results.jsx             # Live results dashboard
│   │   ├── Receipt.jsx             # Vote confirmation
│   │   ├── BlockchainExplorer.jsx  # Transaction explorer
│   │   ├── Navigation.jsx          # Header navigation
│   │   ├── MiningOverlay.jsx       # Mining animation
│   │   └── index.js                # Exports all components
│   │
│   ├── utils/                      # Utility functions
│   │   ├── blockchain.js           # Block generation & hashing
│   │   ├── validation.js           # Form & data validation
│   │   ├── localStorage.js         # Persistent storage
│   │   └── index.js                # Utility exports
│   │
│   ├── App.js                      # Main app entry
│   ├── App-refactored.jsx          # Primary app component
│   ├── App.test.js                 # App tests
│   ├── index.js                    # React DOM render
│   ├── styles.css                  # Global styles
│   ├── App.css                     # App-specific styles
│   ├── index.css                   # Base styles
│   ├── constants.js                # Election data (candidates, positions)
│   └── setupTests.js               # Test configuration
│
├── backend/                        # Node.js backend (if separate)
│   ├── routes/
│   │   ├── auth.js                 # Authentication endpoints
│   │   ├── votes.js                # Vote submission
│   │   └── blockchain.js           # Blockchain endpoints
│   ├── models/
│   │   ├── Voter.js
│   │   ├── Vote.js
│   │   └── Block.js
│   ├── middleware/
│   │   ├── auth.js                 # JWT verification
│   │   └── validation.js           # Input validation
│   ├── server.js                   # Express app config
│   └── package.json
│
├── .gitignore
├── package.json                    # Frontend dependencies
├── vite.config.js                  # Vite configuration
├── README.md                        # This file
└── LICENSE

---

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/auth/register	Register voter with ID
POST	/api/auth/login	Authenticate and receive JWT
GET	/api/auth/verify	Verify current session

Voting

Method	Endpoint	Description
POST	/api/votes/submit	Submit encrypted ballot
GET	/api/votes/status/:txHash	Check vote status by transaction hash
GET	/api/votes/county/:countyId	Get vote count by county

Blockchain

Method	Endpoint	Description
GET	/api/blockchain/chain	Retrieve full blockchain
GET	/api/blockchain/block/:index	Get specific block
GET	/api/blockchain/verify/:txHash	Verify transaction
GET	/api/blockchain/stats	Blockchain statistics

Results

Method	Endpoint	Description
GET	/api/results/national	National vote counts
GET	/api/results/county/:countyId	County-level results
GET	/api/results/position/:positionId	Results by position

---

Deployment

Deploy Frontend (Vercel / Netlify)

Vercel:

npm install -g vercel
vercel

Netlify:

npm run build
# Upload 'dist' folder to Netlify

Environment Variables: Set VITE_API_URL to your production backend URL in deployment settings.

Deploy Backend (Heroku / Railway / Render)

Railway:

npm install -g @railway/cli
railway login
railway up

Render:

1. Connect GitHub repository
2. Set environment variables in Render dashboard
3. Auto-deploys on git push

Environment Variables on Production:

• MONGODB_URI: Production MongoDB connection string
• JWT_SECRET: Strong random secret (use openssl rand -base64 32)
• NODE_ENV: "production"
• CORS_ORIGIN: Frontend production URL

---

Screenshots

Landing Page

Shows hero section with features and CTA buttons.

[Screenshot placeholder - election overview]

Voter Registration

Secure identity verification form.

[Screenshot placeholder - registration form with 3-part name field]

Ballot Screen

Vote for all 6 elective positions.

[Screenshot placeholder - ballot voting interface]

Live Results

Real-time vote aggregation dashboard.

[Screenshot placeholder - results by position and county]

Blockchain Explorer

Verify transactions independently.

[Screenshot placeholder - blockchain transaction explorer]

---

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes with clear commit messages
4. Test thoroughly before submitting
5. Push to your fork: git push origin feature/your-feature-name
6. Open a Pull Request with a description of changes

Contribution Guidelines

• Follow existing code style (React hooks, functional components)
• Add tests for new features
• Update documentation if needed
• Keep commits atomic and descriptive
• No console errors or warnings

Reporting Issues

Found a bug? Open an issue with:

• Clear title and description
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if applicable

---

License

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

You are free to:

• Use commercially
• Modify the code
• Distribute copies

With the condition that you include the original license and copyright notice.

---

Support

For questions or support:

• Email: villeowan@gmail.com
• GitHub Discussions: Start a discussion

---