Introduction

stackr is a CLI that generates a production-grade, multi-service TypeScript monorepo — and, just as importantly, the tooling that keeps that architecture intact long after the code is generated.

npx create-stackr@latest my-app

It is not a starter template you clone and outgrow in a week. It scaffolds an opinionated, horizontally-scalable backend architecture and a context harness that encodes the conventions of that architecture into files your editor and your AI agents read on every edit.

What stackr generates

A monorepo with one auth service — the trust anchor that owns user, session, account, and verification data — plus any number of base services. Each service is fully isolated:

• its own Fastify backend (layered routes → service → repository → schema),
• its own PostgreSQL database and Redis instance,
• optional Next.js web and Expo mobile frontends,
• an optional BullMQ event queue.

Services never reach into each other's databases. The only cross-service call is a base service verifying a request by forwarding the session cookie to the auth service. Everything is wired together with Docker Compose and a full Vitest test setup.

Why stackr?

Spinning up "a full-stack app" is easy. Spinning up one that still has a coherent architecture after three months of features — and after an AI agent has written half of it — is the hard part. That is the gap stackr is built for.

Most scaffolding tools stop at file generation. The moment you (or your agent) start writing features, the conventions the template encoded begin to drift: business logic leaks into route handlers, a second service quietly grows a user table, error handling becomes inconsistent, and the "architecture" becomes a folder layout nobody enforces.

stackr addresses this with two pillars.

1. A scalable architecture, not a scaffold

stackr generates a multi-microservice monorepo with hard isolation boundaries. Each service owns its data and can be deployed, scaled, or rewritten independently — a runaway migration in one service can't corrupt another's. The auth service is the single trust anchor; base services authenticate by forwarding cookies, never by trusting a header or a client-supplied id. This is precisely the structure that ad-hoc and AI-generated projects fail to get right.

→ Start with the Architecture overview.

2. A context harness that keeps conventions enforced

After generation, stackr ships a push-based context harness: nested AGENTS.md files, a CLAUDE.md bridge, Cursor and Windsurf glob rules, Claude skills, ast-grep lint rules, and a post-edit hook — all derived from a single source of truth. Your editor and your agents are told the rules as they edit the matching files, and a subset of those rules is mechanically enforced. Codegen (stackr add entity) is correct-by-construction: the generated code always compiles and already follows the conventions.

→ Learn how it works in The Context Harness.

Who it's for

• Teams that want a service-oriented backend with isolation and testing built in from day one, instead of refactoring a monolith into one later.
• Engineers using AI agents (Claude Code, Cursor, Codex, Windsurf) who want the agent to stay on-architecture without hand-holding every prompt.
• Solo builders who want a production-shaped foundation — auth, Docker, CI, tests — without wiring it all by hand.

Next steps

• Installation — prerequisites and getting the CLI.
• Quick Start — generate and boot a project in a few commands.
• Configuration — the interactive wizard and every option.
• Architecture — how the monorepo is structured and why.
• The Context Harness — how conventions stay enforced.