@ -6,7 +6,7 @@ Know Foolery follows a microservices architecture with clear separation between
### Frontend Architecture
### Frontend Architecture
- **Web Application** : Responsive web application
- **Web Application** : Responsive web application
- **Mobile Applications** : Cross platform application for iOS and Android
- **Mobile Applications** : Cross platform application for iOS and Android. Packages the web application
- **Desktop Applications** : Cross platform application for MacOS, Windows and Linux. Packages the web application
- **Desktop Applications** : Cross platform application for MacOS, Windows and Linux. Packages the web application
### Backend Architecture
### Backend Architecture
@ -23,113 +23,6 @@ Know Foolery follows a microservices architecture with clear separation between
- **Cache** : Session state and caching layer
- **Cache** : Session state and caching layer
## Application Design
### 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’
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
## System Architecture Diagram
## System Architecture Diagram
```
```
@ -137,7 +30,6 @@ Know Foolery follows a microservices architecture with clear separation between
│ Client Layer │
│ Client Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Web App │ │ Mobile iOS │ │ Mobile Android│ │ Desktop │ │
│ │ Web App │ │ Mobile iOS │ │ Mobile Android│ │ Desktop │ │
│ │ (React) │ │(React Native)│ │(React Native) │ │ (Wails) │ │
│ └──────────────┘ └──────────────┘ └───────────────┘ └─────────────┘ │
│ └──────────────┘ └──────────────┘ └───────────────┘ └─────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
└────────────────────────────────────────────────────────────────────────────┘
│
│
@ -158,50 +50,39 @@ Know Foolery follows a microservices architecture with clear separation between
│
│
┌─────────────────────────────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────────────────────────────────┐
│ Microservices Layer │
│ Microservices Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Game Session│ │Question Bank│ │ User │ │ Leaderboard │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Admin │ │
│ │ Service │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────────────────┘
│
│
Database Connections
Database Connections
│
│
┌─────────────────────────────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────────────────────────────────┐
│ Data & External Layer │
│ Data & External Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ ┌───────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Zitadel │ │ Observabi- │ │
│ │ Primary │ │ Cache & │ │ Authentication │ │ Observability │ │
│ │ Primary │ │ Cache & │ │ OAuth │ │ lity │ │
│ │ Database │ │ Sessions │ │ Provider │ │ Stack │ │
│ │ Database │ │ Sessions │ │ Provider │ │ Stack │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ └───────────────┘ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────────────────┘
```
```
### Frontend Technologies
### Frontend Technologies
```yaml
```yaml
Web Application:
Web Application:
Framework: React 18.2 +
Framework: SolidJS 1.9.3 +
Language: TypeScript 5.0+
Language: TypeScript 5.0+
Build Tool: Vite 4.0+
Build Tool: Vite 4.0+
UI Library: Gluestack UI (React Native Web)
UI Library: SUID (suid.io)
Styling: NativeWind/Tailwind CSS 3.0+
Testing: Jest + Playwright
State Management: React Context + useReducer
Testing: Jest + React Testing Library + Playwright
Mobile Applications:
Mobile Applications:
Framework: React Native 0.81+
Framework: Tauri 2.9.5+
Language: TypeScript 5.9+
Language: TypeScript
UI Library: Gluestack UI (Native)
Package manager: yarn
Navigation: Expo 54+
UI Template: Solid
State Management: React Context + useReducer
Testing: Jest + React Native Testing Library
Desktop Application:
Desktop Application:
Framework: Wails 2.10+
Framework: Tauri 2.9.5+
Template: wails-vite-react-ts-tailwind-template
Language: TypeScript
Package manager: yarn
UI Template: Solid
```
```
### Backend Technologies
### Backend Technologies
@ -229,7 +110,7 @@ Primary Database:
Migrations: Ent migrations
Migrations: Ent migrations
Backup: pg_dump + Object Storage
Backup: pg_dump + Object Storage
Cache Layer :
Cache and Session :
Engine: Redis 7+
Engine: Redis 7+
Use Cases: Sessions, Rate limiting, Cache
Use Cases: Sessions, Rate limiting, Cache
Clustering: Redis Cluster (Production)
Clustering: Redis Cluster (Production)
@ -258,8 +139,7 @@ Authentication:
```
```
### Inter-Service Communication
### Inter-Service Communication
Service Mesh Architecture
#### Service Mesh Architecture
```yaml
```yaml
Communication Patterns:
Communication Patterns:
Synchronous: gRPC for real-time operations
Synchronous: gRPC for real-time operations
@ -276,31 +156,6 @@ Circuit Breaker:
Timeout: Context-based timeouts
Timeout: Context-based timeouts
```
```
#### 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);
}
```
## Deployment & Infrastructure
## Deployment & Infrastructure
### Development Environment
### Development Environment
@ -338,3 +193,93 @@ CI/CD:
Security: SAST/DAST scanning
Security: SAST/DAST scanning
Deployment: GitOps with ArgoCD
Deployment: GitOps with ArgoCD
```
```
## Project Structure
```
knowfoolery/
├── docs/ # Project documentation
├── backend/
│ ├── services/ # Microservices
│ │ ├── {service-name}/
│ │ │ ├── cmd/
│ │ │ │ └── main.go # Service entry point
│ │ │ ├── internal/
│ │ │ │ ├── handlers/ # Fiber HTTP handlers
│ │ │ │ ├── app/ # Business logic (commands, queries, dto)
│ │ │ │ ├── domain/ # Domain logic (aggregates, value objects, repositories interfaces, services from Domain Driven Design)
│ │ │ │ ├── infra/
│ │ │ │ │ ├── events/
│ │ │ │ │ ├── grpc/
│ │ │ │ │ └── ent/ # Ent models and schemas + repositories implementation
│ │ │ ├── api/ # API definitions (OpenAPI/gRPC)
│ │ │ ├── config/ # Configuration management
│ │ │ ├── tests/ # Service-specific tests
│ │ │ ├── Dockerfile # Container definition
│ │ │ └── go.mod # Go module
│ │ └── shared/ # Shared packages
│ │ │ ├── errors/ # Shared domain errors
│ │ │ ├── events/ # Domain events contracts
│ │ │ ├── types/ # Shared types
│ │ │ ├── valueobjects/ # Shared value objects
│ │ │ └── infra/
│ │ │ ├── auth/ # JWT middleware & Zitadel integration
│ │ │ ├── observability/ # Metrics and tracing
│ │ │ ├── security/ # Security utilities
│ │ │ └── utils/ # Common utilities
├── frontend/
│ ├── shared/
│ │ ├── ui-components/ # Shared Gluestack UI components
│ │ ├── logic/ # Business logic
│ │ ├── types/ # TypeScript types
│ │ └── utils/ # Utility functions
│ └── apps/
│ ├── web/ # React web app
│ ├── mobile/ # React Native app
│ └── desktop/ # Wails desktop app
└── infrastructure/ # DevOps and deployment
├── dev/ # Development setup
│ ├── docker-compose.yml # dev stack (hot reload, mounts)
│ └── api.env # dev env vars
└── prod/ # Production setup
```
### Backend Directory Structure
```
backend/
├── Domain/ # Domain logic (DDD patterns)
├── services/ # Microservices
│ ├── {service-name}/
│ │ ├── cmd/main.go # Service entry point
│ │ ├── internal/
│ │ │ ├── handlers/ # Fiber HTTP handlers
│ │ │ ├── app/ # Business logic
│ │ │ ├── middleware/ # Service-specific middleware
│ │ │ └── models/ # Ent models and schemas
│ │ ├── config/ # Configuration management
│ │ └── tests/ # Service-specific tests
│ └── shared/ # Shared packages
│ ├── auth/ # JWT & Zitadel integration
│ ├── database/ # Ent database client
│ ├── observability/ # Metrics and tracing
│ └── security/ # Security utilities
```
### Frontend Structure
```
frontend/
├── shared/
│ ├── ui-components/ # Shared Gluestack UI components
│ ├── logic/ # Business logic
│ ├── types/ # TypeScript types
│ └── utils/ # Utility functions
└── apps/
├── web/ # SolidJS web app (Vite + TypeScript)
└── cross-platform/ # Tauri app (embeds the SolidJS web app)
```
### Infrastructure Structure
```
Infrastructure/
├── dev/ # Scripts to setup and start development infrastructure
└── prod/ # Scripts to setup and start production infrastructure
```
