knowfoolery/docs/4_work_plan/2.1-question-bank-service.md

2.1 Question Bank Service (Port 8081) - Detailed Implementation Plan

Summary

Implement the Question Bank Service as the source of truth for quiz questions and themes, with public random/get endpoints and admin CRUD/bulk workflows. Runtime stack: Fiber HTTP, PostgreSQL persistence, Redis-backed random-question cache, and shared packages for auth/validation/errors/observability.

Objectives

1. Provide /questions/random and /questions/{id} for gameplay.
2. Provide admin endpoints for create/update/delete/list themes/bulk import.
3. Implement 85% fuzzy answer matching helper for downstream game-session usage.
4. Add observability, health/readiness, and test coverage.

API Endpoints

• POST /questions/random
• GET /questions/{id}
• POST /admin/questions
• PUT /admin/questions/{id}
• DELETE /admin/questions/{id}
• GET /admin/themes
• POST /admin/questions/bulk

Data Model

Question fields:

• id (UUID)
• theme (max 100)
• text (max 1000)
• answer (max 500)
• hint (optional, max 500)
• difficulty (easy|medium|hard, default medium)
• is_active (default true)
• created_at, updated_at

Indexes:

• (theme, is_active)
• (difficulty, is_active)

Core Logic

1. Random selection with exclusion list and optional theme/difficulty filters.
2. Cache key format: qb:random:v1:{sha256(filters+sorted_exclusions)}.
3. Cache TTL: 5m.
4. Cache invalidation on admin writes via namespace version bump.
5. Fuzzy matching utility:

• normalize strings (trim/lower/collapse spaces/remove punctuation)
• compute Levenshtein similarity
• match when score >= 0.85

Security

1. Public endpoints are open for internal service usage.
2. Admin endpoints protected by Zitadel JWT middleware.
3. Admin authorization requires admin role + MFA.

Observability

1. Shared logger initialized with service metadata.
2. Shared metrics registered and /metrics exposed.
3. Shared tracer initialization and shutdown.
4. /health and /ready endpoints available.

Configuration

• QUESTION_BANK_PORT (default 8081)
• QUESTION_CACHE_TTL (default 5m)
• QUESTION_RANDOM_MAX_EXCLUSIONS (default 200)
• QUESTION_BULK_MAX_ITEMS (default 5000)
• shared POSTGRES_*, REDIS_*, TRACING_*, METRICS_*, LOG_LEVEL, ZITADEL_*

Testing Strategy

1. Unit tests:

• fuzzy matching threshold behavior
• random selection no-result and cache paths

2. HTTP integration tests:

• random/get success
• admin auth guard behavior
• metrics endpoint

3. Repository integration test scaffold (optional, DB-backed when env is set)

Verification

From backend/services/question-bank-service:

go test ./...
go vet ./...