Danijel Martinek
ef2b8e300e
First slice of the combined Plan 8 + Plan 9 doc-update pass: - CLAUDE.md Key Conventions: append schema-in-use-case, presenter, controller unknown input, feature-scoped tRPC error mapping, public surface split (./ui) - packages/core-shared/AGENTS.md: document defineErrorMiddleware export + t re-export from trpc/init - docs/superpowers/plans/2026-05-05-plan-8-*.md and matching spec: one-line note that some controller/router patterns shifted in Plan 9; link to the Plan 9 refactor log - docs/architecture/overview.md: data-flow box now shows xProcedure + xInputSchema + xOutputSchema.parse + presenter + middleware lanes; three explanatory paragraphs added (schemas, presenter, error mapping) - docs/architecture/dependency-flow.md: app-side ./ui subpath note, allowed/disallowed examples updated for Plan 9 paths Remaining doc-pass items (root AGENTS.md, per-feature AGENTS.md ×5, core-testing AGENTS.md, adding-a-feature.md, tdd-workflow.md, testing-strategy.md, vertical-feature-spec.md) follow in subsequent commits — to be dispatched in parallel.
68 lines
5.1 KiB
Markdown
68 lines
5.1 KiB
Markdown
# Clean Architecture Monorepo Template
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
pnpm install # Install all dependencies
|
|
pnpm dev # Start all dev servers
|
|
pnpm build # Build all packages
|
|
pnpm test # Run all tests
|
|
pnpm turbo boundaries # Validate workspace dependency graph
|
|
docker compose up -d # Start PostgreSQL
|
|
```
|
|
|
|
## TDD
|
|
|
|
```bash
|
|
pnpm test --watch --filter @repo/<feature> # watch one feature
|
|
pnpm test -- --coverage # full run with coverage
|
|
pnpm test:stories # Storybook smoke tests
|
|
pnpm test:e2e # Playwright e2e
|
|
```
|
|
|
|
See `docs/guides/tdd-workflow.md` for the full cycle.
|
|
|
|
## Project Overview
|
|
|
|
Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) owns its Clean Architecture layers. Core packages (`core-shared`, `core-cms`, `core-api`, `core-trpc`, `core-ui`) provide foundation. Two tooling packages (`core-eslint`, `core-typescript`) provide shared configs. Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.
|
|
|
|
## Read First
|
|
|
|
- `AGENTS.md` — Package map, boundary rules, per-package conventions
|
|
- `docs/architecture/overview.md` — High-level architecture and package responsibilities
|
|
- `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
|
|
- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough
|
|
|
|
## Key Conventions
|
|
|
|
- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias
|
|
- **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/`
|
|
- **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }`
|
|
- **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files
|
|
- **Lazar-conformant file layout** — Entities live at `entities/models/<x>.ts`; errors at `entities/errors/<domain>.ts` + `entities/errors/common.ts`; mock siblings use the `.mock.ts` suffix (`<x>.repository.mock.ts`); real repository impls drop the `payload-` prefix (`<x>.repository.ts`); interface filenames are dot-separated (`<x>.repository.interface.ts`)
|
|
- **Factory-function use cases & controllers** — Every use case and controller is `(deps) => async (input) => result`; each exports `export type I*UseCase = ReturnType<typeof xUseCase>` (and the analogous `I*Controller`); one controller per use case (no multi-method controllers)
|
|
- **DI uses `.toDynamicValue()` for factories** — `bind<IXUseCase>(SYMBOL).toDynamicValue((ctx) => xUseCase(ctx.container.get(...)))`; mocks remain the default binding
|
|
- **Tests inject mocks directly** — Construct `MockXRepository` and pass into the factory: `signInUseCase(mockUsers, mockAuth)(input)`. No container rebinding in unit tests
|
|
- **Schemas in the use-case file** — Every use case exports `xInputSchema` (a `z.ZodObject` with `.strict()`; `z.object({}).strict()` for void inputs) and, for non-void use cases, `xOutputSchema`. Types: `XInput = z.infer<typeof xInputSchema>` and `XOutput`. Use case body ends with `xOutputSchema.parse(result)` before returning (runtime guarantee against malformed repository data)
|
|
- **Controllers receive `unknown` + presenter** — Controllers `safeParse(xInputSchema)` from the use-case file and throw `InputParseError` on failure. Non-void controllers define a top-level `function presenter(value: XOutput)` and return `Promise<ReturnType<typeof presenter>>` (identity is fine — `return value`); void controllers return `Promise<void>` with no presenter
|
|
- **Feature-scoped tRPC error mapping** — Each feature has `integrations/api/procedures.ts` exporting `xProcedure = t.procedure.use(defineErrorMiddleware([[Ctor, "TRPC_CODE"], ...]))` from `@repo/core-shared/trpc/define-error-middleware`. Routers use `xProcedure.input(xInputSchema)` — schemas are imported from the use-case file, never redefined inline. `core-shared` never enumerates feature error classes
|
|
- **Public surface split** — Feature root (`.`) exports contracts only: types, errors, schemas, IUseCase / IController aliases, router type, constants. UI artifacts (query builders, components) live behind `./ui` (`src/ui/index.ts`). Apps import queries from `@repo/<feature>/ui`, schemas/types from `@repo/<feature>`
|
|
- **Payload repositories via constructor** — Feature packages receive Payload config at constructor time, not as a direct dependency
|
|
- **App bootstrap** — Each app calls `bindProduction*()` per feature at startup to swap mocks for real Payload-backed impls in the InversifyJS containers
|
|
|
|
## MCP Servers
|
|
|
|
Start Storybook before UI work: `pnpm dev --filter @repo/storybook`
|
|
|
|
Storybook MCP available at `http://localhost:6006/mcp` — use `list-all-documentation` to discover existing components before creating new ones.
|
|
|
|
## Key Ports
|
|
|
|
| Service | Port |
|
|
|---|---|
|
|
| Next.js | 3000 |
|
|
| Payload CMS | 3001 |
|
|
| TanStack Start | 3002 |
|
|
| PostgreSQL | 5432 |
|
|
| Storybook | 6006 |
|