# 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.

**Key Goals:**
- Provide secure, verifiable electronic voting
- Ensure vote immutability via blockchain
- Support post-quantum cryptographic algorithms
- Enable transparent election results
- Maintain voter privacy and authentication

## 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
- **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`

### 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

### 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

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

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