Project Structure

A stackr project is a monorepo of isolated services. Each service lives under its own top-level directory; there is no shared workspace package.

Root

my-app/
├── auth/                   # auth service (trust anchor)
├── core/                   # a base service
├── wallet/                 # another base service…
├── tests/e2e/              # cross-service end-to-end tests
├── scripts/                # setup.mjs, test runners, check-auth-tables.mjs
├── docker-compose.yml      # dev: all services + their DBs + Redis
├── docker-compose.test.yml # component & e2e test profiles
├── docker-compose.prod.yml # production overlay
├── stackr.config.json      # source of truth for the monorepo shape
├── AGENTS.md / CLAUDE.md   # harness: root conventions + bridge
├── .cursor/ .windsurf/     # harness: editor glob rules
├── .claude/                # harness: skills + PostToolUse hook (if Claude selected)
├── .stackr/sg-rules/       # harness: ast-grep enforcement rules
├── sgconfig.yml
├── DESIGN.md               # generated system design
└── package.json            # root scripts: setup, docker:dev, test, lint:sg…

A service

Each service contains the subsystems you enabled for it: always a backend, optionally web and mobile, plus its own nested AGENTS.md files.

<service>/
├── AGENTS.md               # service role + trust boundary
├── backend/
│   ├── AGENTS.md
│   ├── controllers/
│   │   ├── rest-api/
│   │   │   ├── index.ts    # Fastify bootstrap
│   │   │   ├── plugins/    # config, error-handler, cors, auth, redis
│   │   │   └── routes/     # thin handlers
│   │   └── event-queue/    # BullMQ workers (if enabled)
│   ├── domain/
│   │   └── <entity>/       # schema.ts, repository.ts, service.ts
│   ├── drizzle/ | prisma/  # ORM schema
│   ├── utils/              # db client, ErrorFactory
│   ├── tests/              # Vitest component tests
│   └── Dockerfile
├── web/                    # optional Next.js app (App Router)
│   └── AGENTS.md
└── mobile/                 # optional Expo app
  └── AGENTS.md

The auth service is special

auth/ has the same shape but runs BetterAuth and owns the user/session/account/verification tables. Its web/ is the admin dashboard. No other service may declare identity tables. See Services & Isolation.

Web subsystem

<service>/web/
├── src/app/          # App Router routes (Server Components by default)
├── src/components/   # shadcn/ui components
├── src/lib/
│   ├── session.ts    # server-only, React.cache() wrapped
│   └── actions.ts    # 'use server' mutations (updateTag)
└── src/store/        # Zustand

Route groups like (auth) and (app) organize routes without affecting URLs — public vs. protected.

Mobile subsystem

<service>/mobile/
├── app/              # Expo Router (incl. (onboarding), paywall if enabled)
└── src/
  ├── services/     # shared Axios api instance + integration services
  ├── store/        # Zustand
  ├── components/    # ui + feature components (theme tokens)
  └── ...

Harness artifacts

The AGENTS.md files, CLAUDE.md, .cursor/, .windsurf/, .claude/, and .stackr/sg-rules/ are all generated from stackr.config.json and regenerated by stackr add service and stackr migrate context. Treat them as output — see The Context Harness.