Merge pull request #98 from chirpz-ai/dashboard

Dashboard

Author: sinatayebati

backend/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+The repo-wide `CLAUDE.md` at the project root covers monorepo layout, the two-plane API model, backend domain layering, and shared conventions. This file adds the backend-specific details that are easy to get wrong without reading several files.
+
+## Commands
+
+All targets are exposed at the repo root (`make backend-*`) and as host-side targets in `backend/Makefile`. From inside `backend/`:
+
+| Goal | Command |
+|---|---|
+| Install (locked) | `uv sync --frozen` |
+| API server (host) | `make dev` — uvicorn on `:8000` with reload, `APP_ENV=development` |
+| Celery worker (host) | `make worker` — needs Redis on `:6379` and Postgres on `:5432` |
+| Lint / format | `make lint` / `make format` (ruff over `app/` and `tests/`) |
+| Unit tests (host, no infra) | `make test-unit` (or `uv run --group test pytest tests/unit/ -v`) |
+| Single unit test | `uv run --group test pytest tests/unit/test_traces.py::test_name -v` |
+| Integration tests | From repo root: `make test-integration` — spins up `docker-compose.test.yml` (Postgres :5433, Redis :6380), runs `tests/integration/`, tears down with `-v` |
+| New migration | `make migration msg="describe change"` — runs `alembic revision --autogenerate` against **local** Postgres on `:5432` |
+| Apply migrations | `make migrate` (auto-applied on `make up` via Docker entrypoint) |
+
+To run integration tests against an already-running test stack: set `POSTGRES_PORT=5433 POSTGRES_DB=pandaprobe_test_db REDIS_PORT=6380` and run `pytest tests/integration/`. `tests/conftest.py` already wires these env vars + `APP_ENV=test` + `CELERY_TASK_ALWAYS_EAGER=true`.
+
+## Two auth dependencies — pick the right one
+
+`app/api/dependencies.py` exposes three dependencies. Routes must pick deliberately:
+
+- `get_api_context` — **management plane**. Bearer JWT only. Use for `/user`, `/organizations`, `/projects`, `/api-keys`, `/subscriptions`. Returns `ApiContext` with `organization` always set and `project` always `None`.
+- `get_data_plane_context` — **data plane**. Accepts Bearer JWT (with `X-Project-ID`) **or** `X-API-Key` (with `X-Project-Name`). **When both are sent, API key wins** — this is intentional to prevent failures when Swagger UI sends a stale JWT alongside a valid key.
+- `require_project` — thin wrapper around `get_data_plane_context` that 422s if `ctx.project is None`. Use this on every `/traces`, `/sessions`, `/evaluations` handler.
+
+`_resolve_jwt` JIT-provisions: upserts the user from the IdP claims, auto-creates "My Organization" on first sign-in (plan = DEVELOPMENT when auth is disabled, else default tier), and on new-user creation enqueues welcome/follow-up emails + CRM sync via Celery. Routes get the resolved org/user via `ApiContext` — they should never re-query identity themselves.
+
+`_resolve_api_key` resolves projects by *name* within the API key's org and **auto-creates the project if missing**. This is why SDK clients can call `POST /traces` with any new `X-Project-Name`.
+
+## Celery worker: NullPool + per-task asyncio.run
+
+`app/infrastructure/queue/tasks.py` has a critical pattern documented in its module docstring — don't deviate:
+
+- Worker uses a **dedicated `NullPool` engine** (`_worker_engine`), not the request-path pool from `infrastructure/db/engine.py`. Every task creates a fresh connection via `_worker_session()` and discards it. Reusing a pooled connection across `asyncio.run()` calls causes `"attached to a different loop"` errors because each `asyncio.run()` creates a new event loop.
+- Each Celery task body is a sync function that immediately calls `asyncio.run(_async_helper(...))`. Don't add async Celery tasks — use this pattern.
+- **Heavy imports go inside the task function**, not at module top. This keeps worker bootup fast and avoids importing FastAPI/auth code into the worker process.
+
+### Dispatcher + per-org worker fanout
+
+For periodic jobs that touch many orgs (usage sync, overage billing, eval monitors), the pattern is **one dispatcher task that queries eligible IDs and fans out one sub-task per org/monitor**:
+
+- `dispatch_sync_usage` → fans out `sync_single_org_usage(org_id)` per active org
+- `dispatch_overage_billing` → fans out `bill_single_org(org_id)` per paid active org (rate-limited to `80/s` to stay under Stripe's `100/s` live cap)
+- `dispatch_hobby_reset` → fans out `reset_single_hobby_org(org_id)`
+- `check_eval_monitors` → fans out `process_single_monitor(monitor_id, project_id)` (and uses a Redis lock `check_eval_monitors` with `timeout=60` so only one beat worker drives the tick)
+
+When adding new periodic work, follow the same shape — failures stay isolated to a single org, and workers parallelise across slots.
+
+### Beat schedule
+
+Configured in `infrastructure/queue/celery_app.py` using `RedBeatScheduler` (Redis-backed; no on-disk schedule file). Current cadence: eval monitors and usage sync every 5 min; overage billing and hobby reset every 6 hours; invitation expiry every hour.
+
+## Auth adapter selection
+
+`infrastructure/auth/adapters.py::get_auth_adapter()` dispatches:
+- `AUTH_ENABLED=false` → `DevelopmentAdapter` (no-op JWT verify, returns a fixed dev identity). Allowed **only** in `APP_ENV=development` — `Settings._apply_environment_settings` forces `AUTH_ENABLED=true` everywhere else and logs an override warning.
+- `AUTH_PROVIDER=firebase` → `FirebaseAdapter` (uses Firebase Admin SDK + ADC; `GOOGLE_CLOUD_PROJECT` required)
+- `AUTH_PROVIDER=supabase` (default) → `SupabaseAdapter` (uses `SUPABASE_URL` + `SUPABASE_KEY`)
+
+Adapters expose a single `verify_token(token) -> Claims` method called via `asyncio.to_thread` since IdP SDKs are sync.
+
+## Settings: env-aware defaults
+
+`Settings._apply_environment_settings` (`app/registry/settings.py`) overrides `DEBUG`, `LOG_LEVEL`, `LOG_FORMAT` per environment **only when the env var is not explicitly set**. So `LOG_LEVEL=DEBUG` in `.env.production` would still win, but the default behaviour gives you JSON `WARNING` logs in prod and console `DEBUG` logs in dev.
+
+The lifespan in `main.py` calls `_validate_stripe_settings()` which **fails fast at startup** if `STRIPE_SECRET_KEY` or `STRIPE_WEBHOOK_SECRET` are missing in staging/production. Don't gate this behind a flag — it's intentional.
+
+## Domain errors, not HTTPException
+
+Raise subclasses of `PandaProbeError` (`registry/exceptions.py`) — `NotFoundError`, `AuthenticationError`, `AuthorizationError`, `ConflictError`, `ValidationError`, `QuotaExceededError`, `OrgLimitReachedError`. The handler in `main.py` translates them to `{"detail": "..."}` JSON with the right status code. Routes that raise `HTTPException` directly bypass this and break the error contract — use the domain exceptions.
+
+Pydantic request-body validation errors are reshaped by `validation_exception_handler` into `{"detail": "Validation error", "errors": [{field, message}, ...]}` — clients depend on this shape.
+
+## Domain entities vs ORM models
+
+Repositories in `infrastructure/db/repositories/` return **core domain entities** (Pydantic models in `app/core/*/entities.py`), not SQLAlchemy `*Model` rows. Services and routes only see entities. If you add a column to a `*Model`, also add it to the entity and the repo mapping — otherwise the field is invisible to callers.
+
+`get_db_session` (`infrastructure/db/engine.py`) is the per-request session dependency. It auto-`commit()`s on success and `rollback()`s on exception. Don't sprinkle `await session.commit()` at the end of route handlers — let the dependency handle it. Workers, in contrast, **must** commit explicitly because they don't go through this dependency.
+
+## Integration test mechanics
+
+`tests/integration/conftest.py` does several non-obvious things — read it before writing new integration tests:
+
+- **`nest_asyncio.apply()`** at import time so Celery's `asyncio.run(...)` works inside the pytest-asyncio loop (eager mode).
+- **TRUNCATE-based isolation**, not transaction rollback. The Celery task creates its own session/connection (matching real worker behaviour), so wrapping each test in a transaction would hide its commits from the test code. After each test, every table is `TRUNCATE ... CASCADE`d and the async engine pool is `dispose()`d so pooled connections don't leak into the next test's event loop.
+- **Fixed seed UUIDs** (`TEST_ORG_ID`, `TEST_PROJECT_ID`) so every fixture in a test shares the same identity.
+- **`autouse` dep overrides** replace `get_db_session`, `require_project`, and `get_redis` for every test. The overridden `require_project` returns a pre-built `ApiContext` — no auth roundtrip.
+- **Redis `FLUSHDB`** runs at the end of every test so rate-limiter counters, eval locks, and usage counters don't bleed across tests.
+
+If you need a test that exercises auth resolution itself (not bypassing it), override only `get_db_session` and `get_redis` and let `require_project` run for real.
+
+## Conventions
+
+- Ruff: `line-length = 119`, Google docstrings (`D`), `B`/`ERA` rules on. `D203`/`D213`/`B904`/`B008`/`D107`/`E501`/`F401` are intentionally ignored. `unfixable = ["B"]` — bugbear findings are surfaced but not auto-fixed.
+- `tests/*` get `D100`/`D103`/`D104` waived; `__init__.py` files get `E402`/`D104` waived.
+- API keys are stored hashed (`registry/security.py::hash_api_key`); never log or persist the raw key — only the prefix shown in `IdentityRepository`.
+- New tables / column changes require an Alembic migration **and** an updated ORM model. `migration` runs autogenerate against the local Postgres on `:5432` — bring up `make up` (or just the postgres service) first.
+- The only required runtime env vars in dev are Postgres/Redis connection vars; LLM, Stripe, Resend, Attio, PostHog keys are all optional and the corresponding services no-op when unset (`is_configured()` checks).

frontend/CLAUDE.md

@@ -1 +1,66 @@
-@AGENTS.md
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+The repo-wide `CLAUDE.md` at the project root covers monorepo layout, the two-plane API model, backend architecture, and a high-level frontend overview. This file adds the frontend-specific details that are easy to get wrong without reading several files.
+
+## Commands
+
+All targets are exposed at the repo root (`make frontend-*`) and as host-side targets in `frontend/Makefile`. From inside `frontend/`:
+
+| Goal | Command |
+|---|---|
+| Install (locked) | `yarn install --frozen-lockfile` |
+| Dev server (host) | `yarn dev` — runs Next.js on `:3000` against `NEXT_PUBLIC_API_URL` |
+| Production build | `yarn build` (uses `output: "standalone"` from `next.config.ts`) |
+| Lint / autofix | `yarn lint` / `yarn lint:fix` |
+| Type check | `yarn typecheck` (`tsc --noEmit`) |
+| Format | `yarn format` (write) / `yarn format:check` (CI gate) |
+| Unit tests | `yarn test` (Jest + jsdom) |
+| Single Jest test | `yarn test src/__tests__/lib/api/traces.test.ts` (or pass `-t "name"`) |
+| E2E (Playwright) | `yarn playwright install --with-deps` once, then `yarn test:e2e` |
+
+Playwright's `webServer` runs `yarn dev` on `:3000` and reuses an existing server outside CI — leaving `yarn dev` running while you iterate on E2E is fine.
+
+## Routing model (App Router)
+
+Authenticated UI lives under `src/app/org/[orgId]/project/[projectId]/{traces,sessions,evaluations,analytics}`. Org-level pages without a project context live under `src/app/org/[orgId]/settings/{organization,members,api-keys,projects,plans,billing}`. The `(auth)` route group holds `/login`.
+
+When adding a page that operates on traces, sessions, or evals, nest it under `org/[orgId]/project/[projectId]/...` — `OrganizationProvider` and `ProjectProvider` read from the URL segments, and the API client only injects the `X-Organization-ID` / `X-Project-ID` headers when those providers resolve a context.
+
+`src/middleware.ts` is the auth gate. It redirects unauthenticated requests under `/org/*` to `/login?callbackUrl=...` based on the `__pp_session` cookie (`SESSION_COOKIE_NAME` in `lib/auth/config.ts`). The cookie is a presence flag set by `auth-service.setSessionCookie()` after Firebase sign-in — the real bearer token comes from Firebase on each request. When `NEXT_PUBLIC_AUTH_ENABLED=false`, the middleware no-ops and pages render without auth.
+
+## Auth toggle is build-time
+
+`AUTH_ENABLED` is evaluated from `process.env.NEXT_PUBLIC_AUTH_ENABLED` in `src/lib/auth/config.ts`. Next.js constant-folds the comparison at build time, so the same image cannot be flipped between auth-enabled and auth-disabled at runtime — the public GHCR image is built with auth off, the private image with auth on. If you're changing how auth gating works, remember it has to behave correctly under both build flavors.
+
+## API client and provider order
+
+`src/lib/api/client.ts` is a singleton axios instance. It is configured exactly once via `configureAuth({ getToken, forceRefreshToken, getOrgId, getProjectId, onUnauthorized })`, called from `components/providers/ApiConfigProvider.tsx` at mount. The request interceptor pulls a Firebase ID token via `getToken()` and stamps `Authorization`, `X-Organization-ID`, `X-Project-ID` onto every request. Do not build URLs or attach headers by hand — go through the per-resource modules in `src/lib/api/` (`traces.ts`, `sessions.ts`, `evaluations.ts`, etc.).
+
+The response interceptor handles 401 by calling `forceRefreshToken()` and retrying the original request once. Concurrent 401s share a single in-flight refresh via `refreshPromise`. If refresh fails (or the second attempt 401s), `onUnauthorized()` runs — wired in `ApiConfigProvider` to clear the session cookie and redirect to `/login`.
+
+Provider nesting in `components/providers/Providers.tsx` is load-bearing:
+```
+AuthProvider → PostHogProvider → ToastProvider → QueryClientProvider → ApiConfigProvider
+```
+`ApiConfigProvider` must sit inside `AuthProvider` (needs the Firebase user) and inside `QueryClientProvider` (so the unauthorized handler can clear caches). `OrganizationProvider` / `ProjectProvider` are mounted lower, inside the `org/[orgId]` and `project/[projectId]` layouts, because they read URL params.
+
+## Query keys
+
+Always pull cache keys from `src/lib/query/keys.ts` (`queryKeys.traces.detail(traceId)`, `queryKeys.evaluations.monitors.list(projectId, params)`, etc.). Inline tuples will silently miss `invalidateQueries` calls keyed off the helpers. When adding a new resource, extend `keys.ts` rather than scattering string literals.
+
+`src/__tests__/lib/query/keys.test.ts` pins the shapes — update both together.
+
+## Tests
+
+- Jest config (`jest.config.ts`): `jsdom`, `ts-jest`, path alias `@/* → src/*`, tests live at `src/__tests__/**/*.test.ts?(x)`, setup at `src/__tests__/setup.ts`.
+- `src/__mocks__/` holds MSW handlers and module mocks used across tests. API tests mock at the network layer with MSW rather than stubbing the axios client.
+- E2E tests live in `frontend/e2e/` and run against a real `yarn dev` server. The Playwright config only ships a Chromium project.
+
+## Conventions
+
+- Path alias `@/...` resolves to `src/...` (both `tsconfig.json` and Jest).
+- Prettier + ESLint via `eslint-config-next` (flat config in `eslint.config.mjs`). `format:check` is the CI gate.
+- `next.config.ts` sets security headers (CSP `frame-ancestors 'self'`, HSTS, etc.) for every route — keep an eye on this when wiring up embeds or third-party iframes.
+- The only required public env var is `NEXT_PUBLIC_API_URL`. Firebase keys are required only when `NEXT_PUBLIC_AUTH_ENABLED=true`. `NODE_ENV` is owned by Next.js — never set it in `.env.*`.

frontend/package.json

@@ -17,6 +17,7 @@
     "format:check": "prettier --check 'src/**/*.{ts,tsx}'"
   },
   "dependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",

