CIA/e-voting-system/openspec/project.md

# Project Context

## Purpose
E-Voting System - A secure electronic voting platform with blockchain-based vote recording, post-quantum cryptography, and real-time election management. Allows users to register, authenticate, and participate in elections through a web-based interface while ensuring vote integrity and transparency through distributed ledger technology.

**Project Definition (Cryptographie Industrielle Avancée):**
Conceive and implement a functional prototype of a secure electronic voting system emphasizing correct application of cryptographic principles to address specific challenges of online voting.

**Key Goals:**
- Provide secure, verifiable electronic voting
- Ensure vote immutability via blockchain
- Support post-quantum cryptographic algorithms (ML-KEM, ML-DSA)
- Enable transparent election results
- Maintain voter privacy and authentication
- Address e-voting challenges: fraud prevention, voter intimidation resistance, anonymity preservation
- Implement correct cryptographic mechanisms for vote security

**Deliverables (Per Project Requirements):**
1. **Complete Source Code & Environment:**
   - Full e-voting system source code
   - Independently deployable via Docker configuration
   - Implemented cryptographic security mechanisms
   - Ready for autonomous deployment

2. **Technical & Scientific Report:**
   - Architecture and design approach
   - Cryptographic tools explanation and principles
   - Security properties and threat analysis
   - Application of cryptography to voting system

## Tech Stack

### Frontend
- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript 5.3
- **Styling**: Tailwind CSS 3.3.6
- **UI Components**: shadcn/ui (custom components)
- **Forms**: React Hook Form 7.66.0
- **Validation**: Zod 4.1.12
- **Icons**: Lucide React
- **Environment**: Node.js 18+, npm

### Backend
- **Framework**: FastAPI (Python 3.12+)
- **Authentication**: JWT tokens (30-minute expiry)
- **Database**: MySQL 8.0+ / SQLite (dev)
- **ORM**: SQLAlchemy
- **Validation**: Pydantic
- **Cryptography**:
  - bcrypt for password hashing
  - Post-quantum algorithms (ML-KEM, ML-DSA)
  - Ballot hashing for vote verification
- **Middleware**: CORS enabled
- **Documentation**: Swagger UI & ReDoc

### Infrastructure
- **Containerization**: Docker & Docker Compose
- **Development Server**: uvicorn (backend), Next.js dev (frontend)
- **Production Build**: Next.js static export + Node.js server

### Blockchain/Distributed Ledger
- Vote records stored with ballot hashes
- Immutable vote recording
- Transparent result verification

## Project Conventions

### Code Style

**TypeScript/JavaScript:**
- Use TypeScript for all new code (no `any` types)
- Use arrow functions and const declarations
- Use camelCase for variables and functions
- Use PascalCase for component names and types
- Max line length: 100 characters
- Indent with 2 spaces
- Quote style: Double quotes for JSX, prefer template literals

**Python:**
- Follow PEP 8 naming conventions
- snake_case for functions and variables
- PascalCase for classes
- 4-space indentation
- Use type hints for all functions
- Docstrings for public functions/classes

**Git Formatting:**
- ESLint config: `.eslintrc.json` disables unescaped entities rule
- No Prettier config needed (uses Next.js defaults)

### Architecture Patterns

**Frontend Architecture:**
```
app/                    # Next.js App Router
├── page.tsx           # Route components
├── layout.tsx         # Route layouts
├── @modal/            # Optional slot routes
components/
├── ui/                # Reusable UI components (shadcn/ui)
└── protected-route.tsx # Authentication wrapper
lib/
├── api.ts             # API client with TypeScript types
├── auth-context.tsx   # Global auth state (React Context)
├── validation.ts      # Zod schemas for form validation
└── utils.ts           # Utility functions
```

**Authentication Flow:**
1. User submits form (login/register)
2. Frontend validates with Zod schema
3. API request with JSON payload
4. Backend validates and returns JWT token
5. Frontend stores token in localStorage
6. Token included in Authorization header for all subsequent requests
7. useAuth() hook provides user state across components

**API Client Pattern:**
- Centralized in `lib/api.ts`
- Grouped by resource: `authApi`, `electionsApi`, `votesApi`
- Returns `{ data?, error?, status }` structure
- Automatic token injection in headers
- Type-safe responses with TypeScript interfaces

**Protected Routes:**
- ProtectedRoute component wraps dashboard
- Checks useAuth() context before rendering
- Redirects to login if not authenticated
- Shows loading spinner during auth check

**Backend Architecture:**
```
backend/
├── main.py            # FastAPI app entry point
├── routes/            # Endpoint handlers
│   ├── auth.py       # Authentication endpoints
│   ├── elections.py   # Election management
│   └── votes.py       # Vote recording
├── models.py          # SQLAlchemy ORM models
├── schemas.py         # Pydantic request/response schemas
├── services.py        # Business logic
├── auth.py            # JWT and password utilities
├── database.py        # Database connection
└── crypto/            # Cryptographic utilities
```

### Testing Strategy

**Manual Testing (Current):**
- Test registration with form validation
- Test login/logout flow
- Test protected routes redirect
- Test election data loading
- Test form validation errors
- Test API error handling

**Future Testing:**
- **Unit Tests**: Jest for frontend components
- **E2E Tests**: Cypress for user workflows
- **Backend Tests**: pytest for API endpoints
- **Integration Tests**: Full stack with Docker

### Git Workflow

