docs: Fill out openspec/project.md with complete project details

Documented: - Project purpose and goals (e-voting with blockchain) - Complete tech stack (Next.js, FastAPI, MySQL, Docker) - Code style conventions (TypeScript, Python, Git) - Architecture patterns (frontend, backend, API client) - Testing strategy and git workflow - Domain context (e-voting concepts, security model) - Important constraints (technical, security, regulatory) - External dependencies and key endpoints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-06 17:51:25 +01:00 · 2025-11-06 17:51:25 +01:00 · 6ef4dc851b
commit 6ef4dc851b
parent fc7be6df26
1 changed files with 261 additions and 0 deletions
--- a/e-voting-system/openspec/project.md
+++ b/e-voting-system/openspec/project.md
@ -0,0 +1,261 @@
+# 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`