Danijel Martinek
f77e6ea881
Curated, product-agnostic snapshot of the post-story-04 tree: demo content deleted, auth-only reference feature, web-next shell, all gates green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor library traces, and product naming are curated out; generic template repairs (coverage provider devDeps, root test:coverage script, live lint fixes, root-only release-please) are kept. See TEMPLATE.md for provenance, curation list, and usage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
119 lines
6.1 KiB
Markdown
119 lines
6.1 KiB
Markdown
# Clean Architecture Monorepo Template
|
|
|
|
Turborepo + pnpm monorepo organised by vertical features, with an **agent-first workflow** and **five conformance gates**.
|
|
|
|
This template is built for **agent-driven development**. [Sandcastle](https://github.com/mattpocock/sandcastle) is the orchestration substrate; `pnpm work dispatch` is the entry point. See [ADR-019](./docs/decisions/adr-019-sandcastle-for-agent-orchestration.md) for the decision rationale and [`docs/guides/runbook.md`](./docs/guides/runbook.md) for end-to-end usage.
|
|
|
|
## Start here
|
|
|
|
Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting, **Using Sandcastle for agent dispatch**).
|
|
|
|
## Quick reference
|
|
|
|
```bash
|
|
pnpm install # Install + auto-wire husky pre-commit hooks
|
|
pnpm dev # All dev servers (web-next:3000, cms:3001, storybook:6006)
|
|
pnpm test # All tests
|
|
pnpm typecheck # TypeScript across all packages
|
|
pnpm lint # ESLint (incl. 8 conformance/* rules)
|
|
pnpm conformance # Cross-feature event closure
|
|
pnpm fallow # Whole-codebase: dead exports, dupes, complexity
|
|
pnpm turbo boundaries # Workspace dependency graph
|
|
pnpm work status # docs/work/ epic + story state
|
|
docker compose up -d # Start PostgreSQL
|
|
```
|
|
|
|
## Sandcastle setup (one-time)
|
|
|
|
Required only if you'll use `pnpm work dispatch --execute` or `pnpm work decompose <id> --execute` (agent dispatch). The dispatch loop runs the implementer / reviewer / decomposer agents inside an isolated Docker sandbox; the image is built once locally.
|
|
|
|
```bash
|
|
# 1. Ensure Docker is running
|
|
docker info >/dev/null
|
|
|
|
# 2. Build the sandcastle image (reads .sandcastle/Dockerfile)
|
|
pnpm exec sandcastle docker build-image
|
|
# Tags as: sandcastle:template-vertical (derived from the root package.json name)
|
|
|
|
# 3. Pick ONE auth path:
|
|
# (a) Recommended — Claude Pro/Max subscription:
|
|
claude login # one-time; ~/.claude/ becomes the auth source
|
|
# (b) Fallback — API key:
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
**macOS users**: subscription auth needs an extra step. Claude Code stores credentials in the macOS Keychain by default, so the host's `~/.claude/` directory has no `.credentials.json` for the sandbox to read. Two workarounds:
|
|
|
|
```bash
|
|
# (preferred for macOS subscription users) extract keychain -> file once:
|
|
security find-generic-password -s "Claude Code-credentials" -a "$USER" -w \
|
|
> ~/.claude/.credentials.json
|
|
chmod 600 ~/.claude/.credentials.json
|
|
# Trade-off: credentials now live as a plaintext file at the path; refresh
|
|
# when the token expires (re-run the same one-liner). The file is in your
|
|
# home directory — chmod 600 + your home permissions are the protection.
|
|
|
|
# OR fall back to API key — no host changes needed:
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
Linux + WSL users with `claude login` write `~/.claude/.credentials.json` directly; nothing extra needed.
|
|
|
|
After the image exists, dispatch flows work without further setup:
|
|
|
|
```bash
|
|
pnpm work dispatch # print plan (safe anywhere)
|
|
pnpm work dispatch --execute # actually dispatch via sandcastle
|
|
pnpm work decompose <prd-id> # print decompose plan
|
|
pnpm work decompose <prd-id> --execute # decompose an approved PRD
|
|
```
|
|
|
|
To rebuild the image after changing `.sandcastle/Dockerfile`:
|
|
|
|
```bash
|
|
pnpm exec sandcastle docker remove-image
|
|
pnpm exec sandcastle docker build-image
|
|
```
|
|
|
|
See [`docs/guides/runbook.md` → Using Sandcastle](./docs/guides/runbook.md#using-sandcastle-for-agent-dispatch) for the full dispatch lifecycle, auth modes, and troubleshooting.
|
|
|
|
## Versioning
|
|
|
|
Releases are automated via release-please with a **single root version** — only the root package (`template-vertical`) is tracked, tagged as plain `v*` (see `.github/workflows/release-please.yml` + `release-please-config.json`). Hybrid per-feature versioning (independent tags per feature package, bump targeting by commit path) is a documented alternative — see [ADR-021](./docs/decisions/adr-021-versioning-and-changelog.md) and [`docs/guides/releasing.md`](./docs/guides/releasing.md); the per-feature config remains greppable in the source repo's git history.
|
|
|
|
## Documentation map
|
|
|
|
- **[`docs/guides/runbook.md`](./docs/guides/runbook.md)** — start here
|
|
- **[`CLAUDE.md`](./CLAUDE.md)** — full conventions reference
|
|
- **[`AGENTS.md`](./AGENTS.md)** — package map + boundary rules
|
|
- **[`docs/guides/conformance-quickref.md`](./docs/guides/conformance-quickref.md)** — manifest + 5-gate daily reference
|
|
- **[`docs/architecture/agent-first-workflow-and-conformance.md`](./docs/architecture/agent-first-workflow-and-conformance.md)** — full design
|
|
- **[`docs/architecture/feature-conformance-explainer.html`](./docs/architecture/feature-conformance-explainer.html)** — interactive explainer
|
|
|
|
## Scaffolding
|
|
|
|
```bash
|
|
pnpm turbo gen feature <name> # Scaffold a feature (manifest + contracts + tests)
|
|
pnpm turbo gen event # Event contract or handler (requires gen core-package events)
|
|
pnpm turbo gen job # Background job
|
|
pnpm turbo gen realtime # Realtime channel (requires gen core-package realtime)
|
|
pnpm turbo gen core-package <name> # Optional core: events / realtime / trpc / ui / audit
|
|
pnpm turbo gen core-ui-component <name> # Atomic-design component
|
|
```
|
|
|
|
**Generator-first is non-negotiable** — hand-rolled feature/event/job/realtime/component code is rejected by reviewer agents and may fail the CI scaffold-drift check.
|
|
|
|
## Optional packages
|
|
|
|
Five core packages scaffold on demand:
|
|
|
|
```bash
|
|
pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016)
|
|
pnpm turbo gen core-package events # Cross-feature events + Payload jobs (ADR-015)
|
|
pnpm turbo gen core-package trpc # tRPC server setup
|
|
pnpm turbo gen core-package ui # Design system
|
|
pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018)
|
|
```
|
|
|
|
See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list.
|