**Branching Strategy:**
- `paul/evoting` - Main development branch
- `UI` - Current frontend branch with Next.js rebuild
- `backup` - Old React CRA frontend (preserved)
- Feature branches off main development branch

**Commit Conventions:**
Format: `<type>: <subject>`

**Types:**
- `feat:` - New feature
- `fix:` - Bug fix
- `refactor:` - Code restructuring
- `docs:` - Documentation updates
- `chore:` - Dependencies, config changes
- `test:` - Test additions/updates

**Example:**
```
feat: Integrate backend API with frontend - Authentication & Elections
fix: Update Docker config for Next.js frontend
docs: Add comprehensive project status document
```

**Commit Messages:**
- Use imperative mood ("add" not "added")
- Keep subject under 50 characters
- Include context in body if needed
- Sign with: `🤖 Generated with Claude Code`
- Co-author: `Co-Authored-By: Claude <noreply@anthropic.com>`

## Domain Context

### E-Voting Concepts
- **Election**: A voting event with candidates and a deadline
- **Candidate**: Options users can vote for
- **Voter/User**: Authenticated user who can vote in elections
- **Vote**: Immutable record of voter choice (with ballot hash for verification)
- **Ballot Hash**: Cryptographic hash of vote details for verification without exposing vote

### Election States
- **Pending/Upcoming**: Not yet started, no voting allowed
- **Active**: Currently accepting votes
- **Completed**: Voting finished, results available

### Security Model
- User authentication via JWT tokens (30-minute expiry)
- Password hashing with bcrypt
- Post-quantum cryptography for future-proofing
- Vote recording with ballot hashes for transparency
- Vote immutability via blockchain/ledger
- No voter identification in vote records (privacy)

### French Language Convention
- All UI text in French
- Error messages: `Erreur`, validation messages, etc.
- Date format: DD/MM/YYYY

## Important Constraints

### Technical Requirements
- **Password Requirements**:
  - Minimum 8 characters
  - At least 1 uppercase letter
  - At least 1 digit
  - At least 1 special character (!@#$%^&*)
- **Token Expiry**: 30 minutes
- **Build Output**: Static pre-rendered pages + Node.js server
- **Database**: MySQL for production, SQLite for development
- **API URL**: Environment variable `NEXT_PUBLIC_API_URL`
- **Docker Deployment**: System must be deployable autonomously via Docker
- **Cryptographic Implementation**: All chosen cryptographic mechanisms must be implemented

### Security Properties & Design Challenges
**E-Voting Challenges to Address:**
- **Fraud Prevention**: Prevent vote tampering and false result reporting
- **Voter Intimidation Resistance**: Ensure no voter can prove how they voted
- **Anonymity Preservation**: Disconnect voter identity from vote content
- **Vote Integrity**: Guarantee votes cannot be altered after submission
- **Coercion Resistance**: System prevents voter coercion while voting
- **Universal Verifiability**: Anyone can verify election results are correct
- **Voter Verifiability**: Voter can verify their vote was recorded correctly

**Cryptographic Security:**
- **CORS**: Currently allow all origins (restrict to frontend domain in production)
- **HTTPS**: Required for production
- **HttpOnly Cookies**: Recommended instead of localStorage for production
- **Rate Limiting**: Should be implemented on auth endpoints in production
- **Audit Logging**: Should be added for compliance
- **Post-Quantum Ready**: Support ML-KEM and ML-DSA algorithms

### Business/Regulatory
- **Election Integrity**: Votes must be immutable once recorded
- **Voter Privacy**: Vote contents never tied to voter identity
- **Transparency**: Results and vote counts must be verifiable
- **Blockchain**: All votes stored with cryptographic verification
- **Compliance**: Consider GDPR and voting regulations
- **Audit Trail**: System must support accountability and verification

### Development
- No destructive git commands without explicit user confirmation
- Always commit before major changes
- Preserve working tree cleanly
- Test Docker builds before deployment

### Report Structure Requirements
**Technical & Scientific Report Must Include:**

1. **Introduction & Design Choices**
   - Motivation and context (e-voting challenges)
   - System architecture (client/server, blockchain-based, mixing servers)
   - Justification of technology choices (languages, frameworks, database)
   - Detailed voting process (registration to results publication)

2. **Analysis & Cryptographic Application**
   - Fundamental cryptographic tools explanation
   - Principles behind chosen algorithms
   - Application of cryptography to voting security
   - How tools guarantee chosen security properties

3. **Security Properties & Threat Analysis**
   - Voting security properties the system satisfies
   - Potential vulnerabilities evaluation
   - How design choices (especially cryptographic) address threats
   - Resistance to identified threats

## External Dependencies

### APIs/Services
- **Backend Database**: MySQL server (localhost:3306 in dev)
- **CORS-enabled**: Frontend communicates with backend via REST API

### Libraries/Packages
- **shadcn/ui**: Component library (via npm)
- **Radix UI**: Primitive components for shadcn/ui
- **FastAPI**: Built-in Swagger/ReDoc documentation
- **SQLAlchemy**: ORM for database abstraction

### Infrastructure
- **Docker Hub**: Alpine Linux images for containers
- **npm Registry**: Frontend dependencies
- **PyPI**: Python backend dependencies
- **MariaDB/MySQL**: Database provider

### Key Endpoints
- Backend Health: `GET /health`
- Backend Docs: `GET /docs` (Swagger)
- Backend ReDoc: `GET /redoc`
- Frontend: `http://localhost:3000`
- Backend: `http://localhost:8000`