Skip to content

CLAUDE.md

Latest commit

 

History

History
75 lines (58 loc) · 2.97 KB

CLAUDE.md

File metadata and controls

75 lines (58 loc) · 2.97 KB
Raw

CLAUDE.md

Place at repo ROOT. Auto-loaded into every Claude Code session.

Project

Distributed job scheduling platform. Postgres is both the queue and the system of record. Four deployables: apps/api, apps/worker, apps/scheduler, apps/web. Graded logic lives in packages/core — treat it as the crown jewel.

Hard rules — never violate

Concurrency

  • Job claiming MUST use SELECT ... FOR UPDATE SKIP LOCKED.
  • NEVER SELECT then UPDATE as separate statements.
  • NEVER application-level locking, in-memory mutexes, or advisory locks for claiming.
  • Every claim sets lock_expires_at. No exceptions.
  • Retry backoff always applies full jitter.

Database

  • Parameterized queries only. NEVER string-interpolate SQL.
  • Drizzle for schema and migrations. Raw SQL is allowed and expected for the claim query.
  • Every partial index in docs/DATABASE.md must exist. Do not "simplify" them.
  • Migrations run as a release step, never on service boot.

Security

  • Every project-scoped query filters by org_id derived from the JWT — NEVER from a request param.
  • Use the shared assertProjectAccess() guard. No route bypasses it.
  • argon2id for passwords. jose for JWT. Never jsonwebtoken.
  • http_request handler enforces the SSRF allowlist and blocks private CIDRs.
  • Never log password, token, authorization, key, or secret.
  • Never return stack traces in production responses. Log them, return the request ID.

API

  • Cursor pagination only. NEVER OFFSET.
  • zod validation on every body, query, and param.
  • One error envelope: { error: { code, message, details, request_id } }.
  • 201 create, 202 enqueue accepted, 409 idempotency conflict, 422 validation, 429 rate limit.

Testing

  • Concurrency tests run against real Postgres via Testcontainers. NEVER mock the database.
  • Test-first for anything in packages/core.

Frontend

  • Tokens from docs/UI_DESIGN_SYSTEM.md exactly. Do not substitute Tailwind defaults.
  • Borders, not shadows. Radius 6px default, 10px cards.
  • Monospace for every identifier. Status = dot + label, never a filled badge.

Process

  • No new dependencies without asking first.
  • Do not create files outside the structure in docs/MODULES.md.
  • Prefer fewer, larger, well-organized files over many small ones.
  • When the spec and your instinct disagree, follow the spec and say so.

Stack — do not substitute

Node 22 · TypeScript 5.7 strict · Express 5 · Drizzle + postgres.js · zod · pino · argon2 · jose · Vitest + Testcontainers · React 19 · Vite 6 · Tailwind v4 · TanStack Query/Router/Table · shadcn/ui · Biome · pnpm · Turborepo

Commands

pnpm dev            all services
pnpm test           full suite
pnpm test:chaos     concurrency proof
pnpm db:migrate     apply migrations
pnpm db:seed        demo data
pnpm bench          throughput benchmark

At session end

Append to docs/PROGRESS.md: what you built, files touched, and any decision that differs from the spec with the reason.