walkup/README.md

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