traceway CLAUDE.md

CLAUDE.md - Traceway Project

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

Project Overview

Traceway is an error tracking and monitoring platform consisting of:

• Frontend: SvelteKit 2 dashboard application with Svelte 5
• Backend: Go/Gin API server with ClickHouse database
• CLI: Go/Cobra command-line client for the backend HTTP API (/cli)

---

Code Style

• No pointless comments: Do not add comments that simply describe what the code does. The code should be self-explanatory. Only add comments when explaining non-obvious "why" decisions.
• No py-4 in dialog form content: Do not add py-4 on the content wrapper inside AlertDialog or Dialog components — it creates too much blank space between the form and the action buttons.
• Dialog button labels & toasts: For form dialogs, use descriptive button labels with icons instead of generic "Create"/"Update". The {Entity} is always a platform entity, capitalized (Project, Widget, Dashboard, Channel, Rule, Token, Invitation, ...). Create actions: <Plus icon> New {Entity} with variant="success". Update actions: <Check icon> Update {Entity} with the default (primary) variant. Delete/revoke/remove confirm buttons: <Trash2 icon> Delete {Entity} (or Revoke {Entity} / Remove {Entity}) with variant="destructive". After success, show toast.success('Successfully created the {Entity}', { position: 'top-center' }) for creates and 'Successfully updated the {Entity}' for updates. The button should only be disabled during the loading state — never disable it to enforce validation; let the backend return 422 and show the error in the dialog instead.

---

Quick Start

Development Commands

Component	Command	Description
Frontend	cd frontend && npm run dev	Dev server (port 5173)
Frontend	npm run build	Production build
Frontend	npm run check	TypeScript checking
Backend	cd backend && go run ./cmd/traceway	API server (port 8082)
Backend	cd backend && govulncheck ./...	Vulnerability scan (default tags only); CI also scans the other storage build-tag combos (.github/workflows/backend-vulncheck.yml)
CLI	cd cli && just build	Builds bin/traceway
CLI	cd cli && just test	Runs unit tests
CLI	cd cli && just check	Lint + test + vulncheck + skill drift + contract tests (pre-commit gate; CI enforces it for cli/)
CLI	cd cli && just smoke-test	Live E2E (needs TRACEWAY_SMOKE_* env vars)
Any	nix develop (or direnv via .envrc)	Dev shell with the Go and Node versions read from backend/go.mod and frontend/package.json, plus just, golangci-lint, govulncheck (flake.nix; shells default, backend, frontend, oxc). Put JWT_SECRET in the gitignored .envrc.local