knowfoolery/docs/3_guidelines/design-guidelines.md

# Know Foolery - Design Guidelines 

## Key Technical Orientations

### Go Service Structure
- Services use Fiber v3 framework with structured error handling
- Business logic separated into service layer with dependency injection
- Ent ORM with schema-first approach and proper indexing
- Custom middleware for JWT authentication and rate limiting
- Comprehensive testing with testcontainers for integration tests

### TypeScript/React Patterns
- Components use Gluestack UI with proper TypeScript typing
- Custom hooks pattern for business logic (e.g., `useGameSession`)
- Context + useReducer for state management
- Comprehensive testing with Jest + React Testing Library

### Authentication Flow
- Zitadel provides OAuth 2.0/OIDC authentication
- JWT tokens validated via shared auth middleware
- User context stored in Fiber locals for request handling
- Admin routes protected with role-based authorization

### Database Design
- Domain-driven design with clear aggregate boundaries
- Ent schemas with proper validation and indexes
- Transaction management for multi-step operations
- Separate read/write patterns for performance

### Security Considerations
- JWT token validation on all protected endpoints
- Rate limiting per user and IP address
- Input validation and sanitization
- CORS configuration for cross-origin requests
- SQL injection prevention with Ent ORM
- Secrets management via environment variables

## Application Design

### Core Services
1. **Game Service** (port 8080): Session management, scoring logic
2. **Question Service** (port 8081): CRUD operations for questions/themes  
3. **User Service** (port 8082): Player registration and profiles
4. **Leaderboard Service** (port 8083): Score calculations and rankings
5. **Session Service** (port 8084): Timer management, session state
6. **Admin Service** (port 8085): Question/user management with OAuth
7. **Gateway Service** (port 8086): API routing, authentication, rate limiting

### Detailes Microservices Design
1. **Game Session Service**: 
  - Responsibilities: Session management, pick next question (excluding already answered), scoring logic, attempts tracking, enforce timer, anti-cheat checks.
  - Scaling driver: concurrent players, realtime updates.
  - Interfaces:
    - Commands: 
      - POST /sessions/start          → Start new game session for a player (user)
      - POST /sessions/end            → End game session
      - POST /sessions/{id}/answer    → Submit answer
      - POST /sessions/{id}/hint      → Request hint
    - Queries
      - GET  /sessions/{id}           → Get session details, including status and timer
      - GET  /sessions/{id}/question  → Get the current question for the session
  - Domain driven design:
    - **Aggregates**: GameSession 
    - **Value Objects**: Attempt, Score 
    - **Domain Services**: Scoring
  - Storage: 
    - Core entities:
      - **Sessions**: id, id of user, score, start_time, end_time, is_active
      - **Session_Questions**: id, id of question
      - **Attempts**: id, id of Session_Questions, answer, score
    - Data relationships : Sessions track multiple question attempts for a user

2. **Question Bank Service**: 
  - Responsibilities: CRUD operations for questions, themes, hints, random selection API with filters (and “exclude these ids”).
  - Scaling driver: editorial ops, cacheable reads.
  - Interfaces:
    - Commands: 
      - POST /questions/random?theme=… with body {exclude:[ids]} → returns 1 random question    
    - Queries
      - GET  /questions/{id} → Get specific question
    - Admin: 
      - POST /admin/questions → Create question
      - PUT /admin/questions/{id} → Update question
      - DELETE /admin/questions/{id} → Delete question
      - GET /admin/themes → List available themes
      - GET /admin/themes/{id}/questions → List all questions for a theme
      - POST /admin/questions/bulk → Bulk question import
  - Domain driven design:
    - **Aggregates**: Theme, Question
    - **Value Objects**: Hint, Answer
  - Storage: 
    - Core entities:
      - **Themes**: id, theme, metadata
      - **Questions**: id, theme_fk, text, answer, hint, difficulty, metadata
    - Data relationships : Questions belong to themes
  - Notes: easily cache popular themes; can be read-replicated/CDN’ed if needed.
  
