# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Install all dependencies (Python + frontend)
make install

# Local development (API on :8000, Vite on :5173 in parallel)
make dev
make dev-api        # FastAPI only
make dev-dashboard  # Vite only

# Build frontend (output → static/dashboard/)
make build-dashboard

# Type checking (ty for Python, tsc for frontend)
make typecheck

# Lint (ruff + biome check)
make lint

# Auto-format (ruff + biome)
make fmt

# Tests
make test
uv run pytest tests/path/to/test_file.py::test_name  # single test

# Docker
make docker-up      # build image + run via compose on :8080
make docker-down
PORT=9000 make docker-up
```

## Architecture

**Monorepo layout**: Python backend (`src/`) + React dashboard (`dashboard/`). The frontend is served by FastAPI in production; in dev, Vite runs separately on `:5173` and proxies `/api` to FastAPI on `:8000`.

### Backend (`src/resonance_engine/`)

- **`config.py`** — single `Settings` class (pydantic-settings). All env vars come from here. Includes `logging_config` property that wires up Rich (dev) and JSON/Datadog (prod) handlers. Every new `Field(..., validation_alias="VAR")` must also be added to `.env.example`.
- **`api/app.py`** — `get_app()` factory. Register new API routers here **before** the dashboard catch-all. Mount order matters: static assets → API routers → dashboard SPA catch-all (last).
- **`api/routers/dashboard.py`** — serves the built Vite SPA. Falls back to `index.html` for all unmatched paths (client-side routing). Returns 503 with instructions if `static/dashboard/` doesn't exist.
- **`cli/`** — Typer-based CLI, entry point via `python -m resonance_engine.cli`.
- **`runtime/`** — background task handlers (stub, to be expanded).

### Frontend (`dashboard/`)

React + Vite + TypeScript. Tooling: Biome for lint/format, `tsc -b` for type checking. Bun is the package manager (`bun install`, `bun run <script>`).

Vite builds to `../static/dashboard/` (relative to `dashboard/`) with `manifest: true`. FastAPI mounts `static/dashboard/assets/` at `/assets` and serves `index.html` for all other routes.

### Settings reference

| Env var | Default | Purpose |
|---|---|---|
| `ENVIRONMENT` | `dev` | `dev` / `staging` / `production` |
| `APP_DEBUG` | `false` | FastAPI debug mode |
| `LOGGING_DEBUG` | `false` | Rich console logging |

### Adding postgres/redis

`compose.yml` has commented-out `postgres` and `redis` service blocks with healthchecks. Uncomment them, uncomment `depends_on` in the `api` service, and add connection env vars to `.env.example`.