knowfoolery/docs/2_architecture/technical-architecture.md

Know Foolery - Technical Architecture Documentation

Architecture Overview

Know Foolery follows a microservices architecture with clear separation between frontend presentation, backend services, and data persistence layers. The system is designed for cross-platform compatibility, scalability, and maintainability.

Technical Architecture

Frontend Architecture

• Web Application: React with TypeScript, vite and React Native Web
• Mobile Applications: React Native with Expo for iOS and Android
• Desktop Applications: Wails for macOS, Windows, and Linux, with the web application packaged for the deployement in the Wails app
• UI Framework: Gluestack UI for consistent cross-platform design

Backend Architecture

• Business Logic: Domain Driven Design approach
• 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

Domain Design

• Aggregates: User, Theme, Question, GameSession
• Value Objects: Hint, Attempt, Answer, Score
• Domain Services: Scoring

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 and user 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 production application data
3. sqlite: Database for test application data
4. Redis: Session state and caching layer

Database Design

Core Entities

• Users: ID, name, created_at (minimal player data)
• Themes: ID, theme, metadata
• Questions: ID, ID of theme, text, answer, hint, metadata
• GameSessions: ID, ID of user, score, start_time, end_time, is_active
• Attempts: ID, ID of GameSession, answer
• Leaderboard: Aggregated scores and rankings
• AuditLogs: Admin actions and security events

Data Relationships

• Questions belong to themes
• GameSessions track multiple question attempts for a user
• Leaderboard aggregates from GameSessions
• AuditLogs reference users and actions

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: Wails applications for major operating systems

System Architecture Diagram

┌────────────────────────────────────────────────────────────────────────────┐
│                            Client Layer                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  ┌─────────────┐    │
│  │   Web App    │  │  Mobile iOS  │  │ Mobile Android│  │   Desktop   │    │
│  │   (React)    │  │(React Native)│  │(React Native) │  │   (Wails)   │    │
│  └──────────────┘  └──────────────┘  └───────────────┘  └─────────────┘    │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                               HTTPS/WSS
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                          API Gateway Layer                                  │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  NGINX + API Gateway Service (Go)                                      │ │
│  │  • Authentication & Authorization                                      │ │
│  │  • Rate Limiting & CORS                                                │ │
│  │  • Request Routing & Load Balancing                                    │ │
│  │  • Security Headers & Input Validation                                 │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                 gRPC/HTTP
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Microservices Layer                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │    Game     │ │   Question  │ │    User     │ │ Leaderboard │            │
│  │   Service   │ │   Service   │ │   Service   │ │   Service   │            │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘            │
│  ┌─────────────┐ ┌─────────────┐                                            │
│  │   Session   │ │    Admin    │                                            │
│  │   Service   │ │   Service   │                                            │
│  └─────────────┘ └─────────────┘                                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                              Database Connections
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Data & External Layer                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ PostgreSQL  │ │    Redis    │ │   Zitadel   │ │ Observabi-  │            │
│  │   Primary   │ │   Cache &   │ │   OAuth     │ │    lity     │            │
│  │  Database   │ │  Sessions   │ │  Provider   │ │    Stack    │            │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────────────────────┘

Technology Stack

• Web Application: React with TypeScript, vite and React Native Web
• Mobile Applications: React Native with Expo for iOS and Android
• Desktop Applications: Wails for macOS, Windows, and Linux, with the web application packaged for the deployement in the Wails app
• UI Framework: Gluestack UI for consistent cross-platform design

Frontend Technologies

Web Application:
  Framework: React 18.2+
  Language: TypeScript 5.0+
  Build Tool: Vite 4.0+
  UI Library: Gluestack UI (React Native Web)
  Styling: NativeWind/Tailwind CSS 3.0+
  State Management: React Context + useReducer
  Testing: Jest + React Testing Library + Playwright

Mobile Applications:
  Framework: React Native 0.81+
  Language: TypeScript 5.9+
  UI Library: Gluestack UI (Native)
  Navigation: Expo 54+
  State Management: React Context + useReducer
  Testing: Jest + React Native Testing Library

Desktop Application:
  Framework: Wails 2.10+
  Template: wails-vite-react-ts-tailwind-template 

Backend Technologies

Microservices:
  Language: Go 1.25+
  HTTP Framework: Fiber 3.0+
  gRPC: Protocol Buffers + gRPC-Go
  Database ORM: Ent (Facebook)
  Authentication: JWT + Zitadel Integration
  Testing: Go testing + testcontainers
  
