# Repository Guidelines

## Project Structure & Module Organization
- Monorepo managed by Yarn workspaces (Node >= 20).
- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).
- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.
- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.
- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.
- Autogenerated types (do not manually edit these files):
  - valhalla/jawn/src/tsoa-build/
  - web/lib/clients/jawnTypes/
  - bifrost/lib/clients/jawnTypes/
  - worker/supabase/database.types.ts
  - web/db/database.types.ts
  - helicone-cron/src/db/database.types.ts
  - valhalla/jawn/src/lib/db/database.types.ts

## Build, Test, and Development Commands
- Install deps: `yarn`
- Lint all: `yarn lint` • Fix: `yarn lint:fix`
- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`
- Bifrost: `yarn workspace bifrost dev`
- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`
- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`
- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)
- Python integration: `python tests/python_integration_tests.py`

## Coding Style & Naming Conventions
- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.
- ESLint required; fix warnings before PRs.
- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.
- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.

## Testing Guidelines
- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.
- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).
- Run affected workspace tests locally before opening a PR.

## Commit & Pull Request Guidelines
- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.
- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.
- Checks must pass: lint, build for touched workspaces, and relevant tests.

## Security & Configuration Tips
- Never commit secrets. Use `.env.example` as a template.
- Web envs: `vercel env pull` or maintain `.env.local` locally.
- Worker secrets: `wrangler secret put <NAME>`.
- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.

## Agent-Specific Notes
- Scope changes to the smallest relevant workspace.
- Prefer `yarn workspace <name> <cmd>`; avoid modifying unrelated packages.
- Keep code style consistent; run `yarn lint` and add targeted tests.