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

# E-Voting System - Architecture & Structure

## 📋 Vue d'ensemble

Système de vote électronique sécurisé utilisant la **cryptographie post-quantique** et **le vote chiffré**.

**Stack technique:**
- **Backend:** Python FastAPI + SQLAlchemy + MariaDB
- **Frontend:** React 19 + React Router + Axios
- **Cryptographie:** ElGamal + Preuve Zero-Knowledge + PQC Hybrid
- **Déploiement:** Docker Compose

---

## 📁 Structure du projet

```
e-voting-system/
├── backend/                    # API FastAPI
│   ├── main.py                # Point d'entrée FastAPI
│   ├── config.py              # Configuration (DB, JWT, etc)
│   ├── database.py            # Setup SQLAlchemy
│   ├── models.py              # Tables SQLAlchemy (Voter, Election, Vote, Candidate)
│   ├── schemas.py             # Schémas Pydantic (validation)
│   ├── services.py            # Logique métier (VoterService, ElectionService, VoteService)
│   ├── auth.py                # JWT et hashing (bcrypt)
│   ├── dependencies.py        # Dépendances FastAPI
│   ├── crypto/                # Modules cryptographie
│   │   ├── encryption.py      # ElGamal encryption
│   │   ├── hashing.py         # Key derivation (PBKDF2, bcrypt)
│   │   ├── signatures.py      # Digital signatures
│   │   ├── zk_proofs.py       # Zero-Knowledge proofs
│   │   └── pqc_hybrid.py      # PQC Hybrid approach
│   ├── routes/                # Endpoints
│   │   ├── auth.py            # Login, Register, Profile
│   │   ├── elections.py       # Élections CRUD
│   │   └── votes.py           # Soumission/Récupération votes
│   └── scripts/
│       └── seed_db.py         # Script initialisation DB
│
├── frontend/                  # Application React
│   ├── public/
│   │   ├── index.html         # HTML root
│   │   └── config.js          # Config runtime (API_BASE_URL)
│   ├── src/
│   │   ├── App.js             # Routeur principal
│   │   ├── index.js           # Entry point React
│   │   ├── components/        # Composants réutilisables
│   │   │   ├── Header.jsx     # Navigation
│   │   │   ├── Footer.jsx     # Footer
│   │   │   ├── Alert.jsx      # Messages d'erreur/succès
│   │   │   ├── Modal.jsx      # Modals
│   │   │   ├── LoadingSpinner.jsx
│   │   │   └── VoteCard.jsx   # Carte candidat
│   │   ├── pages/             # Pages/routes
│   │   │   ├── LoginPage.js   # Page de connexion (FIXED)
│   │   │   ├── HomePage.jsx   # Accueil
│   │   │   ├── RegisterPage.jsx
│   │   │   ├── DashboardPage.js # Tableau de bord
│   │   │   ├── VotingPage.jsx # Page de vote
│   │   │   ├── ArchivesPage.jsx
│   │   │   └── ProfilePage.jsx
│   │   ├── config/
│   │   │   ├── api.js         # Configuration API endpoints
│   │   │   └── theme.js       # Thème UI
│   │   ├── hooks/
│   │   │   └── useApi.js      # Hook pour appels API
│   │   ├── styles/
│   │   │   ├── globals.css
│   │   │   └── components.css
│   │   └── utils/
│   │       └── api.js         # Utilitaires API
│   ├── package.json           # Dépendances npm
│   ├── build/                 # Compilation production
│   └── Dockerfile             # Containerisation
│
├── docker/
│   ├── Dockerfile.backend     # Image FastAPI
│   ├── Dockerfile.frontend    # Image React
│   └── init.sql               # Script init DB
│
├── docker-compose.yml         # Orchestration (mariadb + backend + frontend)
├── Makefile                   # Commandes utiles
├── README.md                  # Documentation principale
└── .claude/                   # Documentation développeur
    ├── PROJECT_STRUCTURE.md   # Ce fichier
    ├── DEPLOYMENT.md          # Guide déploiement
    └── POSTQUANTUM_CRYPTO.md  # Infos PQC
```

---

## 🔑 Composants clés

### Backend - Routes principales

#### `/api/auth/`
- **POST /register** → Créer compte votant
- **POST /login** → Authentification, retourne JWT
- **GET /profile** → Profil votant actuel

#### `/api/elections/`
- **GET /active** → Élection en cours
- **GET /completed** → Élections terminées
- **GET /active/results** → Résultats