API Gateway:
  Reverse Proxy: NGINX
  Gateway Service: Go + Fiber
  Load Balancing: Round-robin + Health checks
  Rate Limiting: Redis-based sliding window

Data Technologies

Primary Database:
  Engine: PostgreSQL 15+
  Connection Pooling: pgxpool
  Migrations: Ent migrations
  Backup: pg_dump + Object Storage

Cache Layer:
  Engine: Redis 7+
  Use Cases: Sessions, Rate limiting, Cache
  Clustering: Redis Cluster (Production)
  Persistence: RDB + AOF

Authentication:
  Provider: Zitadel (Self-hosted)
  Protocol: OAuth 2.0 + OpenID Connect
  Tokens: JWT with RS256 signing
  MFA: TOTP + WebAuthn

Infrastructure Technologies

Containerization:
  Runtime: Docker 24+
  Orchestration: Kubernetes 1.28+
  Registry: Private Docker Registry
  
Observability:
  Metrics: Prometheus + Node Exporter
  Visualization: Grafana + Custom Dashboards
  Tracing: Jaeger + OpenTelemetry
  Logging: Structured logging + Loki
  
CI/CD:
  Platform: GitHub Actions
  Testing: Automated test suites
  Security: SAST/DAST scanning
  Deployment: GitOps with ArgoCD

Microservices Design

Service Boundaries

1. Game Service

// API Endpoints
POST   /api/v1/game/start              // Start new game session
GET    /api/v1/game/session/{id}       // Get session details
POST   /api/v1/game/answer             // Submit answer
POST   /api/v1/game/hint               // Request hint
POST   /api/v1/game/end                // End session
GET    /api/v1/game/status/{id}        // Get session status

2. Question Service

// API Endpoints
GET    /api/v1/questions/themes/random/{id}  // Get random question in a theme
GET    /api/v1/questions/random              // Get random question in a theme
GET    /api/v1/questions/{id}                // Get specific question
GET    /api/v1/questions/themes              // List available themes
POST   /api/v1/questions                     // Create question (admin)
PUT    /api/v1/questions/{id}                // Update question (admin)
DELETE /api/v1/questions/{id}                // Delete question (admin)
GET    /api/v1/questions                     // List all questions (admin)
POST   /api/v1/questions/bulk                // Bulk question import (admin)

3. User Service

// API Endpoints
POST   /api/v1/users/register          // Register new player
GET    /api/v1/users/profile           // Get user profile
PUT    /api/v1/users/profile           // Update profile
GET    /api/v1/users/sessions          // Get session history
DELETE /api/v1/users/profile           // Delete account (GDPR)
GET    /api/v1/users                   // List all users (admin)
DELETE /api/v1/users                   // Delete user (admin)

4. Leaderboard Service

// API Endpoints
GET    /api/v1/leaderboard/top10       // Get top 10 scores
GET    /api/v1/leaderboard/stats       // Get game statistics
GET    /api/v1/leaderboard/player/{id} // Get player ranking
POST   /api/v1/leaderboard/update      // Update scores (internal)

5. Session Service

// API Endpoints
POST   /api/v1/sessions                // Create session
GET    /api/v1/sessions/{id}           // Get session
PUT    /api/v1/sessions/{id}           // Update session
DELETE /api/v1/sessions/{id}           // End session
GET    /api/v1/sessions/{id}/timer     // Get timer status

6. Admin Service

// API Endpoints
POST   /api/v1/admin/auth              // Admin authentication
GET    /api/v1/admin/dashboard         // Dashboard data
GET    /api/v1/admin/audit             // Audit logs

Inter-Service Communication

Service Mesh Architecture

Communication Patterns:
  Synchronous: gRPC for real-time operations
  Asynchronous: Event-driven via message queues (future)
  
Service Discovery:
  Registry: Kubernetes DNS
  Health Checks: HTTP /health endpoints
  Load Balancing: Round-robin with health awareness
  
Circuit Breaker:
  Pattern: Hystrix-style circuit breakers
  Fallback: Graceful degradation
  Timeout: Context-based timeouts

gRPC Service Definitions

// 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);
}

This technical architecture provides a solid foundation for building a scalable, secure, and maintainable quiz game platform with cross-platform capabilities.