docs: Add complete MVP specification and implementation plan

Added comprehensive MVP definition with:

Core Components:
- Paillier homomorphic encryption for vote secrecy
- Kyber (ML-KEM) for post-quantum key protection
- Dilithium (ML-DSA) for PQC signatures
- Blockchain module with immutable vote recording
- ZKP implementation for ballot validity

MVP Features:
1. Cryptographic toolkit (Paillier, Kyber, Dilithium, ZKP)
2. Blockchain module (linked blocks, signatures, validation)
3. Voting API (setup, public-keys, submit, blockchain, count)
4. Voter client (encryption, signing, submission)
5. Blockchain visualizer (display, verification)
6. Scrutator module (counting, results)

6-Phase Implementation Plan:
- Phase 1: Cryptographic foundations
- Phase 2: Backend API integration
- Phase 3: Frontend voting interface
- Phase 4: Blockchain visualization
- Phase 5: Results & reporting
- Phase 6: Testing & technical report

Security properties matrix with mechanisms.
Progress tracking checklist for all phases.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

e-voting-system/openspec/project.md

@@ -58,10 +58,106 @@ Conceive and implement a functional prototype of a secure electronic voting syst
 - **Development Server**: uvicorn (backend), Next.js dev (frontend)
 - **Production Build**: Next.js static export + Node.js server
 
+### Cryptography Libraries
+- **Paillier Homomorphic Encryption**: `python-paillier` - Vote encryption & homomorphic summation
+- **Kyber (ML-KEM)**: `liboqs-python` - Post-quantum key encapsulation
+- **Dilithium (ML-DSA)**: `liboqs-python` - Post-quantum digital signatures
+- **SHA-256**: Built-in hashlib - Blockchain hashing
+- **ZKP (Zero-Knowledge Proofs)**: Custom implementation - Ballot validity proofs
+
 ### Blockchain/Distributed Ledger
 - Vote records stored with ballot hashes
-- Immutable vote recording
+- Immutable vote recording via linked blocks
 - Transparent result verification
+- Chain integrity verification via SHA-256 hashing
+- Block signatures with Dilithium PQC
+
+## MVP (Minimum Viable Product) Features
+
+### Core Components
+
+**1. Cryptographic Toolkit (`backend/crypto_tools.py`)**
+- Paillier homomorphic encryption (key generation, encryption, decryption, homomorphic addition)
+- Kyber (ML-KEM) for post-quantum key encapsulation
+- Dilithium (ML-DSA) for post-quantum digital signatures
+- Simple Zero-Knowledge Proofs (prove ballot is 0 or 1 without revealing value)
+- SHA-256 for blockchain hashing
+
+**2. Blockchain Module (`backend/blockchain.py`)**
+- Block structure: index, previous hash, timestamp, encrypted votes, block hash, signature
+- Chain validation: verify hash chain integrity and block signatures
+- Ballot addition: add new encrypted votes to blockchain
+- Chain immutability: ensure votes cannot be altered
+
+**3. Voting API Endpoints (`backend/routes/votes.py`)**
+- `POST /api/votes/setup` - Initialize election (generate Paillier keys)
+- `GET /api/votes/public-keys` - Retrieve public keys for client encryption
+- `POST /api/votes/submit` - Submit encrypted ballot with signature
+- `GET /api/votes/blockchain` - Retrieve blockchain state
+- `GET /api/votes/count` - Homomorphic vote counting
+
+**4. Voter Client (`frontend/components/voting-interface.tsx`)**
+- Display election details and candidates
+- Client-side ballot encryption with Paillier
+- Generate simple ZKP for ballot validity
+- Sign ballot with voter's Dilithium key
+- Submit encrypted, signed ballot to blockchain
+- Display confirmation and vote receipt
+
+**5. Blockchain Visualizer (`frontend/app/dashboard/blockchain/page.tsx`)**
+- Display blockchain as linked blocks
+- Show: block index, previous hash, current hash, encrypted vote, signature
+- Chain integrity verification button
+- Visual representation of vote count progress
+
+**6. Scrutator Module (`backend/scripts/scrutator.py`)**
+- Access blockchain votes
+- Verify chain integrity and all signatures
+- Homomorphic summation: multiply all encrypted votes to get encrypted total
+- Decrypt result using Paillier private key (protected by Kyber)
+- Publish results with verification proofs
+
+### MVP Voting Process
+
+**Étape 1: Election Setup**
+- System generates Paillier keypair
+- System generates Kyber keypair for private key protection
+- System generates Dilithium keypair for block signing
+- Public keys published for voters
+
+**Étape 2: Voter Registration & Key Generation**
+- Voter authenticates via JWT
+- Voter generates personal Dilithium keypair
+- System stores public key for vote verification
+
+**Étape 3: Voter's Ballot Submission**
+1. Voter selects candidate (0 or 1)
+2. Frontend encrypts ballot: `E(v) = Paillier.encrypt(v, public_key)`
+3. Frontend generates ZKP: proof that `E(v)` is valid (0 or 1)
+4. Frontend signs: `Signature = Dilithium.sign(E(v) || ZKP, voter_private_key)`
+5. Frontend submits: `{voter_id, E(v), ZKP, Signature}` to API
+6. API verifies signature and ZKP
+7. API checks voter hasn't already voted (emission list)
+8. API adds to blockchain: `Block{index, prev_hash, timestamp, E(v), tx_id, block_signature}`
+9. API returns confirmation
+
+**Étape 4: Vote Counting (Scrutator)**
+1. Retrieve all blocks from blockchain
+2. Verify blockchain integrity (hash chain + all block signatures)
+3. Homomorphic operation: `E(total) = E(v1) × E(v2) × ... × E(vn)`
+4. Decrypt: `total = Paillier.decrypt(E(total), private_key)`
+5. Publish results
+
+### Security Properties Provided
+
+| Property | Mechanism | Implementation |
+|----------|-----------|-----------------|
+| **Vote Secrecy** | Paillier encryption | Votes encrypted before leaving client |
+| **Vote Integrity** | Blockchain + Dilithium signatures | Linked blocks + PQC signatures on blocks |
+| **Voter Authentication** | JWT tokens + Dilithium signatures | JWT for session, Dilithium for ballot auth |
+| **Anonymity** | Transaction ID instead of voter ID | Voter ID verified once, not stored with vote |
+| **Verifiability** | ZKP + blockchain verification | Client proves ballot validity, anyone verifies chain |
+| **Post-Quantum Ready** | Kyber + Dilithium | Protected against future quantum attacks |
 
 ## Project Conventions
 
