Architecture

Walkup is a baseball walk-up song app with a React PWA frontend and a FastAPI backend.

System Overview

The frontend runs as a browser app and PWA.
The backend owns authentication, persisted app data, and media processing.
TeamSnap is the source of truth for teams, members, events, lineups, and availability.
The backend stores only app-owned data plus TeamSnap external IDs and tokens needed for the auth flow.

frontend/ contains the React application.
The app uses React Router for navigation and TanStack Query for server state.
TeamSnap data is loaded through the official JavaScript SDK from the browser after the backend provides an access token.
The UI includes player, gameday, and library views for clip management and gameday playback.
The home page is a lightweight landing page that orients users and links to the Library and Gameday views.
The app is shipped as a PWA with install and offline-prep behavior.

backend/ contains the FastAPI application.
The backend handles TeamSnap OAuth start, callback, and token refresh.
It manages session state, clip metadata, game assignment state, and normalized media storage.
Media files are stored in the backend-media Docker volume, mounted at /app/storage during development.

TeamSnap entities are not durably mirrored as first-class backend records.
App-owned records include media assets, clips, playback assignments, and related metadata.
Game-day clip pinning is modeled as app state that references TeamSnap game IDs and clip IDs.

Docker Compose is the normal development path.
The frontend is served separately through Vite in development.
The backend is run through FastAPI with Docker-managed local storage and Docker secrets for TeamSnap credentials.
README.md contains the setup steps and environment expectations.