knowfoolery/docs/4_work_plan/overall-plan.md

KnowFoolery Implementation Plan

Executive Summary

KnowFoolery is a quiz game platform requiring:

• 6 Go microservices with Domain-Driven Design
• SolidJS web app with Tauri for desktop/mobile
• PostgreSQL + Redis data layer
• Zitadel authentication (OAuth 2.0/OIDC)
• Full observability stack (Prometheus, Grafana, Jaeger)

Timeline: 9 weeks Team Size: 1-3 developers

---

Phase 1: Foundation (Weeks 1-2)

1.1 Development Environment Setup

Priority: CRITICAL Duration: 2-3 days

Tasks:

• Initialize Go workspace with go.work for multi-module monorepo
• Set up shared packages structure (backend/shared/)
• Configure linting (golangci-lint, ESLint)
• Create Docker Compose for local development (PostgreSQL, Redis)
• Set up Zitadel development instance
• Initialize frontend workspace with Yarn workspaces

Deliverables:

• Working local development environment
• make dev command to spin up all dependencies
• Developer onboarding documentation

1.2 Shared Backend Packages

Priority: HIGH Duration: 3-4 days

Packages to implement:

backend/shared/
├── domain/
│   ├── errors/         # DomainError, ValidationError, NotFoundError
│   ├── events/         # Event interfaces, event bus contracts
│   ├── types/          # ID types, pagination, common enums
│   └── valueobjects/   # PlayerName, Score, TimeWindow
└── infra/
    ├── auth/           # JWT middleware, RBAC helpers
    ├── database/       # Ent client factory, connection pooling
    ├── observability/  # Logging, metrics, tracing setup
    └── utils/          # HTTP response helpers, validation

Key Components:

• Domain error types with error codes
• Structured logging with zerolog
• OpenTelemetry tracing initialization
• Prometheus metrics registration
• Fiber middleware factory functions

---

Phase 2: Core Services (Weeks 3-5)

2.1 Question Bank Service (Port 8081)

Priority: HIGH Duration: 4-5 days Depends on: Phase 1

Domain Model:

• Aggregates: Question, Theme
• Value Objects: Hint, Answer, Difficulty
• Repository: QuestionRepository

API Endpoints:

POST /questions/random     # Get random question (with exclusion list)
GET  /questions/{id}       # Get question by ID
POST /admin/questions      # Create question (admin)
PUT  /admin/questions/{id} # Update question (admin)
DELETE /admin/questions/{id}
GET  /admin/themes         # List themes
POST /admin/questions/bulk # Bulk import

Key Features:

• Answer validation with 85% fuzzy matching (Levenshtein distance)
• Random selection with exclusion list
• Question caching in Redis (5-minute TTL)

Ent Schema:

// Question schema
field.String("theme").NotEmpty().MaxLen(100)
field.Text("text").NotEmpty().MaxLen(1000)
field.String("answer").NotEmpty().MaxLen(500)
field.Text("hint").Optional().MaxLen(500)
field.Enum("difficulty").Values("easy", "medium", "hard").Default("medium")
field.Bool("is_active").Default(true)
field.Time("created_at").Default(time.Now).Immutable()
field.Time("updated_at").Default(time.Now).UpdateDefault(time.Now)

2.2 User Service (Port 8082)

Priority: HIGH Duration: 3-4 days Depends on: Phase 1

Domain Model:

• Aggregates: User
• Value Objects: Email, DisplayName, ConsentRecord
• Repository: UserRepository

API Endpoints:

POST /users/register       # Register new player
GET  /users/{id}           # Get user profile
PUT  /users/{id}           # Update profile
DELETE /users/{id}         # Delete account (GDPR)
POST /users/verify-email   # Email verification
GET  /admin/users          # List users (admin)
POST /admin/users/{id}/export  # GDPR export

Key Features:

• Zitadel integration for identity management
• Email verification flow
• GDPR compliance (data export, deletion)

Ent Schema:

