Retro Computing Quiz Platform

 ____      _              ___        _     
|  _ \ ___| |_ _ __ ___  / _ \ _   _(_)____
| |_) / _ \ __| '__/ _ \| | | | | | | |_  /
|  _ <  __/ |_| | | (_) | |_| | |_| | |/ / 
|_| \_\___|\__|_|  \___/ \__\_\\__,_|_/___|
                                           

A web-based quiz platform for testing knowledge of vintage computing systems (8-bit and 16-bit homecomputers and PCs up to 2003).

Table of Contents

• Features
• Technology Stack
• Quick Start
• Step-by-Step Setup
• Operations Guide
• Architecture
• Project Structure
• Configuration
• Security
• API Reference
• Testing
• Troubleshooting
• License

---

Features

Quiz System

• Multiple quizzes with up to 75 questions each
• Millisecond-precision timer for competitive tracking
• Points-based scoring with difficulty multipliers and time bonuses
• Answer randomization per session
• Real-time points display during quiz

User Management

• User registration with email verification
• Guest mode for trying quizzes without registration
• User profiles with quiz history and statistics
• Admin panel for user, quiz, and question management

Multi-Language Support

• Full i18n support (English, German)
• Persistent language preferences
• Translated quiz content and UI

Themes

• 13 themes: authentic retro (C64, Amiga, Atari ST, ZX Spectrum, PET, CGA, EGA, VGA, MS-DOS, Win98, GeoCities, 80s Vibes) plus a modern theme
• Pixel art icon system for retro themes
• Persistent theme preferences

Admin Features

• Bulk operations for users, quizzes, and questions
• Content moderation with flagging system
• JSON import/export for quiz data
• Custom icon upload for quizzes and themes
• Email notifications for user submissions

---

Technology Stack

Component	Technology
Backend	Python 3.14, FastAPI
Database	PostgreSQL 17
Cache	Valkey 7 (Redis-compatible)
Development	Finch on macOS (ARM64)
Production	Docker Engine on Linux (AMD64)

---

Quick Start

# 1. Clone and configure
git clone <repository-url>
cd RetroQuizzer
cp .env.example .env

# 2. Start Finch VM (macOS only, first time)
brew install finch && finch vm init && finch vm start

# 3. Build and start everything
make init

# 4. Open http://localhost:8000

---

Step-by-Step Setup

Prerequisites

Environment	Tool	Install
macOS (dev)	Finch	brew install finch
Linux (prod)	Docker Engine	Usually pre-installed

1. Install Finch (macOS)

brew install finch
finch vm init
finch vm start
finch version

2. Clone and Configure

git clone <repository-url>
cd RetroQuizzer
cp .env.example .env
# Edit .env with your settings

3. Start Services

make init    # First time: build, start, migrate
# or
make up      # Subsequent starts

4. Verify Installation

make ps      # Check services
make test    # Run tests
make logs    # View logs

5. Access Application

Service	URL	Notes
Web App	http://localhost:8000	Main application
API Docs	http://localhost:8000/docs	Swagger UI
Database	localhost:5432	postgres/postgres
Cache	localhost:6379	No password (dev)

6. Create Admin User

Set in .env:

ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-secure-password

Or use script:

./scripts/create_admin.sh

7. Import Quiz Data

Quiz data is imported through the admin dashboard: log in as the admin user (step 6), open the admin page, and use the IMPORT QUIZZES (JSON/ZIP) control. Files are uploaded from your machine, so no image rebuild is needed. The accepted JSON format is documented in IMPORT_FORMAT.md; quiz_data/TEMPLATE_singlelang.json and quiz_data/TEMPLATE_multilang.json are complete templates to copy from.

Note: the legacy CLI script scripts/import_quiz_questions.py predates the current quiz-keyed format (it reads a top-level category key) and its in-container invocation fails at startup, so it cannot import the shipped templates — use the admin dashboard import instead.

---

Operations Guide

Daily Operations

# Start/Stop
make up              # Start services
make down            # Stop services
make restart         # Restart all

