# 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, local object-style file storage

## 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 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.

## 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 operator session APIs

## Frontend Responsibilities
- TeamSnap SDK bootstrap with server-issued access tokens
- Team/game browsing from TeamSnap
- Song upload and clip creation
- Game assignments and operator console
- PWA install/offline shell