lmnr: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Laminar is an open-source observability platform for AI agents: OpenTelemetry-native tracing, evaluations, AI monitoring, and SQL access to all data.

Repository Structure

Multi-service monorepo:

• app-server/ — Rust backend (Actix-web HTTP, Tonic gRPC). SQL query validation + JSON↔SQL conversion run in-process (src/query_engine/, built on sqlparser).
• frontend/ — Next.js/TypeScript web UI.
• pii-redactor/ — optional standalone Rust gRPC service running a HuggingFace PII model on CPU via ONNX Runtime. See pii-redactor/README.md.

Some features (Signals evaluation, Laminar Agent, clustering) are enterprise-only and live in the private lmnr-private repo behind the signals cargo feature; OSS ships stubs and public scaffolding for them. Don't document them as OSS features.

Development Commands

Frontend (Next.js)

cd frontend
pnpm install        # Install dependencies
pnpm run dev        # Start dev server (Turbopack)
pnpm lint           # oxlint (lint:fix to auto-fix)
pnpm format:write   # oxfmt
pnpm type-check     # TypeScript type checking
pnpm test           # Run tests (tsx --test tests/**/*.test.ts)
pnpm build          # Production build

• The sandbox's global pnpm is v10 but the lockfile is written by pnpm 12 (.github/workflows/fe-build-check.yml pins 12.14.0, frontend/Dockerfile 12.8.1). pnpm add on v10 rewrites hundreds of (supports-color@…) peer suffixes. Add or bump deps with npx -y [email protected] add <pkg> --lockfile-only, then npx -y [email protected] install --frozen-lockfile to sync node_modules.
• Format only the files you changed: npx oxfmt --write <files>. prettier is present in node_modules (transitive dep) but is NOT the project formatter — running it reformats files oxfmt then flags in the pre-commit hook.
• In a fresh checkout, pnpm type-check (and the husky pre-commit hook) fails with TS2307: Cannot find module '@/assets/...svg' errors — next-env.d.ts is gitignored. Fix: npx next typegen (or any next dev/next build run).
• tsconfig.json sets "incremental": true, so a bare npx tsc --noEmit can report zero errors on files it skipped and give a false green. When verifying a type fix, run npx tsc --noEmit --incremental false (the pre-commit hook does a full check and will catch what you missed otherwise). On an 8 GB box the full check OOMs at Node's default heap; prefix NODE_OPTIONS=--max-old-space-size=8192.
• pnpm test on a clean dev already has two red tests (after pnpm install --frozen-lockfile, ai 7.0.15): tests/test-ai-sdk-parser.test.ts "skips empty text/reasoning parts" and tests/test-normalize-messages.test.ts "end-to-end: a bare AI-SDK parts array …". Both expect empty text/reasoning parts to be dropped and get 2 parts instead of 1. Pre-existing — git stash -u and re-run before blaming your change.
• A stale node_modules fakes ~47 "pre-existing" type errors. An installed tree older than pnpm-lock.yaml (e.g. recharts 2.15.4 where the lock pins 3.10.1) makes tsc --noEmit and pnpm build fail on BarStack / MouseHandlerDataParam / useYAxisScale / <YAxis width="auto"> across chart-builder/, charts/, evaluation/, landing/. They look exactly like the recharts v2→v3 debt they are not: pnpm install --frozen-lockfile clears all of them. Verify the install matches the lock before writing any of it off as pre-existing.
• Turbopack is the Next 16 default for both commands; build opts out with --webpack, dev does not. Turbopack's production output miscompiled chunks (module factory is not available on client navigation). So both bundler blocks in next.config.ts are live, and a production repro needs pnpm build, not a bare next build. next dev generates frontend/AGENTS.md on every run; it is gitignored (do not commit it).
• frontend/.dockerignore excludes only node_modules and .next, so a local docker build frontend/ ships .env.local into the builder and next build inlines its NEXT_PUBLIC_* values. For a CI-faithful image, build from a copy without it (tar --exclude=./node_modules --exclude=./.next --exclude=./.env.local -cf - . | tar -xf - -C /tmp/ctx). The sandbox has no Docker by default: apt-get install -y docker.io then start dockerd in the background works.