Repository Guidelines

Project Structure & Module Organization

This repository is organized as a monorepo with product-facing apps at the top level:

• apps/control-plane/: FastAPI service (apps/control-plane/app) and backend tests (apps/control-plane/tests). Control-plane architecture is feature-module based under apps/control-plane/app/modules; see apps/control-plane/AGENTS.md for backend-specific layering and dependency rules.
• apps/web/: Next.js App Router app with thin route entrypoints in apps/web/app and layered product code in apps/web/src. Frontend architecture follows app -> widgets -> features -> entities -> shared; see apps/web/ARCHITECTURE.md and apps/web/AGENTS.md for the current layering and ownership rules.
• packages/: shared contracts and SDK scaffolds for cross-plane reuse.
• runtimes/: runner scaffolds for framework-specific execution adapters.
• docs/, infra/, and schemas/: architecture docs, deployment assets, and neutral schema definitions.
• apps/web/test: Vitest + React Testing Library test files for UI and logic.
• apps/control-plane/.venv, apps/control-plane/.uv_cache, apps/web/node_modules, apps/web/.next, package/runtime .venv directories, and local CI artifacts such as .phoenix/ or apps/control-plane/.agent-atlas-*.db are generated and should not be committed.

Build, Test, and Development Commands

• Control-plane setup and checks (run in apps/control-plane/):
  • make install — sync runtime + dev dependencies for local development.
  • make sync — recreate the backend environment from uv.lock for reproducible CI/local bootstrap.
  • make fmt — run Ruff formatter and Python compile check.
  • make lint — run Ruff lint/format checks.
  • make typecheck — run mypy on app/.
  • make test — run unit tests plus non-workflow integration tests without the coverage gate for fast local verification.
  • make test-workflow — run long-running backend workflow tests for experiment, validation, and export loops.
  • make test-check — run pytest with coverage checks (--cov-fail-under=70).
  • make security — run Bandit scan on backend code.
  • uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 — start API locally.
• Web app setup and checks (run in apps/web/):
  • npm install — install JS dependencies.
  • make install-ci — install frontend dependencies with npm ci for reproducible CI runs.
  • npm run dev — run Next.js dev server on http://localhost:3000.
  • npm run lint — run ESLint.
  • npm run typecheck — run TypeScript strict check (tsc --noEmit).
  • npm run test — run Vitest suite.
  • npm run build — production build.
  • make ci — run the frontend CI bundle (lint + typecheck + coverage + build).
  • npm run verify:full — run the local full frontend verification bundle, including Playwright e2e.
• Root monorepo checks (run in repository root):
  • make lint — run repo-wide lint and syntax checks across apps, shared packages, and runtimes; local runs default to serial orchestration.
  • make typecheck — run all defined type checks; local runs default to serial orchestration.
  • make test — run app tests and shared package/runtime smoke checks; local runs default to serial orchestration.
  • make build — build the frontend and Python package distributions; local runs default to serial orchestration.
  • make ci-packages — validate shared packages and runtimes.
  • make ci — run full monorepo CI coverage across backend, frontend, shared packages, and runtimes; local runs default to serial orchestration.

Coding Style & Naming Conventions

• Python: 4-space indentation, LF line endings, quote-style double, line length 100 (ruff config).
• TypeScript/React: 2-space indentation, strict TypeScript enabled, Prettier + ESLint formatting.
• Naming: Python uses snake_case for functions/modules/variables, PascalCase for classes; frontend uses camelCase for hooks/functions and PascalCase for React components/files.
• Keep API payload mapping explicit and deterministic; avoid implicit schema guessing.

Testing Guidelines

• Backend tests use pytest; put backend tests under apps/control-plane/tests with test_*.py.
• Frontend tests use Vitest + React Testing Library; test files are *.spec.ts, *.spec.tsx, *.test.ts, *.test.tsx (covered by apps/web/vitest.config.ts).
• Frontend unit/integration tests live under apps/web/test, while Playwright e2e tests live under apps/web/e2e.
• Frontend coverage defaults to app/**/* and src/**/*.
• Generated test artifacts such as __pycache__/, *.pyc, coverage output, build output, .next/, and node_modules/ are not part of the committed test structure.
• Run at least make test and npm run test before opening a PR.

Commit & Pull Request Guidelines

The root and both subdirectories currently have no git history on master, so there is no local convention to infer. Use Conventional Commits now (feat:, fix:, refactor:, test:).

• PRs should include what changed, why, related issue/task link, and command outputs (make test, npm run test, make lint / npm run lint, make typecheck / npm run typecheck).
• For UI work, include relevant screenshots or short screen recordings.
• For API changes, include example request/response payloads and affected endpoints.

Security & Configuration Tips

• Copy apps/control-plane/.env.example to apps/control-plane/.env and configure environment values before running.
• Set NEXT_PUBLIC_API_BASE_URL in frontend when backend URL is not http://127.0.0.1:8000.
• Do not commit secrets, local database dumps, or generated artifacts.