@@ -312,3 +408,229 @@ docs: Add comprehensive project status document
 - Backend ReDoc: `GET /redoc`
 - Frontend: `http://localhost:3000`
 - Backend: `http://localhost:8000`
+
+## Implementation Plan
+
+### Phase 1: Cryptographic Foundations
+**Goal**: Build secure crypto toolkit for PQC-based voting
+
+**Tasks**:
+1. Create `backend/crypto_tools.py` with:
+   - Paillier homomorphic encryption (key generation, encrypt, decrypt, homomorphic ops)
+   - Kyber (ML-KEM) integration via liboqs-python
+   - Dilithium (ML-DSA) integration via liboqs-python
+   - Simple ZKP implementation (prove 0 or 1 without revealing)
+   - SHA-256 blockchain hashing utilities
+
+2. Create `backend/blockchain.py` with:
+   - Block class (index, prev_hash, timestamp, encrypted_votes, block_hash, signature)
+   - Blockchain class (chain management, validation, immutability)
+   - Hash verification and signature verification methods
+   - Homomorphic vote summation
+
+3. Update `requirements.txt`:
+   - `python-paillier`
+   - `liboqs-python`
+   - `pycryptodome` for additional crypto utilities
+
+**Deliverables**:
+- ✅ Functional crypto toolkit
+- ✅ Blockchain data structure
+- ✅ Unit tests for crypto operations
+
+---
+
+### Phase 2: Backend API Integration
+**Goal**: Implement secure voting endpoints
+
+**Tasks**:
+1. Update `backend/routes/votes.py`:
+   - `POST /api/votes/setup` - Initialize election, generate Paillier/Kyber/Dilithium keys
+   - `GET /api/votes/public-keys` - Return public keys for client encryption
+   - `POST /api/votes/register-voter` - Register voter, generate their Dilithium keys
+   - `POST /api/votes/submit` - Receive encrypted ballot, verify signature, add to blockchain
+   - `GET /api/votes/blockchain` - Return blockchain state for verification
+   - `GET /api/votes/results` - Run scrutator, return homomorphic count
+
+2. Update `backend/models.py`:
+   - Add Dilithium key storage for voters
+   - Add blockchain block storage
+   - Add vote submission tracking (emission list)
+
+3. Create `backend/scripts/scrutator.py`:
+   - Verify blockchain integrity
+   - Compute homomorphic sum
+   - Decrypt final results
+   - Generate verification report
+
+**Deliverables**:
+- ✅ Secure API endpoints
+- ✅ Blockchain persistence
+- ✅ Vote scrutiny module
+
+---
+
+### Phase 3: Frontend Voting Interface
+**Goal**: Build client-side secure voting experience
+
+**Tasks**:
+1. Create `frontend/components/voting-interface.tsx`:
+   - Display election details
+   - Fetch public keys from backend
+   - Client-side Paillier encryption
+   - Generate ballot validity ZKP
+   - Sign with voter's Dilithium key
+   - Submit encrypted ballot
+   - Show vote confirmation
+
+2. Create `frontend/lib/crypto-client.ts`:
+   - Paillier encryption operations
+   - Dilithium signature operations
+   - ZKP generation
+   - Ballot serialization
+
+3. Update `frontend/app/dashboard/votes/active/page.tsx`:
+   - Integrate voting interface
+   - Show election details
+   - Display vote submission form
+
+**Deliverables**:
+- ✅ Secure voting UI
+- ✅ Client-side crypto operations
+- ✅ Vote submission workflow
+
+---
+
+### Phase 4: Blockchain Visualization & Verification
+**Goal**: Display blockchain and enable verification
+
+**Tasks**:
+1. Create `frontend/app/dashboard/blockchain/page.tsx`:
+   - Fetch blockchain from API
+   - Display blocks as linked chain
+   - Show: index, prev_hash, current_hash, encrypted_vote, signature
+   - Display vote count progress
+   - Integrity verification button
+
+2. Create `frontend/components/blockchain-viewer.tsx`:
+   - Block display component
+   - Chain visualization
+   - Hash verification UI
+
+3. Create `frontend/lib/blockchain-verify.ts`:
+   - Verify hash chain locally
+   - Verify block signatures
+   - Display verification results
+
+**Deliverables**:
+- ✅ Blockchain visualization
+- ✅ Verification interface
+- ✅ Results display
+
+---
+
+### Phase 5: Results & Reporting
+**Goal**: Display counting results and verification proofs
+
+**Tasks**:
+1. Create `frontend/app/dashboard/votes/results/page.tsx`:
+   - Display final vote count
+   - Show homomorphic verification
+   - Display blockchain integrity report
+   - Show audit trail
+
+2. Update backend scrutator:
+   - Generate detailed results
+   - Create verification proofs
+   - Provide transparency report
+
+**Deliverables**:
+- ✅ Results display page
+- ✅ Verification proofs
+- ✅ Audit report
+
+---
+
+### Phase 6: Testing & Documentation
+**Goal**: Ensure security and create technical report
+
+**Tasks**:
+1. Create technical report document:
+   - Section 1: Introduction & Design Choices
+     - Motivation and e-voting challenges
+     - System architecture (client/server + blockchain)
+     - Technology justification
+     - Voting process walkthrough
+
+   - Section 2: Analysis & Cryptographic Application
+     - Explain Paillier homomorphic encryption
+     - Explain Kyber (ML-KEM) key encapsulation
+     - Explain Dilithium (ML-DSA) signatures
+     - Explain simple ZKP implementation
+     - Explain blockchain hashing
+     - How crypto tools guarantee properties
+
+   - Section 3: Security Properties & Threat Analysis
+     - Security properties provided
+     - Threat analysis and mitigation
+     - Resistance evaluation
+
+2. Add tests:
+   - Unit tests for crypto operations
+   - Integration tests for voting workflow
+   - Blockchain integrity tests
+
+3. Docker testing:
+   - Ensure full deployment via docker-compose
+   - Test all endpoints
+   - Verify blockchain functionality
+
+**Deliverables**:
+- ✅ Complete technical & scientific report
+- ✅ Test suite
+- ✅ Deployment documentation
+
+---
+
+## Development Progress Tracking
+
+### Phase 1: Cryptographic Foundations
+- [ ] Paillier toolkit implementation
+- [ ] Kyber integration
+- [ ] Dilithium integration
+- [ ] ZKP implementation
+- [ ] Blockchain module
+- [ ] Crypto tests
+
+### Phase 2: Backend API Integration
+- [ ] Voting endpoints
+- [ ] Database models
+- [ ] Blockchain persistence
+- [ ] Scrutator module
+- [ ] API tests
+
+### Phase 3: Frontend Voting Interface
+- [ ] Voting component
+- [ ] Crypto client library
+- [ ] Vote submission flow
+- [ ] Confirmation display
+
+### Phase 4: Blockchain Visualization
+- [ ] Blockchain viewer page
+- [ ] Block display component
+- [ ] Verification UI
+- [ ] Hash verification
+
+### Phase 5: Results & Reporting
+- [ ] Results page
+- [ ] Verification proofs
+- [ ] Audit report
+- [ ] Results display
+
+### Phase 6: Testing & Documentation
+- [ ] Technical report (Section 1)
+- [ ] Technical report (Section 2)
+- [ ] Technical report (Section 3)
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Docker verification