CIA/e-voting-system/.claude/PROJECT_COMPLETE_OVERVIEW.md

E-Voting System - Complete Project Overview

📋 Project Summary

This is a secure e-voting system with post-quantum cryptography and blockchain integration. The system uses:

• Backend: FastAPI (Python) with blockchain and cryptographic operations
• Frontend: Next.js 14+ (React) with TypeScript
• Database: MySQL
• Blockchain: Proof-of-Authority (PoA) consensus with validator nodes
• Cryptography: Hybrid signatures (RSA-PSS + ML-DSA Dilithium) + Hybrid encryption (ML-KEM Kyber + ElGamal)

---

🏗️ Architecture

Deployment Models

• Single Node: All services in one docker-compose
• Multi-Node: Distributed validators with PoA consensus (docker-compose.multinode.yml)
• Development: Hot-reload setup with docker-compose.dev.yml

Core Components

1. Backend (/backend)

• Auth System: JWT-based authentication
• Cryptography: Post-quantum key generation & management
• Blockchain: Immutable vote recording with hash chain
• Database: Election, voter, vote, and blockchain storage
• Validators: PoA consensus network
• Services:
  • User registration & authentication
  • Election management
  • Vote submission & verification
  • Blockchain integrity checks

2. Frontend (/frontend)

• Dashboard: Main control center for voters and administrators
• Pages:
  • /dashboard - Main dashboard
  • /dashboard/blockchain - Blockchain viewer & verifier
  • /dashboard/results - Election results
  • /auth/login - Authentication
  • /auth/register - User registration
• Components: Blockchain visualizer, forms, data tables

3. Blockchain Module (/backend/blockchain.py)

• Vote storage with SHA-256 hash chain
• RSA-PSS signatures on blocks
• Tamper detection
• Candidate hash verification

4. Validator Network (/validator)

• Proof-of-Authority consensus
• Block validation
• State synchronization

---

🔐 Security Features

Cryptography

Signatures:
├─ RSA-PSS (Classical)
└─ ML-DSA-65 Dilithium (Post-Quantum) → FIPS 204

Encryption:
├─ ML-KEM-768 Kyber (Post-Quantum) → FIPS 203
└─ ElGamal (Classical)

Hashing:
└─ SHA-256 (Quantum-Resistant)

Blockchain Security

• Immutability: Each block linked to previous via SHA-256 hash
• Authentication: RSA-PSS signatures on each block
• Integrity: Hash verification chain
• Consensus: PoA validators ensure consistency

Data Protection

• JWT tokens for session management
• Password hashing
• Encrypted vote storage
• Database encryption ready

---

🚀 Startup Process

Normal Startup (Docker)

docker-compose up -d
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/docs
# Database: localhost:3306

Multi-Node (Blockchain Network)

docker-compose -f docker-compose.multinode.yml up -d
# Multiple validator nodes with PoA consensus
# Test election automatically created

---

🗂️ File Structure

e-voting-system/
├── backend/
│   ├── main.py                    # FastAPI app entry point
│   ├── auth.py                    # JWT authentication
│   ├── blockchain.py              # Blockchain implementation
│   ├── blockchain_elections.py    # Election-blockchain binding
│   ├── blockchain_client.py       # PoA validator client
│   ├── models.py                  # Database models
│   ├── schemas.py                 # Request/response schemas
│   ├── services.py                # Business logic
│   ├── config.py                  # Configuration
│   ├── database.py                # Database setup
│   ├── crypto/                    # Cryptographic operations
│   └── routes/
│       ├── auth.py                # Authentication endpoints
│       ├── elections.py           # Election endpoints
│       └── votes.py               # Vote & blockchain endpoints
│
├── frontend/
│   ├── app/
│   │   ├── page.tsx               # Home page
│   │   ├── auth/                  # Authentication pages
│   │   ├── dashboard/
│   │   │   ├── page.tsx          # Main dashboard
│   │   │   └── blockchain/
│   │   │       └── page.tsx      # Blockchain viewer
│   │   └── api/                   # API proxy routes
│   ├── components/
│   │   ├── blockchain-visualizer.tsx
│   │   ├── blockchain-viewer.tsx
│   │   └── ...
│   └── lib/
│       ├── api.ts                 # API client utilities
│       └── api-config.ts          # API configuration
│
├── validator/
│   ├── validator.py               # PoA validator logic
│   └── ...
│
├── docker/
│   ├── Dockerfile.backend
│   ├── Dockerfile.frontend
│   ├── Dockerfile.validator
│   ├── nginx.conf
│   └── init.sql
│
├── tests/
│   ├── test_blockchain.py
│   └── test_blockchain_election.py
│
├── docker-compose.yml             # Single node
├── docker-compose.dev.yml         # Development
├── docker-compose.multinode.yml   # PoA network
├── pyproject.toml                 # Python dependencies
├── pytest.ini                      # Test configuration
└── [Documentation files]
    ├── README.md
    ├── GETTING_STARTED.md
    ├── BLOCKCHAIN_FLOW.md
    ├── PHASE_3_INTEGRATION.md
    └── ...

---

🔄 Vote Flow

1. User Registration

User → Registration Form
  ├─ Username/Password
  ├─ Generate hybrid cryptographic keys (RSA + Dilithium + Kyber)
  └─ Store encrypted keys in database