# Logs
make logs            # All logs
make logs-web        # Web only
make logs-db         # Database only

# Shell Access
make shell           # Web container bash
make shell-db        # PostgreSQL CLI
make shell-cache     # Valkey CLI
make python          # Python REPL

Database Operations

# Migrations
make migrate                              # Run pending migrations
make migrate-create MSG="description"     # Create new migration
make migrate-down                         # Rollback one migration
make migrate-history                      # Show history

# Backup/Restore — full runbook: BACKUP_RESTORE.md
# Automated backups (database/quizzes/assets/leaderboard) run via the cron
# sidecar; configure cadence/retention in the admin ops console (/admin/ops).
./scripts/restore_database_backup.sh      # Restore DB artifact (.dump/.sql)
./scripts/restore_assets_backup.sh        # Restore media assets artifact (.zip)
# Ad-hoc manual dump (separate from the automated artifacts):
./scripts/backup_db.sh                    # Create backup
./scripts/restore_db.sh backup.sql.gz     # Restore such a manual backup

# Reset (WARNING: deletes all data)
make db-reset

Cache Operations

make cache-stats     # View statistics
make cache-keys      # List all keys
make cache-flush     # Clear all cache (WARNING)

Running Tests

Day-to-day test commands are consolidated in the Testing section below.

Code Quality

make format          # Format with black
make lint            # Lint with flake8

Code follows PEP 8 with 120 char line length. See app/LOGGING_STANDARDS.md for logging conventions.

Production Deployment

# Build AMD64 images on macOS
make build-prod

# On Linux server
cp .env.prod.example .env.prod
# Edit .env.prod with production values
make up-prod

---

Architecture

Development (macOS with Finch)

+---------------------------------------------+
|  Finch VM (ARM64 native)                    |
|  +---------------------------------------+  |
|  |  PostgreSQL 17 (ARM64) - Port 5432    |  |
|  +---------------------------------------+  |
|  +---------------------------------------+  |
|  |  Valkey 7 (ARM64) - Port 6379         |  |
|  +---------------------------------------+  |
|  +---------------------------------------+  |
|  |  Python 3.14 + FastAPI + Uvicorn      |  |
|  |  Hot-reload enabled - Port 8000       |  |
|  +---------------------------------------+  |
+---------------------------------------------+
         | Volume Mounts
    ./app, ./tests, ./alembic, ./scripts, ./tools
    (+ read-only test-support mounts; named volumes:
     screenshot_media, backups_data)

Production (Linux with Docker)

+---------------------------------------------+
|  Docker Engine (AMD64)                      |
|  +---------------------------------------+  |
|  |  PostgreSQL 17 - Persistent volume    |  |
|  +---------------------------------------+  |
|  +---------------------------------------+  |
|  |  Valkey 7 - Persistent volume         |  |
|  +---------------------------------------+  |
|  +---------------------------------------+  |
|  |  Python 3.14 + Gunicorn (4 workers)   |  |
|  |  Code baked in image                  |  |
|  +---------------------------------------+  |
+---------------------------------------------+

---

Project Structure

.
+-- app/
|   +-- main.py              # FastAPI application entry
|   +-- config.py            # Configuration management
|   +-- database.py          # Database connection
|   +-- errors.py            # Error handling
|   +-- models/              # SQLAlchemy models
|   +-- services/            # Business logic
|   +-- routes/              # API endpoints
|   +-- security/            # Auth, CSRF, rate limiting
|   +-- middleware/          # Security headers, logging
|   +-- static/              # CSS, JS, fonts
|   +-- templates/           # Jinja2 HTML templates
|   +-- translations/        # i18n support
+-- alembic/                 # Database migrations
+-- tests/                   # Test suite
+-- quiz_data/               # Quiz import templates
+-- scripts/                 # Utility scripts
+-- Dockerfile               # Multi-stage build
+-- docker-compose.yml       # Development setup
+-- docker-compose.prod.yml  # Production setup
+-- Makefile                 # Command shortcuts

---

Configuration

Environment Variables

Key variables in .env:

# Database
DATABASE_URL=postgresql+psycopg://postgres:postgres@db:5432/retro_quiz
DB_POOL_SIZE=20

# Cache
REDIS_URL=redis://cache:6379/0

# Security (CHANGE IN PRODUCTION)
SECRET_KEY=dev-secret-key-change-in-production
JWT_SECRET_KEY=jwt-secret-key-change-in-production

# Admin User
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme123

# Email (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
EMAIL_VERIFICATION_REQUIRED=true

# Analytics (optional)
GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
GOOGLE_ANALYTICS_ENABLED=false

Production Configuration

For production, ensure:

• Strong random values for SECRET_KEY and JWT_SECRET_KEY (64+ chars)
• Strong database and Redis passwords
• ENVIRONMENT=production
• Proper SMTP configuration for email verification

Generate secrets:

python -c "import secrets; print(secrets.token_urlsafe(64))"

---

Security

Implemented Security Measures

Authentication

• JWT tokens with configurable expiration
• bcrypt password hashing
• Session storage in Valkey with TTL
• Email verification support

Protection

• CSRF protection with token validation
• Rate limiting on sensitive endpoints
• Input validation and sanitization
• XSS and SQL injection prevention

Headers

• Content Security Policy (CSP)
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Strict-Transport-Security (production)
• Referrer-Policy

Rate Limits (canonical list; enforced in app/security/rate_limit.py and app/routes/auth.py)

• Registration: 3/hour per IP
• Login: 5/5min per IP
• Email verification: 10/5min per IP
• Social sign-in endpoints (initiate/callback/link): configurable via SOCIAL_RATE_LIMIT_*, default 5/5min per IP

---

API Reference

A curated reference for the core player, account, and common admin flows lives in API_DOCUMENTATION.md; the complete, always-current reference is the live OpenAPI documentation served at /docs (Swagger UI) and /redoc while the application is running.

---

Testing

The suite covers unit, integration, contract, and property-based tests. Run make test for the current count and results, make test-coverage for coverage. This is the canonical list of day-to-day test commands (referenced from the Operations Guide and tests/TEST_PATTERNS.md).

# Run all tests
make test

# With coverage
make test-coverage

# Specific file
finch compose exec web pytest tests/test_api_auth.py

# Specific test class, or tests selected by name
finch compose exec web pytest tests/test_services_quiz.py::TestQuizEngine
finch compose exec web pytest -k "test_login"

# By marker (registered markers: unit, property, slow, integration)
finch compose exec web pytest -m property
finch compose exec web pytest -m "not slow"

Test-suite conventions and Hypothesis profile tuning are documented in tests/TEST_PATTERNS.md.

---

Troubleshooting

Finch VM Issues

finch vm status              # Check status
finch vm stop && finch vm start  # Restart
finch vm remove && finch vm init # Reset

Container Issues

make ps                      # Check status
make logs                    # View errors
make restart                 # Restart services
make clean && make init      # Full reset

Database Issues

finch compose exec db pg_isready -U postgres
finch compose restart db

Cache Issues

finch compose exec cache valkey-cli ping
finch compose restart cache

Port Conflicts

Edit docker-compose.yml to change host ports:

ports:
  - "8001:8000"  # Use different host port

---

Additional Documentation

Document	Description
API_DOCUMENTATION.md	Core API flows (complete reference: live OpenAPI at /docs)
BACKUP_RESTORE.md	Backup & restore runbook (artifacts, offsite, alerting, DR)
IMPORT_FORMAT.md	Quiz JSON schema
SOCIAL_LOGIN_SETUP.md	Social login (OAuth) provider setup
scripts/README.md	Helper scripts
app/LOGGING_STANDARDS.md	Logging conventions
app/static/README.md	Frontend asset pipeline
tests/TEST_PATTERNS.md	Test suite patterns
docs/accessibility/theme-contrast.md	Theme contrast audit
docs/audit/ui-ux-audit-report.md	UI/UX audit report

---

License

MIT License - see LICENSE for details.

---

Development: Finch on macOS (ARM64) | Production: Docker Engine on Linux (AMD64)