W07 / Case study

An agent-ready monorepo

The boilerplate this site runs on: typed contracts, infrastructure as code, ADRs and guardrails enforced by hooks.

Client: This site
Role: Author
Period: 2026
Stack: Turborepo
Next.js
NestJS
Drizzle
Railway
Claude Code

01 / Summary

Summary

A full-stack TypeScript monorepo built so AI agents can work in it safely: a Next.js frontend, a private NestJS API with Better Auth, Drizzle on Postgres, a generated typed client and Railway infrastructure as code. Rules live in AGENTS.md files and ADRs, and hooks, architecture tests and reviews enforce them.

02 / Key decisions

Key decisions

The contract is generated, never hand-written
Zod schemas produce the OpenAPI document, which generates the client the frontend uses. CI fails when the committed contract is stale.
Trade-off Every API change regenerates two files.
Guardrails are hooks, not advice
Edits are formatted and linted on write, stopping is blocked until typecheck and tests pass, and a guard rejects skipped hooks and lockfile edits.
Trade-off Slower individual edits, far fewer broken ones.
Architecture enforced by tests
Layer rules, import boundaries and token usage are checked by architecture tests, so a violation fails the build with the rule number.
Trade-off Rules have to be precise enough to test.
A private API
The API has no public domain; only the frontend reaches it over the private network.
Trade-off Third-party access needs an explicit decision and a proxy-aware setup first.

← All work