TryMe Gaming App.

Purpose

TryMe is a student quiz creation and sharing web application where students build multiple-choice and write-in quizzes (0 to 40 questions on the public free tier), share direct quiz URLs with classmates, vote with thumbs up/down, pin and reorder favourite quizzes in a drag-and-drop right-hand rail, and compete on per-quiz leaderboards.

---

Key Features

• Federated Auth0 Login & Local Dev Mode: Sign in with federated IdPs via Auth0 OIDC/JWKS (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET), plus an optional DEV_AUTH_ENABLED local mode for instant development and automated testing.
• Student-Friendly Player Profiles:
  • Pick from 8 stylized geometric animal emblems (Fox, Owl, Bear, Otter, Koala, Tiger, Frog, Penguin) across 8 festive colorways.
  • Set a unique nickname, first_name, last_name, optional age (never asks for a birthday), inclusive gender options (including Non-binary, Two-Spirit, Agender, Genderqueer, Other / self-described, and Prefer not to say), and explicit confirmation of permission to use public websites.
• Multiple-Choice & Write-In Quizzes (0–40 Questions):
  • Combine multiple-choice and case-insensitive write-in questions (with optional accepted synonyms) up to 40 questions on the free tier.
  • Share any public quiz via /quiz/<share-slug>, vote thumbs up or down, and view your latest score, your all-time best, and the best score by anyone (with their nickname).
• Drag-and-Drop Favourites Rail + Pop-Up Recycle Bin:
  • Drag quiz cards from the main page into the right-hand Favourites pane, drag to reorder, or drag out of the pane onto the pop-up Recycle Bin (with one-click Undo and full keyboard accessibility).
• Personal API Keys: Generate tm_live_... API keys to access /api/v1/* programmatically and expire old keys immediately.
• Moderator Controls: Configured at launch (initial moderator claim) or via ADMIN_USER container variable to ban/restore users and remove inappropriate quizzes.

---

Quick Start

Run with Docker Compose (App + PostgreSQL 16)

docker compose up --build

Open http://localhost:8000 for the web app, http://localhost:8000/docs for Swagger UI, or http://localhost:8000/openapi.yaml for the OpenAPI 3.1 specification.

Run Locally (SQLite + Python Virtual Environment)

python3 -m venv venv
venv/bin/pip install -e ".[dev]"
venv/bin/alembic upgrade head

cd frontend && npm ci && npm run build && cd ..
SEED_STARTER_QUIZZES=true venv/bin/uvicorn app.main:app --port 8000

Run Automated Tests

venv/bin/pytest -v

---

Project Layout

trymeapp/
├── .gitea/workflows/cicd.yaml   # Harbor + DockerHub + Helm OCI CI/CD pipeline
├── .github/workflows/ci.yml     # GitHub Actions pytest, SPA, Docker & Helm CI
├── Dockerfile                   # Multi-stage Node 22 + Python 3.11 build
├── docker-compose.yaml          # App + PostgreSQL 16 stack (symlinked at docker-compose.yml)
├── version.ini                  # Root container & API version (0.1)
├── openapi.yaml                 # OpenAPI 3.1 specification
├── alembic.ini / alembic/       # Database schema migrations
├── app/                         # FastAPI application, Auth0/API key auth, routers & models
├── frontend/                    # React 19 + TypeScript + Vite SPA (Hallmark Hum theme)
├── helm-chart/                  # Kubernetes Deployment, Service, Ingress & SQLite PVC
├── tests/                       # Pytest test suite
├── SETUP.md                     # Auth0, Moderator, Database & API Key setup guide
├── INSTALL.md                   # Operator installation, Helm & CI secrets reference
└── SYSTEM.md                    # Architecture & data flow design document

See SETUP.md for Auth0 and moderator configuration, INSTALL.md for Helm and Docker operations, and SYSTEM.md for system architecture details.