# Agent Notes

## Repo Shape
- Monorepo split: `frontend/` is the React/Vite app; `services/bff/` owns auth, users, media upload, and frontend-facing API; `services/logic/` owns catalog, workouts, analytics, builtin seed data, and internal APIs.
- Python services are a uv workspace rooted at `services/`; use the shared `services/.venv`, not per-service virtualenvs.
- Keep dev tools (`ruff`, `ty`, `pytest`) in the `services` workspace dev group only. Docker runtime images must not run `uv run` or install dev tools.

## Commands
- Python setup: `cd services && uv sync --all-packages`.
- Python lint: `cd services && uv run ruff check bff logic`.
- Import-check services with the shared venv from each service dir, e.g. `services/.venv/bin/python -c "from app.main import app; print(app.title)"` with cwd `services/bff` or `services/logic`.
- Frontend uses pnpm `10.12.1`; if `pnpm` is unavailable, use `npx pnpm@10.12.1 ...`.
- Frontend checks from repo root: `npx pnpm@10.12.1 --filter train-watcher-frontend lint`, `typecheck`, and `build`.
- Full local stack: `docker compose -f infra/docker-compose.yml up --build`.

## Docker And Infra Gotchas
- Compose intentionally uses `host.docker.internal` for BFF/logic/Postgres/MinIO/frontend proxy paths; do not casually switch these back to service DNS names without testing Docker DNS on this machine.
- Backend Docker build context is `services/`, with `bff/Dockerfile` and `logic/Dockerfile`; both install runtime deps from `services/uv.lock` and start `/app/.venv/bin/uvicorn` directly.
- `services/.dockerignore` excludes `.venv`, `.ruff_cache`, `.pytest_cache`, `.ty`, and `__pycache__`; do not delete these local artifacts just to clean Docker contexts.
- MinIO uses the named volume `minio-object-data`; the older `minio-data` name was abandoned after corrupted local state.
- Frontend API base defaults to `/api`; `frontend/nginx.conf` proxies `/api/` to the BFF port.

## Backend Details
- Both Python apps auto-create SQLAlchemy tables on startup via `create_schema`; Alembic migrations exist but are not run by Compose startup yet.
- Logic internal endpoints require `X-Service-Token` and `X-User-Id`; BFF is responsible for supplying both.
- BFF stores uploaded images in MinIO/S3 and passes `image_s3_url` plus `image_s3_key` to logic catalog records.