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.

docs/coding-standards.md

@@ -0,0 +1,42 @@
+# Coding Standards
+
+These rules apply to Walkup-specific work in this repository.
+
+## General
+
+- Prefer the smallest change that fully solves the problem.
+- Preserve existing behavior unless the task explicitly requires a change.
+- Keep control flow straightforward and naming explicit.
+- Avoid broad refactors unless they are necessary to complete the task.
+
+## Frontend
+
+- Match the existing Bootstrap-based UI patterns.
+- Use Bootstrap Icons for iconography rather than custom SVG drawing.
+- Keep interactive controls readable and compact, especially in menus and toolbars.
+- Prefer UI changes that fit the current layout and spacing conventions.
+
+## Backend
+
+- Keep route handlers thin and push shared logic into helper functions when it improves clarity.
+- Treat tests as part of the implementation for non-trivial behavior changes.
+- Preserve API shape unless the change requires a contract update.
+
+## Testing
+
+- Add or update tests for user-visible behavior changes.
+- Run the smallest useful verification first, then broader checks for the touched area.
+- If a change cannot be covered automatically, call out the gap clearly.
+
+## Git And Workflow
+
+- Work on a dedicated branch for a scoped change.
+- Use the `Codex <codex@local>` identity for agent-authored commits.
+- Keep commits focused and reviewable.
+- Do not mix unrelated changes into the same commit.
+
+## Docs
+
+- Keep `docs/architecture.md` aligned with the current app structure.
+- Keep `docs/coding-standards.md` aligned with actual repo practice.
+- Update `PLAN.md` when work is completed, deferred, or split.