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

• Authentic retro themes: C64, Amiga, Atari ST, ZX Spectrum, PET, GeoCities
• Modern theme option
• 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

finch compose exec web python scripts/import_quiz_questions.py quiz_data/*.json

---

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
./scripts/backup_db.sh                    # Create backup
./scripts/restore_db.sh backup.sql.gz     # Restore 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)

Testing

make test            # Run all tests
make test-coverage   # With coverage report

# Specific tests
finch compose exec web pytest tests/test_api_auth.py -v
finch compose exec web pytest -k "test_login" -v

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

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

• Registration: 3/hour per IP
• Login: 5/5min per IP
• API: 100/min per IP
• Question submission: 10/hour per user

---

API Reference

Public Endpoints

GET  /api/quizzes              # List quizzes
GET  /api/quizzes/{id}         # Quiz details
POST /api/sessions             # Create quiz session
GET  /api/sessions/{id}        # Session details
POST /api/sessions/{id}/answer # Submit answer
POST /api/sessions/{id}/submit # Complete quiz
GET  /api/leaderboard          # Leaderboard

Authenticated Endpoints

GET  /api/users/me             # Current user
GET  /api/users/me/preferences # User preferences
PUT  /api/users/me/preferences # Update preferences
GET  /api/users/me/history     # Quiz history
POST /api/questions/submit     # Submit question

Admin Endpoints

# Quiz Management
POST   /api/admin/quizzes
PUT    /api/admin/quizzes/{id}
DELETE /api/admin/quizzes/{id}

# Question Management
GET    /api/admin/questions
POST   /api/admin/questions
PUT    /api/admin/questions/{id}
DELETE /api/admin/questions/{id}

# User Management
GET    /api/admin/users
PUT    /api/admin/users/{id}/suspend
POST   /api/admin/users/bulk-approve

# Content Moderation
GET    /api/admin/flags
POST   /api/admin/flags/{id}/resolve

Full API documentation at /docs when running.

---

Testing

Test Status: 360 tests, 69% coverage

# Run all tests
make test

# With coverage
make test-coverage

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

# By marker
finch compose exec web pytest -m "not slow" -v

---

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	Complete API reference
IMPORT_FORMAT.md	Quiz JSON schema
RETRO_DESIGN_GUIDE.md	Theme design specs
SECURITY_FINDINGS.md	Security audit findings
scripts/README.md	Helper scripts

---

License

MIT License - see LICENSE for details.

---

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