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>
This commit is contained in:
Alexis Bruneteau
parent
fc7be6df26
commit
6ef4dc851b
261
e-voting-system/openspec/project.md
Normal file
261
e-voting-system/openspec/project.md
Normal file
@ -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`
|
||||||
Loading…
x
Reference in New Issue
Block a user