knowfoolery/README.md

# 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](docs/1_requirements/functional-requirements.md)
- [Non Functional](docs/1_requirements/non-functional-requirements.md)

#### Architecture
- [Technical](docs/2_architecture/technical-architecture.md)
- [Security](docs/2_architecture/security-architecture.md)
- [Observability](2_architecture/observability-architecture.md)

#### Guidelines
- [Development](docs/3_guidelines/development-guidelines.md)
- [Security](docs/3_guidelines/security-guidelines.md)
- [Observability](docs/3_guidelines/observability-guidelines.md)

## 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:
```bash
docker compose -f infrastructure/prod/docker-compose.yml --env-file infrastructure/prod/.env.prod config
```
3. Build and start:
```bash
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