Add repo docs for agent guidance

docs/architecture.md

@@ -0,0 +1,38 @@
+# 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 session flow.
+
+## 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.
+- The UI includes player, operator, and library views for clip management and gameday playback.
+- The app is shipped as a PWA with install and offline-prep behavior.
+
+## 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 locally in the backend storage path 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 local storage and Docker secrets for TeamSnap credentials.
+- `README.md` contains the setup steps and environment expectations.