3. **Leaderboard Service**: 
  - Responsibilities: compute top-10, success rate, keep historical scores, player statistics.
  - Scaling driver: heavy reads; write via events from Session svc.
  - Interfaces:
    - Queries
      - GET /leaderboard/top10 → Get top 10 scores
      - GET /leaderboard/players/{id} → Get player ranking and history
      - GET /leaderboard/stats → Get game statistics
    - Commands
      - POST /leaderboard/update → Update scores (internal)
  - Storage: 
    - Core entities:
      - **Scores**: session_id, player, points, duration, questions_answered, correct_count, created_at 
      - **Leaderboard**: Aggregated scores and rankings (top10 materialized view/cache)
    - Data relationships : Leaderboard aggregates from GameSessions
  - Notes: can be eventually consistent (seconds). Cache responses (Redis) with short TTL.
4. **User Service**: Player registration and profile management
  - Responsibilities: Identity & Accounts management including email verification, Consent & Compliance (GDPR)
  - Scaling driver: registration bursts (marketing campaigns), auth traffic
  - Interfaces:
    - Queries
      - GET    /users/{id}            → Get user profile (restricted to the user)
    - Commands
      - POST /users/register → Register new player
      - POST /users/verify-email
      - PUT  /users/{id}            → Update profile
    - Admin
      - GET /admin/users?email=… → Get user profile (PII; protected)
      - GET /admin/users → List all users (admin)
      - POST /admin/users/{id}/block|unblock|delete
      - POST /admin/users/{id}/resend-verification
      - POST /admin/users/{id}/export → enqueues GDPR export job
      - POST /admin/users/{id}/erase → soft-delete + downstream purge events
      - DELETE /users/{id}            → Delete account (GDPR)
  - Domain driven design:
    - **Aggregates**: User
  - Storage: 
    - Core entities:
      - **Users**: ID, name, display_name, created_at, updated_at, deleted_at
      - **user_contact**: email unique, email_verified_at 
      - **user_consent**: marketing_email bool, consent_at, email_token (token unique), purpose (verify|login|change_email), expires_at, used_at
5. **Admin Service**: 
  - Responsibilities: Admin authentication, dashboard, audit logs access
  - Interfaces:
    - Commands
      - POST /admin/auth → Admin authentication
    - Admin
      - GET /admin/dashboard → Dashboard data
      - GET /admin/audit → Audit logs
  - Storage: 
    - Core entities:
      - **AuditLogs**: Admin actions and security events. Security events reference users and actions
6. **Gateway Service**: 
  - Responsibilities: API routing, authentication, rate limiting

### gRPC Service Definitions
```protobuf
// game_service.proto
service GameService {
  rpc StartGame(StartGameRequest) returns (StartGameResponse);
  rpc SubmitAnswer(SubmitAnswerRequest) returns (SubmitAnswerResponse);
  rpc GetSession(GetSessionRequest) returns (GetSessionResponse);
  rpc EndGame(EndGameRequest) returns (EndGameResponse);
}

// question_service.proto
service QuestionService {
  rpc GetRandomQuestion(RandomQuestionRequest) returns (Question);
  rpc ValidateAnswer(ValidateAnswerRequest) returns (ValidationResponse);
  rpc GetQuestionHint(HintRequest) returns (HintResponse);
}

// leaderboard_service.proto
service LeaderboardService {
  rpc UpdateScore(UpdateScoreRequest) returns (UpdateScoreResponse);
  rpc GetTopScores(TopScoresRequest) returns (TopScoresResponse);
  rpc GetPlayerRank(PlayerRankRequest) returns (PlayerRankResponse);
}
```

## Testing Strategy

### Backend Testing
- **Unit tests** with Go testing framework + testify
- **Integration tests** with testcontainers (PostgreSQL)
- **Service layer tests** with mocked dependencies
- **API endpoint tests** with Fiber test utilities
- **Integration Testing** with testcontainers for database testing

### Frontend Testing  
- **Unit tests** with Jest
- **Component tests** with Jest + React Testing Library
- **Hook tests** with @testing-library/react-hooks

### End to End Testing
- **E2E Testing** with Playwright for complete user journeys
- **Visual regression testing** for UI components

### Non functional requirements validation
- **Performance Testing**: k6 for load and stress testing
- **Security Testing**: Automated security scanning and penetration testing