2. User Authentication

User → Login Form
  ├─ Verify credentials
  └─ Issue JWT token

3. Vote Submission

Voter → Select candidate
  ├─ Encrypt vote (ML-KEM + ElGamal)
  ├─ Sign with hybrid signature (RSA-PSS + Dilithium)
  ├─ Submit to backend
  └─ Backend:
      ├─ Verify signature
      ├─ Record encrypted vote
      ├─ Create blockchain transaction
      ├─ Broadcast to PoA validators
      └─ Await consensus confirmation

4. Blockchain Recording

Vote Transaction → Create Block
  ├─ Hash previous block
  ├─ Include encrypted vote
  ├─ Include voter signature
  ├─ Sign block with RSA-PSS
  ├─ Chain to previous block
  └─ Store in all validator nodes

5. Results Verification

Admin/Observer → View Blockchain
  ├─ Request blockchain for election
  ├─ Verify chain integrity
  ├─ Check all block signatures
  ├─ Confirm vote count
  └─ Decrypt and display results

---

🧪 Testing

Run Unit Tests

pytest tests/ -v

Test Election Blockchain

python3 test_blockchain_election.py

Manual Testing

# Check API documentation
curl http://localhost:8000/docs

# Register user
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "password": "test123", "email": "test@example.com"}'

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "password": "test123"}'

# Get active elections
curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/elections/active

# Submit vote
curl -X POST http://localhost:8000/api/votes/submit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"election_id": 1, "candidate_id": 1}'

# Get blockchain
curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/votes/blockchain?election_id=1

# Verify blockchain
curl -X POST http://localhost:8000/api/votes/verify-blockchain \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"election_id": 1}'

---

📊 Database Schema

Key Tables

• users: User accounts with hybrid keys
• elections: Election metadata and status
• candidates: Candidates in each election
• votes: Encrypted vote records
• blockchain_blocks: Immutable vote records
• validators: PoA validator nodes
• admin_users: Administrator accounts

---

🌐 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout

Elections

• GET /api/elections/active - List active elections
• GET /api/elections/{id} - Get election details
• GET /api/elections/{id}/candidates - Get candidates

Voting

• POST /api/votes/submit - Submit encrypted vote
• GET /api/votes/blockchain - Get blockchain state
• POST /api/votes/verify-blockchain - Verify chain integrity
• GET /api/votes/results - Get election results

Admin

• POST /api/admin/elections - Create election
• PUT /api/admin/elections/{id} - Update election
• POST /api/admin/elections/{id}/activate - Activate election

---

🔧 Configuration

Environment Variables

# Backend
DATABASE_URL=mysql://user:pass@localhost/voting_db
JWT_SECRET=your-secret-key
BACKEND_URL=http://localhost:8000

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

# Validators
POA_VALIDATOR_COUNT=3
POA_CONSENSUS_THRESHOLD=2

---

📈 Recent Updates (Phase 3)

• ✅ Proof-of-Authority (PoA) consensus network
• ✅ Multi-validator blockchain synchronization
• ✅ Blockchain integrity verification
• ✅ Post-quantum cryptography (ML-DSA, ML-KEM)
• ✅ Hybrid encryption & signing
• ✅ Comprehensive logging system
• ✅ Docker multi-node deployment
• ✅ Blockchain visualizer UI component

---

🐛 Known Issues & Recent Fixes

Recently Fixed (Current Session)

1. ✅ truncateHash errors: Added null/undefined checks
2. ✅ Missing election_id in verify endpoint: Fixed NextJS proxy to pass body params as query string

In Progress

• Validator failover & recovery
• Performance optimization for large elections
• Audit logging

---

📚 Documentation Index

Document	Purpose
README.md	Project overview
GETTING_STARTED.md	Quick start guide
BLOCKCHAIN_FLOW.md	Detailed blockchain architecture
PHASE_3_INTEGRATION.md	PoA integration details
BLOCKCHAIN_ELECTION_INTEGRATION.md	Election-blockchain binding
POA_QUICK_REFERENCE.md	API reference
BLOCKCHAIN_DASHBOARD_FIX.md	Dashboard fixes (new)
BLOCKCHAIN_DASHBOARD_QUICK_FIX.md	Quick fix summary (new)

---

🎯 Next Steps to Try

1. Start the system:

   docker-compose up -d
   

2. Access the frontend:

   • Visit http://localhost:3000
   • Register a new account
   • Login

3. Create an election (admin only):

   • Use admin credentials
   • Create election with candidates

4. Vote:

   • Select an election
   • Vote for a candidate
   • Watch blockchain record it

5. Verify:

   • Go to blockchain dashboard
   • Click "Vérifier l'intégrité de la chaîne"
   • View blockchain integrity verification

---

🆘 Troubleshooting

Database connection issues

# Check MySQL container
docker ps | grep mysql

# View database logs
docker logs <mysql_container_id>

Validator consensus issues

# Check validator logs
docker logs <validator_container_id>

# Restart validators
docker-compose restart validator

Frontend API connection

# Check proxy is working
curl http://localhost:3000/api/elections/active

# Check backend is running
curl http://localhost:8000/docs

---

Last Updated: 2025-11-10
Version: 3.0 with PoA Blockchain
Status: Production-ready with post-quantum cryptography