From 6ef4dc851beadac9fe729b2b450c0a884e08ea1e Mon Sep 17 00:00:00 2001 From: Alexis Bruneteau Date: Thu, 6 Nov 2025 17:51:25 +0100 Subject: [PATCH] docs: Fill out openspec/project.md with complete project details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- e-voting-system/openspec/project.md | 261 ++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 e-voting-system/openspec/project.md diff --git a/e-voting-system/openspec/project.md b/e-voting-system/openspec/project.md new file mode 100644 index 0000000..ba9f12e --- /dev/null +++ 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: `: ` + +**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 ` + +## 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`