72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# WalkUp
|
|
|
|
WalkUp is a collaborative baseball walk-up song app built as a React PWA with a FastAPI backend. The browser integrates with TeamSnap through the official JavaScript SDK, while the backend keeps TeamSnap secrets and only stores app-owned media and game state.
|
|
|
|
## Stack
|
|
- Frontend: React, TypeScript, Vite, React Router, TanStack Query, `teamsnap.js`, `vite-plugin-pwa`
|
|
- Backend: FastAPI, SQLAlchemy, Pydantic Settings, HTTPX
|
|
- Infra: Docker Compose, Postgres, named Docker volume for backend media
|
|
|
|
## Repository Layout
|
|
- `frontend/`: React PWA
|
|
- `backend/`: FastAPI API and storage logic
|
|
- `PLAN.md`: current implementation scope snapshot
|
|
|
|
## Local Development
|
|
1. Copy `.env.example` to `.env`.
|
|
2. Create and activate the host virtualenv if needed:
|
|
`python3 -m venv .venv && source .venv/bin/activate`
|
|
3. Install backend dependencies:
|
|
`pip install -r requirements.txt`
|
|
4. Create `secrets/teamsnap_client_id.txt` and `secrets/teamsnap_client_secret.txt`.
|
|
5. Put the raw TeamSnap client ID and client secret values into those files.
|
|
6. Generate the local TLS certificate and key:
|
|
`./scripts/create-dev-certs.sh`
|
|
7. Start the stack and capture logs:
|
|
`./scripts/dev-up.sh`
|
|
8. Open `https://kif.local.ascorrea.com`.
|
|
|
|
## Dev Logs
|
|
- `./scripts/dev-up.sh` starts the stack with the `dev` profile and appends compose output to `logs/docker-compose.log`.
|
|
- `./scripts/dev-logs.sh` captures current service logs to `logs/docker-services.log`.
|
|
- Use those files when you want me to inspect startup failures or runtime errors from the Docker stack.
|
|
|
|
## Production
|
|
- Copy `compose.traefik.yml.sample` to `compose.traefik.yml` and adjust it for your deployment.
|
|
- The sample routes `backend` and `frontend` through Traefik, builds the frontend as a static Nginx image, and keeps the published ports off the host.
|
|
- `./scripts/prod-up.sh` starts `db`, `backend`, and `frontend` in detached mode with that Traefik override.
|
|
- Use `docker compose logs db backend frontend` when you need live service output from that detached stack.
|
|
|
|
## TeamSnap Secrets
|
|
- TeamSnap credentials are expected through Docker secrets, not plain environment variables.
|
|
- The backend reads `/run/secrets/teamsnap_client_id` and `/run/secrets/teamsnap_client_secret` by default.
|
|
- `.env` keeps only the secret file paths, not the credential values.
|
|
- Direct env var fallback still exists in code for non-Docker debugging, but the intended runtime path is Docker secrets.
|
|
|
|
## Local HTTPS Proxy
|
|
- Local development uses a Caddy reverse proxy at `https://kif.local.ascorrea.com`.
|
|
- TeamSnap callback should be registered as `https://kif.local.ascorrea.com/api/auth/teamsnap/callback`.
|
|
- The proxy forwards `/api/*` to FastAPI and all other routes to the Vite frontend.
|
|
- The proxy binds host ports `80` and `443` by default.
|
|
- If those ports are already in use, set `PROXY_HTTP_PORT` and `PROXY_HTTPS_PORT` in `.env`.
|
|
- The backend session cookie is secure-capable so the local flow matches production proxy behavior.
|
|
- The hostname is configurable through `APP_HOST`, but the default is `kif.local.ascorrea.com`.
|
|
- Generate the local cert/key with `./scripts/create-dev-certs.sh`, which uses `mkcert` and the current `APP_HOST`, or create them manually and place the outputs in:
|
|
- `secrets/dev-proxy-cert.pem`
|
|
- `secrets/dev-proxy-key.pem`
|
|
- Make sure `kif.local.ascorrea.com` resolves to your Docker host on your LAN before testing from other devices.
|
|
|
|
## Backend Responsibilities
|
|
- TeamSnap OAuth start/callback/refresh
|
|
- Session cookie management
|
|
- Media upload and normalized clip registration
|
|
- Game assignments and gameday APIs
|
|
|
|
## Frontend Responsibilities
|
|
- TeamSnap SDK bootstrap with server-issued access tokens
|
|
- Team/game browsing from TeamSnap with cached-first revalidation
|
|
- Song upload and clip creation
|
|
- Game assignments and gameday console
|
|
- PWA install/offline shell
|
|
- Read-only offline clip cache with HTTP revalidation and cached normalized playback media
|