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:**
```go
// 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:**
```go
// 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:**
```go
func CalculateScore(isCorrect bool, usedHint bool, attemptNumber int) int {
    if !isCorrect {
        return 0
    }
    if usedHint {
        return 1
    }
    return 2
}
```

**Ent Schema:**
```go
// 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:**
```go
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: Web 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
```

---

## 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:**
```yaml
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.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. Health checks
4. Smoke tests
5. 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:**
```go
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

---

### Phase 7: 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)

---

## 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
├── 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 A: 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 | Docker Compose | Latest |
| CI/CD | GitHub Actions | Latest |
| Monitoring | Prometheus + Grafana | Latest |
| Tracing | Jaeger | Latest |
| Logging | Loki | Latest |

---

## Appendix B: Future Enhancements (do not take into account for now)

### 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/
```