frontend/public/assets/session-eval.mp4

@@ -1,12 +1,13 @@
 "use client";
 
 import { useEffect } from "react";
+import Link from "next/link";
 import { useParams, useRouter } from "next/navigation";
+import { ArrowRight, FolderPlus } from "lucide-react";
 import { useOrganization } from "@/components/providers/OrganizationProvider";
 import { useResolvedProjectId } from "@/hooks/useNavigation";
 import { useDocumentTitle } from "@/hooks/useDocumentTitle";
 import { Spinner } from "@/components/ui/Spinner";
-import { OnboardingChecklist } from "@/components/features/OnboardingChecklist";
 
 export default function OrgPage() {
   const { orgId } = useParams();
@@ -32,18 +33,45 @@ export default function OrgPage() {
     );
   }
 
+  // Edge case: user lands here with zero projects.
+  const projectsHref = `/org/${orgId as string}/settings/projects`;
+
   return (
-    <div className="max-w-3xl mx-auto py-8 px-4 space-y-6 animate-fade-in">
+    <div className="max-w-2xl mx-auto py-8 px-4 space-y-6 animate-fade-in">
       <div>
         <h1 className="text-lg font-mono text-primary">
           Welcome to PandaProbe
         </h1>
         <p className="text-sm font-mono text-text-dim mt-1">
-          Let&apos;s get you set up before you can send traces.
+          Create your first project to start tracing your AI agents.
         </p>
       </div>
 
-      <OnboardingChecklist />
+      <section
+        className="border-engraved bg-surface"
+        aria-label="Create your first project"
+      >
+        <div className="flex items-center gap-4 px-5 py-4">
+          <span className="flex-shrink-0 flex items-center justify-center h-10 w-10 border border-primary/40 bg-primary/10 text-primary">
+            <FolderPlus className="h-4 w-4" />
+          </span>
+          <div className="flex-1 min-w-0">
+            <h2 className="text-sm font-mono text-text">Create a project</h2>
+            <p className="text-xs font-mono text-text-muted mt-0.5 leading-snug">
+              Projects isolate traces, sessions, and evaluations. Once
+              you&apos;ve created one, we&apos;ll walk you through sending your
+              first trace.
+            </p>
+          </div>
+          <Link
+            href={projectsHref}
+            className="flex-shrink-0 inline-flex items-center gap-1.5 px-3 py-1.5 border border-info/40 bg-info/10 text-xs font-mono text-info hover:bg-info/20 transition-colors"
+          >
+            Create project
+            <ArrowRight className="h-3 w-3" />
+          </Link>
+        </div>
+      </section>
     </div>
   );
 }