Skip to content

agent.md

Latest commit

 

History

History
63 lines (48 loc) · 2.45 KB

agent.md

File metadata and controls

63 lines (48 loc) · 2.45 KB

Repository Guidelines (Agent-Facing)

Project Structure

  • app/ FastAPI backend (Python package with main.py, routers/, services/, schemas/, middleware/).
    • routers/ HTTP surfaces
    • services/ business logic
    • schemas/ Pydantic models
    • middleware/ cross-cutting policies
  • alembic/ DB migrations
  • scripts/ seeds & utilities
  • admin/ Vite + React admin dashboard (src/components, src/pages, src/lib, src/test)
  • app/ Vite + React tenant app (Node toolchain lives alongside the backend package; run frontend commands from this folder)
  • landing/ Vite marketing site (Next.js variant lives in landing/nextjs-landing)
  • docs/, docs-site/, samples/, sdks/

Local Commands

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

Style & Naming

  • Python: PEP8, four spaces, black, ruff; snake_case functions, PascalCase classes/schemas
  • TS/React: Components/pages PascalCase; hooks start with use; shared helpers in src/lib

Testing

  • Backend 90% statements / 80% branches; security middleware covered in tests/test_middleware_security.py
  • Fixtures in tests/conftest.py; keep DEMO_MODE=false and dont set OPENAI_API_KEY in CI
  • Frontend: vitest with coverage (admin/coverage)

Security & Config

  • Start from .env.example; never commit secrets
  • ENV must be production in prod (code reads ENV=production)
  • Keep DEMO_MODE=false
  • Dont put secrets in Vercel frontends

Deployment Rules (Monorepo)

  • Vercel projects must set Root Directory to the app folder:
    • rulhub landing (Vite marketing)
    • rulhub-admin admin (Vite admin dashboard)
    • rulhub-app app (Vite tenant UI)
  • Never point a Vercel project at repo root or use FastAPI preset for frontends
  • Backend deploys to Render only (uvicorn app.main:app)

Migrations

  • Alembic ops must be idempotent (check pg_constraint before creating constraints).

  • Example helper:

    def constraint_exists(conn, name):
    return bool(conn.exec_driver_sql(
        "SELECT 1 FROM pg_constraint WHERE conname=%s", (name,)
    ).fetchone())