Refactor code structure for improved readability and maintainability

2026-05-28 11:20:10 +05:00
parent d5a889ed6d
commit e48b1fc0e9
21 changed files with 171 additions and 1068 deletions
@@ -0,0 +1,26 @@
+# 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.