// User schema
field.String("name").NotEmpty().MaxLen(50)
field.String("display_name").NotEmpty().MaxLen(50)
field.String("email").Unique().NotEmpty()
field.Bool("email_verified").Default(false)
field.Time("created_at").Default(time.Now).Immutable()
field.Time("updated_at").Default(time.Now).UpdateDefault(time.Now)
field.Time("deleted_at").Optional().Nillable()

2.3 Game Session Service (Port 8080)

Priority: CRITICAL Duration: 5-6 days Depends on: 2.1, 2.2

Domain Model:

• Aggregates: GameSession
• Value Objects: Attempt, Score, SessionTimer
• Domain Services: ScoringService, GameFlowService, AntiCheatService

API Endpoints:

POST /sessions/start           # Start new game
POST /sessions/end             # End game session
POST /sessions/{id}/answer     # Submit answer
POST /sessions/{id}/hint       # Request hint
GET  /sessions/{id}            # Get session status
GET  /sessions/{id}/question   # Get current question

Key Features:

• Server-side timer management (30-minute sessions)
• 3 attempts per question with tracking
• Scoring: 2 points (no hint), 1 point (with hint), 0 (wrong)
• Anti-cheat validation (timing, sequence, state integrity)
• Question selection via Question Bank Service (gRPC)

Game Flow State Machine:

Created → Active → {Completed, TimedOut, Abandoned}
                ↓
              Paused → Active (future enhancement)

Scoring Logic:

func CalculateScore(isCorrect bool, usedHint bool, attemptNumber int) int {
    if !isCorrect {
        return 0
    }
    if usedHint {
        return 1
    }
    return 2
}

Ent Schema:

// GameSession schema
field.String("player_id").NotEmpty()
field.String("player_name").NotEmpty().MaxLen(50)
field.Int("total_score").Default(0)
field.Int("questions_asked").Default(0)
field.Int("questions_correct").Default(0)
field.Int("hints_used").Default(0)
field.String("current_question_id").Optional()
field.Int("current_attempts").Default(0)
field.Bool("current_hint_used").Default(false)
field.Enum("status").Values("created", "active", "completed", "timed_out", "abandoned")
field.Time("start_time")
field.Time("end_time").Optional().Nillable()

2.4 Leaderboard Service (Port 8083)

Priority: MEDIUM Duration: 3-4 days Depends on: 2.3

Domain Model:

• Aggregates: Leaderboard, PlayerScore
• Value Objects: Ranking, Statistics
• Domain Services: RankingService

API Endpoints:

GET  /leaderboard/top10        # Get top 10 scores
GET  /leaderboard/players/{id} # Get player ranking
GET  /leaderboard/stats        # Get global statistics
POST /leaderboard/update       # Internal score update

Key Features:

• Materialized view for top 10 (updated on score change)
• Redis sorted set for real-time rankings
• Success rate calculation
• Historical score tracking

Leaderboard Display Format:

Rank | Player    | Score | Questions | Success Rate | Duration
-----|-----------|-------|-----------|--------------|----------
  1  | Alice     |   24  |    14     |     86%      |   28m
  2  | Bob       |   22  |    13     |     85%      |   25m
  3  | Charlie   |   20  |    12     |     83%      |   30m

---

Phase 3: Gateway & Admin (Week 6)

3.1 API Gateway Service (Port 8086)

Priority: HIGH Duration: 3-4 days Depends on: Phase 2

Components:

• NGINX reverse proxy configuration
• Go Fiber gateway service
• JWT validation middleware (Zitadel)
• Rate limiting (Redis-backed sliding window)
• Request routing to microservices
• CORS configuration
• Security headers (CSP, HSTS, X-Frame-Options)

Rate Limits:

Endpoint Type	Limit	Window
General	100 requests	1 minute
Auth	5 requests	1 minute
API	60 requests	1 minute
Admin	30 requests	1 minute

Security Headers:

c.Set("Content-Security-Policy", "default-src 'self'; ...")
c.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
c.Set("X-Frame-Options", "DENY")
c.Set("X-Content-Type-Options", "nosniff")
c.Set("Referrer-Policy", "strict-origin-when-cross-origin")

