43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
# 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.
|
|
- Clip and gameday reads are cached on the client with HTTP validators so the app can keep working when reception is poor or absent.
|
|
|
|
## Frontend
|
|
|
|
- `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.
|
|
- Read-only TeamSnap queries use a stale-while-revalidate cache in the browser so the UI can render immediately from stored data and update when a fresh response arrives.
|
|
- 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.
|
|
- Normalized playback media is cached by the service worker, and the backend marks those files cacheable while keeping auth/session responses `no-store`.
|
|
|
|
## Backend
|
|
|
|
- `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.
|
|
|
|
## Data Boundaries
|
|
|
|
- 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.
|
|
|
|
## Local Development
|
|
|
|
- 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.
|