biggus-dickus/CLAUDE.md

CLAUDE.md

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

Status

Rust (edition 2024) workspace + React SPA collection-management system. Backend crates: domain, db, api, auth, search, server (axum 0.8 + sqlx/Postgres + Meilisearch). Frontend in web/ (React 19 + Vite + pnpm). Tests need the docker-compose stack up (Postgres on :5442, Meilisearch on :7700); each #[sqlx::test] provisions its own temp DB.

Commands

just check                       # fmt + lint + test — the standard pre-commit gate
docker compose up -d             # start Postgres (:5442) + Meilisearch (:7700) for tests
cargo build --workspace          # build
cargo run -p server              # run the server (or: just run — loads .env)
cargo nextest run --workspace    # run all tests — PREFERRED (per-test isolation, live output, hang timeouts)
cargo nextest run -E 'test(<name>)'   # run tests matching a name substring
cargo test --workspace --doc     # doctests (nextest does not run these)
cargo +nightly fmt               # format — always nightly, not stable
cargo clippy --workspace --all-targets -- -D warnings   # lint before committing

(just test runs nextest + doctests; config in .config/nextest.toml.)

Conventions

• CLI args & env vars: use clap with the derive feature.
• Code navigation: prefer the insikt LSP server over grep/glob — it resolves macro-generated symbols that text search misses. (insikt runs standalone, not via the gateway MCP.)
• Dependencies: manage via the cargo-mcp server rather than editing Cargo.toml by hand.
• Formatting: cargo +nightly fmt (nightly toolchain required).
• Frontend guardrails: before touching web/, read web/GUARDRAILS.md — it covers the CI gate (check:size 250 KB-gz budget, check:colors design-token enforcement) and the test-harness quirks (MSW onUnhandledRequest: "error", the jsdom/storybook vitest split, RTL accessible-name collisions, Storybook nested-router and portal handling, and the components/ui/ code-style split).