Know Foolery

Overview

Know Foolery is a quiz game inspired by the French game "Déconnaissance" (https://escaleajeux.fr/jeu/decon.0.1). It's a web-based quiz platform with plans for cross-platform expansion to mobile and desktop applications.

Game Concept

Core Gameplay

• Objective: Players answer randomly selected questions to score points
• Question Format: Each question belongs to a theme, displayed above the question
• Scoring System:
  • 2 points for correct answer without hint
  • 1 point for correct answer with hint
  • 0 points for incorrect answer or timeout
• Attempts: Players have exactly 3 attempts per question
• Time Limit: Each game session is limited to 30 minutes maximum
• Hints: Players can request one hint per question, but this reduces their score

Player Experience

• Registration: Players must enter their name before starting a game
• Session Management: Game tracks progress, attempts, and time remaining
• Leaderboard: Display top 10 scores accessible to all players
• Themes: Questions are categorized by themes (Geography, History, Science, etc.)

Documentation

Detailed requirements

• Functional
• Non Functional

Architecture

• Technical
• Security
• Observability

Guidelines

• Development
• Security
• Observability

Infrastructure

Directory Layout

• infrastructure/dev: local development compose stack and configs
• infrastructure/prod: production compose stack, nginx, and prometheus config
• infrastructure/services: Dockerfiles for each backend service
• tasks: Go Task CI/CD workflows
• .github/workflows: thin GitHub Actions wrappers that trigger Task workflows

Production Compose Usage

1. Copy infrastructure/prod/.env.prod.example to infrastructure/prod/.env.prod and fill secrets.
2. Validate config:

docker compose -f infrastructure/prod/docker-compose.yml --env-file infrastructure/prod/.env.prod config

3. Build and start:

docker compose -f infrastructure/prod/docker-compose.yml --env-file infrastructure/prod/.env.prod up -d --build

Task Workflows

• task ci:security-scan: lint, unit/integration tests, backend coverage gate (>=80%), docker build validation, k6 smoke (when configured), gosec, trivy scans
• task cd:deploy-dev: deploy to dev host over SSH + compose build/up + smoke checks
• task cd:deploy-prod: deploy release tag to prod host over SSH + rollback on failure
• task ci:k6-smoke: run smoke load profile against gateway critical paths
• task ci:k6-load: run local load profile against gateway critical paths

Make wrappers:

• make task-security-scan
• make task-deploy-dev
• make task-deploy-prod
• make task-k6-smoke
• make task-k6-load
• make infra-build-images
• make infra-up-prod

Backend Testing Strategy Implementation (6.1)

• Backend coverage gate uses stepwise thresholds from BACKEND_COVERAGE_THRESHOLDS (default: 60 70 80), summary written to reports/tests/backend-coverage-summary.txt
• Coverage gate aggregation targets backend service internal/application, internal/domain, and internal/interfaces/http packages from service profiles (services-*) with deduplicated unit/integration blocks
• Coverage profiles: generated in reports/tests/coverage/*.out and merged into reports/tests/coverage/backend-combined.out
• DB integration tests: question-bank repository integration now uses a disposable Postgres Testcontainers instance
• API route coverage: admin service integration tests now validate /admin/auth, /admin/dashboard, /admin/audit success and error paths
• Load tests: k6 gateway critical-path scripts located in tests/load/k6

Frontend Testing Strategy Implementation (6.2)

• Unit and component tests run with Solid Testing Library in frontend/apps/web/src/**/*.test.ts(x) and frontend/shared/ui-components/src/**/*.test.ts(x).
• Hooks and utility coverage includes useAuth, useTimer, validation, session storage, and timer helpers.
• Component coverage includes shared UI components and route-level tests for Home, Game, Results, Leaderboard, Profile, and admin question management.
• Playwright critical-flow E2E tests live in frontend/apps/web/e2e/critical-flows.spec.ts:
  • Player registration + demo login
  • Complete game session (start → answer → results)
  • Leaderboard viewing
  • Admin question management (/admin/questions)
• Run locally:
  • cd frontend && yarn test
  • cd frontend && yarn test:e2e
• CI execution:
  • task ci:frontend-e2e-tests
  • Included in task ci:security-scan

k6 Prerequisites and Environment

• Install k6 locally to run load tests from Task/Make commands.
• Required env var: K6_BASE_URL (example: http://localhost:8086)
• Optional env vars:
  • K6_AUTH_TOKEN for protected routes
  • K6_VUS, K6_DURATION, K6_SLEEP_SECONDS to tune profile execution

GitHub Actions Secrets

• Shared: SSH_PRIVATE_KEY
• Dev deploy: DEV_DEPLOY_HOST, DEV_DEPLOY_USER, DEV_DEPLOY_PATH
• Prod deploy: PROD_DEPLOY_HOST, PROD_DEPLOY_USER, PROD_DEPLOY_PATH

Deployment Host Prerequisites

• Linux host with Docker Engine + Docker Compose v2
• git and curl installed
• persistent repository checkout at the configured deploy path
• populated infrastructure/prod/.env.prod on target host

Future Enhancements

Planned Features

1. Question Categories: Filter questions by subject
2. Difficulty Progression: Adaptive difficulty based on performance
3. Multiplayer Mode: Real-time competition between players
4. Daily Challenges: Special themed question sets
5. Achievement System: Badges and milestones
6. Question Contributions: Player-submitted questions

Scoring Enhancements

1. Time Bonus: Extra points for quick correct answers
2. Streak Bonus: Consecutive correct answers bonus
3. Difficulty Multiplier: Higher points for harder questions
4. Perfect Game Bonus: Bonus for 100% correct rate

Success Metrics

User Engagement

• Daily Active Users: Track player engagement
• Session Duration: Average time spent playing
• Question Accuracy: Player success rates by theme
• Hint Usage: Frequency and effectiveness of hints

Technical Performance

• Response Times: API and database performance metrics
• Error Rates: Application stability and reliability
• Uptime: System availability and reliability
• Security Events: Monitoring for security incidents

Business Metrics

• Player Retention: User return rates and engagement
• Content Quality: Question difficulty and engagement
• Platform Usage: Cross-platform adoption rates
• Admin Efficiency: Content management effectiveness

Project Roadmap

Phase 1: Core Platform (Weeks 1-6)

• Basic web application with core game mechanics
• Essential microservices and database setup
• Admin panel for question management

Phase 2: Enhanced Features (Weeks 7-12)

• Complete security implementation
• Comprehensive observability and monitoring
• Production-ready deployment

Phase 3: Mobile Expansion (Weeks 13-18)

• Cross-platform mobile applications
• Cross-platform component optimization
• Mobile app store deployment

Phase 4: Advanced Features (Weeks 19-24)

• Desktop applications
• Advanced analytics and reporting
• Enhanced security and compliance features