3.2 Admin Service (Port 8085)

Priority: MEDIUM Duration: 3-4 days Depends on: 3.1

Domain Model:

• Aggregates: AdminSession, AuditLog
• Domain Services: AuditService, AuthorizationService

API Endpoints:

POST /admin/auth              # Admin authentication
GET  /admin/dashboard         # Dashboard statistics
GET  /admin/audit             # Audit log viewer

Key Features:

• MFA enforcement for admin users
• Comprehensive audit logging
• Dashboard with game statistics
• User and question management views

---

Phase 4: Frontend (Weeks 7-9)

4.1 Web Application (SolidJS)

Priority: HIGH Duration: 6-7 days Depends on: Phase 3

Project Structure:

frontend/apps/web/
├── src/
│   ├── routes/          # Pages
│   │   ├── Home.tsx
│   │   ├── Game.tsx
│   │   ├── Leaderboard.tsx
│   │   └── Profile.tsx
│   ├── features/        # Feature modules
│   │   ├── game/        # Game session components
│   │   ├── auth/        # Authentication flows
│   │   └── leaderboard/ # Leaderboard display
│   ├── hooks/           # Custom hooks
│   │   ├── useGameSession.ts
│   │   ├── useAuth.ts
│   │   └── useTimer.ts
│   └── services/        # API clients
├── public/
└── vite.config.ts

Screens:

1. Home Screen

   • Player name input (2-50 characters, alphanumeric + spaces)
   • Start game button
   • Link to leaderboard

2. Game Screen

   • Theme badge
   • Question text
   • Answer input field
   • Hint button (with score reduction warning)
   • Attempts remaining indicator (3/3, 2/3, 1/3)
   • Current score display
   • Countdown timer (30 minutes)
   • Timer warnings at 5 min, 1 min, 10 sec

3. Results Screen

   • Final score
   • Questions answered / correct
   • Success rate percentage
   • Session duration
   • Leaderboard position
   • Play again button

4. Leaderboard Screen

   • Top 10 players table
   • Player rank, score, questions, success rate, duration
   • Refresh button

5. Profile Screen (authenticated users)

   • Player statistics
   • Game history
   • Settings

Key Features:

• Real-time countdown timer with visual warnings
• Hint request with confirmation modal
• Attempt tracking with visual feedback
• Responsive design (mobile-first)
• SUID component library

4.2 Shared UI Components

Priority: MEDIUM Duration: 2-3 days Depends on: 4.1

Components:

frontend/shared/ui-components/
├── GameCard/            # Question display card
├── Timer/               # Countdown timer with warnings
├── ScoreDisplay/        # Current score indicator
├── LeaderboardTable/    # Top 10 table
├── AnswerInput/         # Answer submission input
├── HintButton/          # Hint request button
├── ResultsCard/         # Game over results
├── AttemptIndicator/    # Visual attempt counter
└── ThemeBadge/          # Question theme display

4.3 Desktop/Mobile (Tauri)

Priority: LOW Duration: 3-4 days Depends on: 4.1

Project Structure:

frontend/apps/cross-platform/
├── src/                 # Inherits from web app
├── src-tauri/
│   ├── Cargo.toml
│   ├── tauri.conf.json
│   ├── capabilities/
│   ├── icons/
│   └── src/
│       ├── main.rs
│       ├── lib.rs
│       └── commands/    # Native commands

Target Platforms:

• macOS (Intel + Apple Silicon)
• Windows (x64)
• Linux (x64)
• iOS (via Tauri 2.x)
• Android (via Tauri 2.x)

---

Phase 5: Infrastructure (Weeks 8-9)

5.1 Docker Configuration

Priority: HIGH Duration: 2-3 days

Directory Structure:

infrastructure/
├── dev/
│   ├── docker-compose.yml  # Dev stack with hot reload
│   └── .env.dev
├── prod/
│   ├── docker-compose.yml  # Production stack
│   └── .env.prod
└── services/               # Dockerfiles
    ├── gateway.Dockerfile
    ├── game-session.Dockerfile
    ├── question-bank.Dockerfile
    ├── user.Dockerfile
    ├── leaderboard.Dockerfile
    └── admin.Dockerfile

Development Stack:

services:
  postgres:
    image: postgres:15-alpine
    ports: ["5432:5432"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]
  zitadel:
    image: ghcr.io/zitadel/zitadel:latest
    ports: ["8080:8080"]
  prometheus:
    image: prom/prometheus:latest
    ports: ["9090:9090"]
  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports: ["16686:16686"]

5.2 Kubernetes Manifests

Priority: MEDIUM Duration: 3-4 days

Directory Structure:

infrastructure/k8s/
├── base/
│   ├── namespace.yaml
│   ├── configmaps/
│   │   ├── game-config.yaml
│   │   └── observability-config.yaml
│   ├── secrets/
│   │   └── database-secrets.yaml
│   └── services/
│       ├── gateway/
│       ├── game-session/
│       ├── question-bank/
│       ├── user/
│       ├── leaderboard/
│       └── admin/
├── overlays/
│   ├── dev/
│   │   └── kustomization.yaml
│   └── prod/
│       └── kustomization.yaml
└── monitoring/
    ├── prometheus/
    ├── grafana/
    └── jaeger/

5.3 CI/CD Pipeline

Priority: HIGH Duration: 2-3 days

GitHub Actions Workflows:

.github/workflows/
├── ci.yml              # Lint, test, build on every PR
├── security-scan.yml   # SAST/DAST scanning
├── deploy-dev.yml      # Deploy to development (on merge to develop)
└── deploy-prod.yml     # Deploy to production (on release tag)

CI Pipeline Stages:

1. Lint (golangci-lint, ESLint)
2. Unit Tests
3. Integration Tests (with testcontainers)
4. Build Docker Images
5. Security Scan (gosec, Trivy)
6. Push to Registry

CD Pipeline Stages:

1. Pull latest images
2. Run database migrations
3. Deploy to Kubernetes
4. Health checks
5. Smoke tests
6. Rollback on failure

---

Phase 6: Testing & Quality (Ongoing)

6.1 Backend Testing Strategy

Parallel to: All phases

Test Types:

Type	Tool	Coverage Target
Unit Tests	Go testing + testify	80%
Integration Tests	testcontainers	Key flows
API Tests	Fiber test utilities	All endpoints
Load Tests	k6	Performance SLAs

Example Test Structure:

func TestGameService_StartGame(t *testing.T) {
    // Arrange
    ctx := context.Background()
    client := enttest.Open(t, "sqlite3", "file:ent?mode=memory")
    defer client.Close()

    svc := services.NewGameService(client)

    // Act
    session, err := svc.StartGame(ctx, "user123", "TestPlayer")

    // Assert
    require.NoError(t, err)
    assert.NotEmpty(t, session.ID)
    assert.Equal(t, "TestPlayer", session.PlayerName)
    assert.Equal(t, 0, session.TotalScore)
}

6.2 Frontend Testing Strategy

Parallel to: Phase 4

Test Types:

Type	Tool	Coverage Target
Unit Tests	Jest	Hooks, utilities
Component Tests	Solid Testing Library	All components
E2E Tests	Playwright	Critical user flows

Critical E2E Flows:

1. Player registration and login
2. Complete game session (start → answer questions → end)
3. Leaderboard viewing
4. Admin question management

6.3 Security Testing

Parallel to: All phases

Tools:

• SAST: gosec, ESLint security plugins
• DAST: OWASP ZAP
• Dependency Scanning: Dependabot, Snyk
• Container Scanning: Trivy

Security Checklist:

• Input validation on all endpoints
• SQL injection prevention (Ent ORM)
• XSS prevention (output encoding)
• CSRF protection
• Rate limiting implemented
• JWT validation with Zitadel
• Secrets not in code
• Security headers configured

---

Implementation Order Summary

