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 six DDD contexts). If a component lives under a context's `ui/`, it's in Domein; everything else
in `shared/ui`/`shared/layout` is Design System. See [Atomic design](?path=/docs/foundations-atomic-design--docs)
for the Atoms → Molecules → Organisms → Templates ladder inside Design System.

## Six contexts, one direction

```
src/app/<context>/<layer>/
```

Contexts: `shared` (the base layer — depends on nothing), `auth`, `registratie`,
`herregistratie`, `brief` (letter-composition teaching slice), `showcase` (teaching page,
sanctioned to read every context — nothing imports it).

**Dependencies only point inward and in one declared direction between contexts:**

```
herregistratie → registratie → shared
auth           → shared
brief          → shared
```

Never the other way — `registratie` may not import `herregistratie`, and no context but
`shared` is imported by everyone.

## 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

`eslint.config.mjs` fails the build on every rule above:

- `domain/` importing `@angular/*` at all (any context).
- `shared/` importing a feature context (`@auth/*`, `@registratie/*`, `@herregistratie/*`,
  `@brief/*`) — the base layer depends on nothing.
- `registratie/` importing `@herregistratie/*`/`@brief/*`, `auth/`/`brief/` importing a
  sibling context — the cross-context direction above.
- `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).

Two components get a documented exemption from the "nothing reaches across" rule:
`shared/ui/debug-state` (reads every root store, for the dev-only state panel) and
`showcase/` (reads every context, for side-by-side teaching pages). Both exemptions live
next to the rule they break, in `eslint.config.mjs`, so they can't rot silently.

## 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.