From bbf073c6aeee8cca2ff08f5dc4cb11cdeab5348b Mon Sep 17 00:00:00 2001 From: ThinkAI Readiness Date: Tue, 26 May 2026 17:31:46 +0000 Subject: [PATCH] chore(readiness): improve AI agent readiness --- .cursor/rules/backend-fastapi.mdc | 16 ++++++++++++++++ .cursor/rules/docker-compose.mdc | 17 +++++++++++++++++ .cursor/rules/frontend-react-bun.mdc | 15 +++++++++++++++ .cursor/rules/project-overview.mdc | 27 +++++++++++++++++++++++++++ 4 files changed, 75 insertions(+) create mode 100644 .cursor/rules/backend-fastapi.mdc create mode 100644 .cursor/rules/docker-compose.mdc create mode 100644 .cursor/rules/frontend-react-bun.mdc create mode 100644 .cursor/rules/project-overview.mdc diff --git a/.cursor/rules/backend-fastapi.mdc b/.cursor/rules/backend-fastapi.mdc new file mode 100644 index 0000000000..b3368c143a --- /dev/null +++ b/.cursor/rules/backend-fastapi.mdc @@ -0,0 +1,16 @@ +--- +description: Python FastAPI backend conventions (SQLModel, routes, migrations) +globs: backend/**/* +alwaysApply: false +--- + +# Backend (FastAPI + SQLModel) + +- App entry: `backend/app/main.py`; routers under `backend/app/api/routes/`, mounted in `app/api/main.py`. +- Use dependency types from `app/api/deps.py` (`SessionDep`, `CurrentUser`, etc.) instead of ad-hoc DB/session wiring. +- Models and Pydantic schemas live in `app/models.py`; persistence helpers in `app/crud.py`. +- Settings via `app/core/config.py` (`pydantic-settings`); never hardcode secrets. +- DB migrations: Alembic in `app/alembic/` — add revisions for schema changes; do not edit applied migration files. +- Lint/typecheck: Ruff + mypy (strict); run from `backend/` with `uv run ruff check app` / `uv run mypy app`. +- Tests mirror app layout under `backend/tests/`; use fixtures in `tests/conftest.py` and helpers in `tests/utils/`. +- Raise `HTTPException` for API errors; use SQLModel `select()` / `session.exec()` patterns consistent with existing routes. diff --git a/.cursor/rules/docker-compose.mdc b/.cursor/rules/docker-compose.mdc new file mode 100644 index 0000000000..ee9555143f --- /dev/null +++ b/.cursor/rules/docker-compose.mdc @@ -0,0 +1,17 @@ +--- +description: Docker Compose stack layout and local development commands +globs: compose*.yml +alwaysApply: false +--- + +# Docker Compose + +- `compose.yml` — base stack (db, backend, frontend, prestart, traefik labels). +- `compose.override.yml` — dev overrides (volume mounts, local Traefik); applied automatically with `compose.yml`. +- `compose.traefik.yml` — production Traefik; not used for simple local dev. +- Configuration flows from `.env`; restart after env changes: `docker compose watch`. +- Services: backend `:8000`, frontend `:5173`, Adminer `:8080`, Mailcatcher `:1080`. +- Run backend prestart/migrations via the `prestart` service; backend image built from `backend/Dockerfile`. +- Logs: `docker compose logs [service]`; stop a service to run it locally on the same port (see `development.md`). + +Do not commit production secrets in Compose files; use `.env` and documented env vars. diff --git a/.cursor/rules/frontend-react-bun.mdc b/.cursor/rules/frontend-react-bun.mdc new file mode 100644 index 0000000000..918322d9b2 --- /dev/null +++ b/.cursor/rules/frontend-react-bun.mdc @@ -0,0 +1,15 @@ +--- +description: React frontend with Bun, Vite, TanStack Router, and generated API client +globs: frontend/**/* +alwaysApply: false +--- + +# Frontend (React + Bun) + +- Package manager: **Bun** (`bun install`, `bun run dev`). Root `package.json` workspaces delegate to `frontend/`. +- Routes: TanStack Router in `frontend/src/routes/`; run dev server to regenerate `routeTree.gen.ts` — do not hand-edit it. +- UI: Tailwind + shadcn/ui components under `frontend/src/components/ui/`. +- API client is **generated** from OpenAPI (`frontend/src/client/`). Regenerate via repo-root `./scripts/generate-client.sh` after backend API changes. +- Lint/format: Biome — `bun run lint` in `frontend/`. +- E2E tests: Playwright in `frontend/tests/`; config in `playwright.config.ts`. Auth setup in `tests/auth.setup.ts`. +- Use existing hooks (`useAuth`, `useCustomToast`, etc.) and TanStack Query patterns already in the codebase. diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc new file mode 100644 index 0000000000..6e37b87b16 --- /dev/null +++ b/.cursor/rules/project-overview.mdc @@ -0,0 +1,27 @@ +--- +description: Full-stack template overview, safe AI conventions, and test entrypoints +alwaysApply: true +--- + +# Project overview + +Full-stack FastAPI template: Python API in `backend/`, React + Vite frontend in `frontend/`, orchestrated with Docker Compose. See `development.md` for local workflows. + +## Safe conventions for AI-assisted work + +- Never commit secrets: `.env`, generated keys, or credentials. +- Prefer minimal, focused diffs; do not remove unrelated code. +- After backend API/schema changes, regenerate the frontend client: `./scripts/generate-client.sh` (do not hand-edit `frontend/src/client/*`). +- Run linters via `uv run prek run --all-files` from repo root (or rely on pre-commit hooks). + +## Test entrypoints + +| Scope | Command | +|-------|---------| +| Full stack (CI-style) | `./scripts/test.sh` — builds Compose, runs backend pytest in container | +| Backend only (in Compose) | `docker compose exec backend bash scripts/tests-start.sh` | +| Backend pytest (local, in `backend/`) | `bash scripts/test.sh` (coverage + pytest on `tests/`) | +| Frontend E2E | `bun run test` (root) or `cd frontend && bun run test` | +| Frontend E2E UI mode | `bun run test:ui` | + +Local dev: `docker compose watch`; backend alone: `cd backend && fastapi dev app/main.py`; frontend alone: `bun run dev`.