#### `/api/votes/`
- **POST /** → Soumettre un vote chiffré
- **GET /history** → Historique votes votant

### Frontend - Pages principales

| Page | Route | Description |
|------|-------|-------------|
| **LoginPage.js** | `/login` | Connexion votant |
| **HomePage.jsx** | `/` | Accueil |
| **DashboardPage.js** | `/dashboard` | Elections actives |
| **VotingPage.jsx** | `/vote/:id` | Interface vote |
| **ArchivesPage.jsx** | `/archives` | Elections passées |

---

## 🔐 Flux d'authentification

```
1. Utilisateur → LoginPage.js
2. POST /api/auth/login (email + password)
3. Backend vérifie credentials (bcrypt.checkpw)
4. ✅ JWT token retourné
5. Token + voter data → localStorage
6. Redirection → /dashboard
```

### Important: LoginPage.js

**Corrigé le 5 nov 2025:**
- ✅ Utilise `API_ENDPOINTS.LOGIN` (au lieu de URL hardcodée)
- ✅ Prop correct: `onLogin` (au lieu de `onLoginSuccess`)
- ✅ Structure données correcte: `email`, `first_name`, `last_name`

---

## 🗄️ Modèles Base de données

### `voters`
```
id (PK)
email (UNIQUE)
password_hash (bcrypt)
first_name
last_name
citizen_id (UNIQUE)
public_key (ElGamal)
has_voted (bool)
created_at
updated_at
```

### `elections`
```
id (PK)
name
description
start_date
end_date
elgamal_p (nombre premier)
elgamal_g (générateur)
public_key (clé publique)
is_active (bool)
results_published (bool)
```

### `candidates`
```
id (PK)
election_id (FK)
name
description
order
```

### `votes`
```
id (PK)
voter_id (FK)
election_id (FK)
candidate_id (FK)
encrypted_vote (ElGamal ciphertext)
zero_knowledge_proof
ballot_hash
timestamp
ip_address
```

---

## 🐳 Docker Compose

3 services:

### `mariadb` (port 3306)
- Image: `mariadb:latest`
- Init script: `docker/init.sql`
- Volume: `evoting_data`

### `backend` (port 8000)
- Build: `docker/Dockerfile.backend`
- CMD: `uvicorn backend.main:app --host 0.0.0.0 --port 8000`
- Dépend de: `mariadb` (healthcheck)

### `frontend` (port 3000)
- Build: `docker/Dockerfile.frontend`
- CMD: `serve -s build -l 3000`
- Dépend de: `backend`

---

## 🚀 Démarrage

### Local (développement)
```bash
# Backend
cd backend
uvicorn main:app --reload

# Frontend (autre terminal)
cd frontend
npm start
```

### Docker
```bash
docker-compose up -d
# Frontend: http://localhost:3000
# Backend: http://localhost:8000
```

### Makefile
```bash
make up      # docker-compose up -d
make down    # docker-compose down
make logs    # docker-compose logs -f backend
make test    # pytest tests/ -v
```

---

## 🔒 Sécurité

### Authentification
- Passwords: **bcrypt** (salt + hash)
- Tokens: **JWT** (HS256, 30min expiration)

### Votes
- **Chiffrement:** ElGamal
- **Preuve:** Zero-Knowledge
- **Traçabilité:** ballot_hash

### Post-Quantum
- Hybride PQC/Classique pour transition future
- Module: `backend/crypto/pqc_hybrid.py`

---

## 📝 Variables d'environnement

### Backend (`.env`)
```
DB_HOST=mariadb
DB_PORT=3306
DB_NAME=evoting_db
DB_USER=evoting_user
DB_PASSWORD=evoting_pass123
SECRET_KEY=your-secret-key-change-in-production
DEBUG=false
```

### Frontend (`public/config.js`)
```javascript
window.API_CONFIG = {
  API_BASE_URL: 'http://localhost:8000'
};
```

---

## ✅ Tests

```bash
# Tous les tests
pytest tests/ -v

# Tests spécifiques
pytest tests/test_backend.py -v
pytest tests/test_crypto.py -v
pytest tests/test_pqc.py -v
```

---

## 🎯 Statut (5 nov 2025)

✅ **Système fonctionnel**
- [x] Login/Register
- [x] Dashboard
- [x] JWT authentication
- [x] Docker deployment
- [x] API endpoints
- [ ] Vote submission (en cours)
- [ ] Results display (planifié)

---

## 📚 Références

- **FastAPI:** https://fastapi.tiangolo.com/
- **React Router:** https://reactrouter.com/
- **SQLAlchemy:** https://www.sqlalchemy.org/
- **ElGamal:** Crypto asymétrique probabiliste
- **Zero-Knowledge Proofs:** Preuve sans révéler info

---

**Dernière mise à jour:** 5 novembre 2025