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.

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.

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.

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.