Skip to content

AGENTS.md

Latest commit

 

History

History
42 lines (35 loc) · 3.2 KB

AGENTS.md

File metadata and controls

42 lines (35 loc) · 3.2 KB

Repository Guidelines

Project Structure & Module Organization

  • app/ hosts the FastAPI backend; use routers/ for HTTP surfaces, services/ for business rules, schemas/ for Pydantic models, and middleware/ for cross-cutting policies.
  • tests/ mirrors backend domains; shared fixtures live in tests/conftest.py (SQLite seeds, feature toggles).
  • admin/ contains the Vite + React dashboard (src/components, src/pages, src/lib, src/test).
  • Data migrations sit in alembic/ (managed via alembic.ini); seed scripts and utilities reside in scripts/.
  • Documentation, SDKs, and samples live under docs/, docs-site/, samples/, and sdks/.

Build, Test, and Development Commands

  • Backend bootstrap: python -m venv venv && pip install -r requirements.txt && alembic upgrade head.
  • Local API: uvicorn app.main:app --reload.
  • Backend checks: coverage run --branch -m pytest -q && coverage report --fail-under=90.
  • Frontend loop: cd admin && npm install && npm run dev.
  • Frontend quality gates: npm run lint, npm test, npm run build.

Coding Style & Naming Conventions

  • Python: PEP 8, four-space indentation, 79-char width (black), lint with ruff.
  • Naming: modules/functions in snake_case, classes and schemas in PascalCase, async endpoints declare explicit return annotations.
  • TypeScript: components and pages in PascalCase; hooks begin with use; shared helpers belong in admin/src/lib.

Testing Guidelines

  • Backend: run coverage run --branch -m pytest -q; maintain >=90% statements and >=80% branches. Security middleware coverage comes from tests/test_middleware_security.py.
  • Fixtures: import from tests/conftest.py; keep DEMO_MODE=false and OPENAI_API_KEY unset for deterministic runs.
  • Frontend: npm test -- --coverage (Vitest writes results to admin/coverage/).

Commit & Pull Request Guidelines

  • Commits are imperative, e.g., Add rule taxonomy and align tests; squash WIP commits before merging.
  • PRs document scope, database or seed impacts, and list local verification (backend coverage, frontend lint/tests).
  • Link related issues and attach UI evidence when relevant; wait for backend, frontend, and security CI jobs.

Security & Configuration Tips

  • Start from .env.example; never commit secrets. Default to ENVIRONMENT=production to keep DEMO_MODE=false.
  • Leave OPENAI_API_KEY blank unless you are testing LLM flows.
  • After dependency updates, run bandit -r app and safety check.

2025-10-22 Audit Notes

  • Harden the API key middleware by removing the X-API-Key-Prefix response header in app/middleware/api_key_security.py and backfilling coverage that enforces header expectations.
  • Document production Redis and queue requirements so the startup checks in app/main.py do not fail during deployments; codify in IaC or ops runbooks.
  • Drop committed bundles under admin/dist/ and ensure the directory stays ignored to avoid stale assets drifting from source.
  • Close open TODOs in app/services/version_service.py around cloning and audit logging to make version promotions observe full change history.
  • Hide or complete the marketing placeholder routes (admin/src/marketing/pages/*) to prevent dead-end navigation in the admin shell.