E-Voting Developer 4b3da56c40 docs: Add comprehensive documentation (PROJECT_STRUCTURE, QUICK_START) and cleanup

- Remove old STATUS.md and STRUCTURE_NOTES.md
- Add detailed PROJECT_STRUCTURE.md with full architecture documentation
- Add QUICK_START.md with quick reference guide
- Documentation covers: project overview, file structure, database models, API routes, Docker setup, authentication flow, security, and deployment

2025-11-06 01:20:57 +01:00

8.4 KiB

Raw Blame History

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)

# Backend
cd backend
uvicorn main:app --reload

# Frontend (autre terminal)
cd frontend
npm start

Docker

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

Makefile

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`)

window.API_CONFIG = {
  API_BASE_URL: 'http://localhost:8000'
};

✅ Tests

# 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

Login/Register
Dashboard
JWT authentication
Docker deployment
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

8.4 KiB Raw Blame History