ehoandClaude Opus 5
d9aef9541f
CLAUDE.md did not name the overzicht context that RD-03 created, and it did not name the max-lines budget that RD-02 enforces. An agent that follows it writes a long page into the wrong context, and meets a red build with no warning. CLAUDE.md now names the context, the @overzicht/* alias, the overzicht -> registratie arrow, the 250-line budget and its glob, and the step-component contract. layers.mdx gains the same arrow. atomic-design.mdx credited eslint.config.mjs with the layer rules. dependency-cruiser enforces them. Each tool is now named for what it does. The page also gains the layer-folder table and the step contract. Four paths were pre-monorepo: three example paths in the ui-component skill, and two citations of libs/shared/src/ui/async, which RD-27 moved to libs/shared/src/ui/molecules/async. npm run ci --full passes: 67 and 45 storybook suites, 306 axe tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
116 lines
6.3 KiB
Plaintext
116 lines
6.3 KiB
Plaintext
import { Meta } from '@storybook/addon-docs/blocks';
|
|
|
|
<Meta title="Foundations/Domain-Driven Design" />
|
|
|
|
# Domain-driven design: bounded contexts & layers
|
|
|
|
This project is **domain-driven**: the code is organised first by **bounded context**
|
|
(a business capability with its own language) and then by **layer** inside each context,
|
|
with dependencies pointing inward. The Storybook sidebar is laid out to **be** that
|
|
architecture, not just document it: **Foundations** (this curriculum) → **Design System**
|
|
(reusable, domain-free) → **Domein** (the app-local DDD contexts). If a component lives
|
|
under a context's `ui/`, or under `libs/beheer/ui`, it's in Domein; everything else in
|
|
`libs/shared/ui`/`layout` is Design System. See [Atomic design](?path=/docs/foundations-atomic-design--docs)
|
|
for the Atoms → Molecules → Organisms → Templates ladder inside Design System.
|
|
|
|
## Two apps, two shared libraries
|
|
|
|
This is a **monorepo**: two Angular projects share one backend and one shared library.
|
|
|
|
```
|
|
apps/<app>/src/app/<context>/<layer>/ — app-local bounded context
|
|
libs/<lib>/src/<layer>/ — cross-app library
|
|
```
|
|
|
|
- `apps/ssp` — the Zorgverlener self-service portal. Contexts: `auth`, `registratie`,
|
|
`herregistratie`, `brief` (letter-composition teaching slice), `showcase` (teaching
|
|
page, sanctioned to read every context in its own app — nothing imports it).
|
|
- `apps/behandelportal` — the Behandelaar backoffice (ADR-0002). Contexts: `auth`,
|
|
`behandeling`.
|
|
- `libs/shared` — the design system + kernel + generated API client. No business logic.
|
|
The base layer: depends on nothing app- or context-specific.
|
|
- `libs/beheer` — the admin/stamdata context, used identically by both apps.
|
|
|
|
`auth` is deliberately **not** shared even though today it's near-identical in both
|
|
apps — ADR-0002 models Zorgverlener/Medewerker as different `Principal` variants with
|
|
different login flows, so the two copies are expected to diverge.
|
|
|
|
**Dependencies only point inward, in one declared direction between contexts:**
|
|
|
|
```
|
|
overzicht → registratie → libs/shared|beheer (ssp)
|
|
herregistratie → registratie → libs/shared|beheer (ssp)
|
|
auth → libs/shared|beheer (ssp)
|
|
brief → libs/shared|beheer (ssp)
|
|
behandeling → libs/shared|beheer (behandelportal)
|
|
auth → libs/shared|beheer (behandelportal)
|
|
```
|
|
|
|
Never the other way — `registratie` may not import `herregistratie`, no context but
|
|
`libs/shared`/`libs/beheer` is imported by everyone, an app may not import the other
|
|
app's source, and `libs/shared` may not depend on `libs/beheer` (shared stays the base,
|
|
beheer a peer leaf).
|
|
|
|
## Five layers, one direction
|
|
|
|
| Layer | Job | Angular allowed? |
|
|
| ----------------- | ----------------------------------------- | ----------------- |
|
|
| `domain/` | business rules + data types | **No — pure TS.** |
|
|
| `application/` | coordinate state/tasks (stores, commands) | yes (signals) |
|
|
| `infrastructure/` | where data comes from (HTTP adapters) | yes (HTTP) |
|
|
| `contracts/` | wire DTOs (the FE⇄BE seam) | no |
|
|
| `ui/` | how it looks (components, pages) | yes |
|
|
|
|
`ui → application → domain`; `ui`/`layout` never import `infrastructure/` directly — they
|
|
reach data through an application store or command.
|
|
|
|
## This is enforced, not just written down
|
|
|
|
`npm run dep:check` (dependency-cruiser) fails the build on every rule above. One shared
|
|
rule _factory_ (`.dependency-cruiser.base.js`) is instantiated once per app — each app is
|
|
cruised separately against its own `tsconfig.json`, since `apps/ssp` and
|
|
`apps/behandelportal` each declare `@auth/*` pointing at a different physical directory
|
|
and a single merged tsconfig can't resolve both at once:
|
|
|
|
- `domain/` importing `@angular/*` at all (any context, either app).
|
|
- `libs/shared` importing an app feature context, or `libs/beheer` — the base layer
|
|
depends on nothing.
|
|
- `libs/beheer` importing an app feature context.
|
|
- an app importing the other app's source directly.
|
|
- `registratie/` importing `@herregistratie/*`/`@brief/*`, `auth/`/`brief/` importing a
|
|
sibling context — the cross-context direction above, one `.dependency-cruiser.<app>.js`
|
|
per app.
|
|
- `contracts/**` importing **anything** — not Angular, not an alias, not even a relative
|
|
path (ADR-0001's wire seam has to stay a pure DTO shape).
|
|
- `ui/**`/`layout/**` importing `*/infrastructure/*` — the anti-corruption boundary
|
|
(ADR-0001) stays behind a store/command, so a page can never bypass it and hand-recompute
|
|
a business rule the backend already decided.
|
|
- The generated `ApiClient` imported as a value outside an `infrastructure/` adapter
|
|
(type-only DTO imports are exempt — they grant no network access).
|
|
|
|
`showcase` gets a documented exemption from the "nothing reaches across" rule
|
|
(`showcase: null` in `.dependency-cruiser.ssp.js`) — it reads every context in its own
|
|
app, for side-by-side teaching pages. The dev-only state panel (`apps/ssp/src/app/shell/debug-state`)
|
|
reads every root store too, but needs no such exemption: it lives outside any enumerated
|
|
context, so the per-context scoping rule never applies to it in the first place.
|
|
|
|
`npm run lint` (`eslint.config.mjs`) is a separate gate — mainly the `any`-free rule —
|
|
and no longer carries the import-boundary rules above (moved to dependency-cruiser,
|
|
so they don't have to be hand-copied per context).
|
|
|
|
## The English/Dutch seam
|
|
|
|
Shared/reusable UI is named in **English** (language-agnostic: `button`, `wizard-shell`);
|
|
domain contexts are named in **Dutch** (`registratie`, `herregistratie`, `*.machine.ts`).
|
|
Pick the language by which side of the seam the code is on — it's the same seam this
|
|
sidebar's Design System/Domein split makes visible.
|
|
|
|
## See it in the sidebar
|
|
|
|
Compare a Design System primitive with the same shape reused across contexts:
|
|
|
|
- [Design System → Molecules → Application Link](?path=/story/design-system-molecules-application-link--navigatie) —
|
|
domain-free, the caller supplies heading/subtitle/cta.
|
|
- [Domein → Registratie → Aanvraag Block](?path=/story/domein-registratie-aanvraag-block--concept) —
|
|
a context-specific organism composed from Design System atoms/molecules.
|