trymeapp/README.md

# TryMe Gaming App.

![TryMe Logo](./2dlogo_medium_256x256.png)

## 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)
```bash
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)
```bash
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
```bash
venv/bin/pytest -v
```

---

## Project Layout

```text
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](./SETUP.md) for Auth0 and moderator configuration, [INSTALL.md](./INSTALL.md) for Helm and Docker operations, and [SYSTEM.md](./SYSTEM.md) for system architecture details.