73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# 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)
|
||
```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.
|