skillsight: Instructions file for Claude Code

CLAUDE.md

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

Commands

Root (runs both packages):

bun run dev          # Start backend + frontend with hot reload
bun run build        # Build frontend (Vite) then backend (Bun)
bun run lint         # Biome lint on both packages
bun run typecheck    # TypeScript strict check on all packages
bun run test         # Run tests across all packages

Backend:

cd backend
bun run dev                    # Hot reload server on :4200
bun run migrate:generate       # Generate Drizzle migrations from schema changes
bun run migrate:run            # Run pending migrations
bun test src/path/to/file.test.ts   # Run a single test file

Frontend:

cd frontend
bun run dev          # Vite dev server on :5173 (proxies /api → :4200)
bun run check        # Biome lint + format check (`biome check src`)
bun test src/path/to/file.test.tsx   # Run a single test file

Architecture

Hexagonal architecture with three layers:

• Domain (backend/src/domain/): Pure entities + repository/gateway port interfaces. No framework deps.
• Application (backend/src/application/): Use cases that accept port interfaces as constructor args. Business logic lives here.
• Infrastructure (backend/src/infrastructure/): Drizzle repository implementations, HTTP gateways (Loki, git), crypto utilities, schedulers.
• HTTP (backend/src/http/): Hono route handlers — thin layer that calls application use cases and serializes responses.

Cross-cutting backend folders outside the hexagon:

• backend/src/config/ — Zod-validated env schema (env.ts).
• backend/src/middleware/ — Hono middleware (session-auth.ts for cookie JWT, ingestion-auth.ts for OTLP bearer).
• backend/src/parsers/ — OTLP and Loki-stream payload parsers, shared by the push endpoint and the pull scheduler.
• backend/src/lib/ — small framework-agnostic helpers (event-bus.ts, request-url.ts).