layered-architecture
Installation
SKILL.md
One direction: handler → service → repo
Undercroft's backend has three layers, and a file's directory is its layer. The arrows point one way and nothing skips a step:
apps/*/src/
main.ts | server.ts composition root: reads env, builds the pool/store, wires it up
handlers/ ──→ HTTP, tRPC, status codes
services/ ──→ the decisions
repos/ ──→ every SQL statement
packages/db/src/ the seam: SqlExecutor, pool, migrate (+ its own repos/, services/)
packages/{core,contracts,crypto,lake,connector-runtime}/ below every layer
Seven ast-grep rules enforce this in bun run lint:rules, inside bun run verify and CI.
They are not style preferences — a SELECT in a handler fails the build. The normative text
is .claude/rules/layering.md; the reasoning is docs/adr/0011-layers-handler-service-repo.md.