Week 1-2: Foundation
├── Development environment setup
├── Docker Compose for local dev
├── Shared packages (errors, logging, metrics)
└── Database schemas (Ent)

Week 3-4: Core Backend
├── Question Bank Service
├── User Service
└── Game Session Service (start)

Week 5: Complete Backend
├── Game Session Service (complete)
├── Leaderboard Service
└── Service integration testing

Week 6: Gateway & Admin
├── API Gateway with JWT validation
├── Rate limiting and security
├── Admin Service
└── End-to-end security testing

Week 7-8: Frontend
├── SolidJS web application
├── Shared UI components
├── Authentication flows
└── Frontend testing

Week 9: Polish & Deploy
├── Tauri desktop/mobile packaging
├── Kubernetes deployment
├── Production configuration
├── Documentation updates
└── Performance testing

---

Dependencies Graph

                    ┌─────────────────┐
                    │   Phase 1       │
                    │   Foundation    │
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┐
           │                 │                 │
           ▼                 ▼                 ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │ Question     │  │ User         │  │ (parallel)   │
    │ Bank Service │  │ Service      │  │              │
    └──────┬───────┘  └──────┬───────┘  └──────────────┘
           │                 │
           └────────┬────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ Game Session     │
           │ Service          │
           └────────┬─────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ Leaderboard      │
           │ Service          │
           └────────┬─────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ API Gateway      │
           │ Admin Service    │
           └────────┬─────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ Frontend         │
           │ Applications     │
           └────────┬─────────┘
                    │
                    ▼
           ┌──────────────────┐
           │ Infrastructure   │
           │ & Deployment     │
           └──────────────────┘

---

Risk Mitigation

Risk	Probability	Impact	Mitigation
Zitadel integration complexity	Medium	High	Start with mock auth, integrate Zitadel in parallel
gRPC learning curve	Low	Medium	Use HTTP initially, add gRPC later as optimization
Tauri mobile maturity	Medium	Low	Web app is priority; mobile can be deferred
Performance under load	Medium	High	Load test early with k6, optimize hot paths
Database schema changes	Medium	Medium	Use Ent migrations, plan schema carefully
Security vulnerabilities	Low	Critical	Security testing in every phase, code review

---

Success Criteria

Functional Requirements

• Player can register with name (2-50 chars, alphanumeric + spaces)
• Player can start a new game session
• Questions display with theme and text
• Player can submit answers (3 attempts max)
• Player can request hints (reduces max score to 1)
• Scoring works correctly (2/1/0 points)
• Timer enforces 30-minute limit
• Game ends on timeout or completion
• Leaderboard shows top 10 accurately
• Admin can create/update/delete questions
• Admin can view audit logs

Non-Functional Requirements

• API response time < 200ms (p95)
• Support 1000+ concurrent users
• 99.9% uptime target
• All security measures implemented
• GDPR compliance (data export, deletion)
• Comprehensive observability (metrics, logs, traces)

Quality Requirements

• 80% code coverage (backend)
• All critical paths have E2E tests
• Security scan passes with no critical issues
• Documentation is complete and up-to-date

---

Appendix: Technology Stack

Backend

Component	Technology	Version
Language	Go	1.25+
HTTP Framework	Fiber	3.0+
ORM	Ent (Facebook)	Latest
Database	PostgreSQL	15+
Cache	Redis	7+
Authentication	Zitadel	Latest
Logging	zerolog	Latest
Metrics	Prometheus client	Latest
Tracing	OpenTelemetry	Latest

Frontend

Component	Technology	Version
Framework	SolidJS	1.9+
Build Tool	Vite	4.0+
Language	TypeScript	5.0+
UI Library	SUID	Latest
Desktop/Mobile	Tauri	2.9+
Testing	Jest + Playwright	Latest

Infrastructure

Component	Technology	Version
Containerization	Docker	24+
Orchestration	Kubernetes	1.28+
CI/CD	GitHub Actions	Latest
Monitoring	Prometheus + Grafana	Latest
Tracing	Jaeger	Latest
Logging	Loki	Latest