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.

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