knowfoolery/requirements.md

# Know Foolery - Project Requirements

## Overview

Know Foolery is a quiz game inspired by the French game "Déconnaissance" (https://escaleajeux.fr/jeu/decon.0.1). It's a web-based quiz platform with plans for cross-platform expansion to mobile and desktop applications.

## Game Concept

### Core Gameplay
- **Objective**: Players answer randomly selected questions to score points
- **Question Format**: Each question belongs to a theme, displayed above the question
- **Scoring System**: 
  - 2 points for correct answer without hint
  - 1 point for correct answer with hint
  - 0 points for incorrect answer or timeout
- **Attempts**: Players have exactly 3 attempts per question
- **Time Limit**: Each game session is limited to 30 minutes maximum
- **Hints**: Players can request one hint per question, but this reduces their score

### Player Experience
- **Registration**: Players must enter their name before starting a game
- **Session Management**: Game tracks progress, attempts, and time remaining
- **Leaderboard**: Display top 10 scores accessible to all players
- **Themes**: Questions are categorized by themes (Geography, History, Science, etc.)

## System Requirements

### Functional Requirements

#### Player Features
1. **Game Session Management**
   - Start new game with player name registration
   - Track current question, attempts remaining, and score
   - Display timer with 30-minute session limit
   - Automatic session termination on timeout

2. **Question Interaction**
   - Display question with theme category
   - Accept text-based answers
   - Provide hint system (1 hint per question)
   - Validate answers server-side to prevent cheating

3. **Scoring and Leaderboard**
   - Real-time score calculation
   - Display top 10 scores with player names
   - Anonymous leaderboard (no personal data exposure)
   - Score persistence across sessions

#### Administrative Features
1. **Question Management**
   - CRUD operations for questions, themes, hints, and answers
   - Secure admin panel with OAuth authentication
   - Question categorization by themes
   - Bulk import/export capabilities

2. **User Management**
   - Admin role-based access control
   - Multi-factor authentication for admin access
   - Audit logging for all administrative actions

### Non-Functional Requirements

#### Performance
- **Response Time**: API responses under 200ms for 95% of requests
- **Concurrent Users**: Support for 1000+ simultaneous players
- **Database Performance**: Query response times under 100ms
- **Cross-Platform**: Consistent performance across web, mobile, and desktop

#### Security
- **Authentication**: OAuth 2.0/OIDC with Zitadel
- **Authorization**: Role-based access control (RBAC)
- **Data Protection**: Encryption at rest and in transit
- **Input Validation**: Comprehensive sanitization of all user inputs
- **Game Integrity**: Server-side validation to prevent cheating

#### Scalability
- **Microservices Architecture**: Independent scaling of components
- **Database**: PostgreSQL with read replicas for high availability
- **Caching**: Redis for session state and frequently accessed data
- **Auto-scaling**: Kubernetes-based horizontal scaling

#### Reliability
- **Uptime**: 99.9% availability target
- **Backup**: Automated daily backups with point-in-time recovery
- **Monitoring**: Comprehensive observability with alerting
- **Failover**: Automatic failover for critical components

## Technical Architecture

### Frontend Architecture
- **Web Application**: React with TypeScript
- **Mobile Applications**: React Native for iOS and Android
- **Desktop Applications**: Wails for macOS, Windows, and Linux
- **UI Framework**: Gluestack UI for consistent cross-platform design
- **Styling**: NativeWind/Tailwind CSS for utility-first styling

### Backend Architecture
- **Microservices**: Go-based services with clear domain boundaries
- **API Gateway**: Centralized routing, authentication, and rate limiting
- **Database ORM**: Ent for type-safe database operations
- **Communication**: gRPC for inter-service communication
- **External APIs**: Repository pattern for external integrations

### Microservices Design

#### Core Services
1. **Game Service**: Session management, scoring logic, attempts tracking
2. **Question Service**: CRUD operations for questions, themes, hints
3. **User Service**: Player registration and profile management
4. **Leaderboard Service**: Score calculations, rankings, statistics
5. **Session Service**: Timer management, session state persistence
6. **Admin Service**: Question management with OAuth protection
7. **Gateway Service**: API routing, authentication, rate limiting

#### External Services
1. **Zitadel**: Self-hosted OAuth 2.0/OIDC authentication
2. **PostgreSQL**: Primary database for application data
3. **Redis**: Session state and caching layer

### Database Design

#### Core Entities
- **Questions**: ID, theme, text, answer, hint, metadata
- **GameSessions**: ID, player_name, score, start_time, end_time, is_active
- **Users**: ID, name, created_at (minimal player data)
- **Leaderboard**: Aggregated scores and rankings
- **AuditLogs**: Admin actions and security events

#### Data Relationships
- Questions belong to themes
- GameSessions track multiple question attempts
- Leaderboard aggregates from GameSessions
- AuditLogs reference users and actions

## Security Requirements

### Authentication & Authorization
- **OAuth 2.0/OIDC**: Industry-standard authentication via Zitadel
- **JWT Tokens**: Secure token-based authentication with short expiration
- **MFA**: Multi-factor authentication required for admin accounts
- **Role-Based Access**: Granular permissions (player, admin roles)

### Data Security
- **Encryption**: AES-256 encryption for sensitive data at rest
- **TLS**: All communications encrypted in transit
- **Input Validation**: Comprehensive sanitization against XSS/injection
- **SQL Injection**: Prevention through parameterized queries (Ent)

### Application Security
- **Rate Limiting**: Per-user and global rate limits
- **CORS**: Strict cross-origin resource sharing policies
- **Security Headers**: CSP, HSTS, X-Frame-Options implementation
- **Audit Logging**: Comprehensive logging of security events

### Game Integrity
- **Server-Side Validation**: All game logic validated on backend
- **Anti-Cheating**: Session state verification and tampering detection
- **Score Validation**: Server-side score calculation and verification

## Compliance & Privacy

### Data Protection
- **GDPR Compliance**: Right to be forgotten, data portability
- **Data Minimization**: Collect only necessary player information
- **Anonymization**: Leaderboard data anonymized for privacy
- **Consent Management**: Clear privacy controls and consent

### Audit & Compliance
- **Audit Trails**: Comprehensive logging of all administrative actions
- **Compliance Reporting**: SOC 2, ISO 27001 compliance capabilities
- **Data Retention**: Defined policies for data lifecycle management

## Deployment & Infrastructure

### Development Environment
- **Local Development**: SQLite for rapid iteration
- **Docker Compose**: Containerized development environment
- **Testing**: Comprehensive unit, integration, and E2E testing

### Production Environment
- **Container Orchestration**: Kubernetes for production deployment
- **Database**: PostgreSQL with high availability configuration
- **Monitoring**: Prometheus, Grafana, Jaeger for observability
- **CI/CD**: GitHub Actions for automated testing and deployment

### Cross-Platform Deployment
- **Web**: Standard web application deployment
- **Mobile**: iOS App Store and Google Play Store distribution
- **Desktop**: Electron applications for major operating systems

## Quality Assurance

### Testing Strategy
- **Unit Testing**: Go testing framework + Jest for frontend
- **Integration Testing**: testcontainers for database testing
- **E2E Testing**: Playwright for complete user journeys
- **Performance Testing**: k6 for load and stress testing
- **Security Testing**: Automated security scanning and penetration testing

### Code Quality
- **Type Safety**: TypeScript for frontend, Go's type system for backend
- **Code Review**: Mandatory peer review for all changes
- **Static Analysis**: Automated code quality checks
- **Documentation**: Comprehensive API and component documentation

## Success Metrics

### User Engagement
- **Daily Active Users**: Track player engagement
- **Session Duration**: Average time spent playing
- **Question Accuracy**: Player success rates by theme
- **Hint Usage**: Frequency and effectiveness of hints

### Technical Performance
- **Response Times**: API and database performance metrics
- **Error Rates**: Application stability and reliability
- **Uptime**: System availability and reliability
- **Security Events**: Monitoring for security incidents

### Business Metrics
- **Player Retention**: User return rates and engagement
- **Content Quality**: Question difficulty and engagement
- **Platform Usage**: Cross-platform adoption rates
- **Admin Efficiency**: Content management effectiveness

## Future Roadmap

### Phase 1: Core Platform (Weeks 1-6)
- Basic web application with core game mechanics
- Essential microservices and database setup
- Admin panel for question management

### Phase 2: Enhanced Features (Weeks 7-12)
- Complete security implementation
- Comprehensive observability and monitoring
- Production-ready deployment

### Phase 3: Mobile Expansion (Weeks 13-18)
- React Native mobile applications
- Cross-platform component optimization
- Mobile app store deployment

### Phase 4: Advanced Features (Weeks 19-24)
- Desktop applications
- Advanced analytics and reporting
- Enhanced security and compliance features

This requirements document serves as the foundation for the Know Foolery quiz game development, ensuring all stakeholders understand the scope, technical approach, and quality standards for the project.