# 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)
```bash
docker-compose up -d
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/docs
# Database: localhost:3306
```

### Multi-Node (Blockchain Network)
```bash
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
```bash
pytest tests/ -v
```

### Test Election Blockchain
```bash
python3 test_blockchain_election.py
```

### Manual Testing
```bash
# 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
```bash
# 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**:
   ```bash
   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
```bash
# Check MySQL container
docker ps | grep mysql

# View database logs
docker logs <mysql_container_id>
```

### Validator consensus issues
```bash
# Check validator logs
docker logs <validator_container_id>

# Restart validators
docker-compose restart validator
```

### Frontend API connection
```bash
# 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