project-setup

Project setup and structure

The decisions here are cheap to make on day one and expensive to change on day two hundred. Two of them account for most of the pain in a mature codebase: how the folders are organised and whether configuration is parsed or merely read.

Structure by business component, not by technical layer

✗ src/controllers/  src/services/  src/models/  src/utils/
✓ src/orders/  src/billing/  src/users/  src/shared/

The technical-layer split feels tidy and gets worse with every feature. Adding one field to orders touches four directories; nothing tells you which files belong together; and services/ becomes a 250-file drawer nobody can navigate. Worst of all it hides coupling — you cannot see that billing reaches into the orders repository, because everything reaches into everything.

Grouping by component makes the dependency graph visible in the filesystem. Inside a component, then layer:

src/orders/
  index.ts          # the public surface — the ONLY thing other components may import
  routes.ts         # HTTP: parse, authorise, delegate. No business logic.
  service.ts        # business logic. No SQL, no Request/Response.
  repository.ts     # data access. No business rules.
  orders.test.ts

The three-layer rule that pays for itself: a Request object must never reach service.ts, and SQL must never appear outside repository.ts. When the service takes plain values instead of a Request, it becomes callable from a queue consumer, a CLI and a test without a fake HTTP layer.

shared/ is for genuinely cross-cutting code. When something there is used by exactly one component, move it into that component — a utils/ that accumulates is how coupling hides.

Configuration: parse at boot, in one file

24 tests ship with this parser and pass (tsc --noEmit clean, Bun 1.3.10).

SKILL="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/project-setup}"; SKILL="${SKILL:-PASTE_THE_DIR_THIS_SKILL_MD_WAS_READ_FROM}"  # that var is UNSET in a Bash tool (MEASURED) — so paste it. `:?` would ABORT the block and copy nothing
mkdir -p src; if [ -d "$SKILL/assets" ]; then cp -r "$SKILL/assets/config" src/config   # env parser + tests
else echo "SKILL is still the placeholder — paste the real dir above and re-run"; fi