atomic-design-poc/docs/project/backlog/WP-38-dependency-graph-boundaries.md

WP-38 — Dependency graph + declarative boundaries

Status: done Phase: 8 — platform/DX/showcase Priority: P1

Outcome

Adopted dependency-cruiser. .dependency-cruiser.js is the single declarative source for context + layer boundaries (incl. the previously-missing herregistratie scope + no-circular); npm run dep:check enforces (wired into ci-local.sh + the frontend CI job), npm run dep:graph emits a mermaid context×layer graph to docs/reference/architecture/dependency-graph.md. The per-context no-restricted-imports blocks were removed from eslint.config.mjs (now only no-explicit-any + template a11y remain); parity verified by planting violations (domain→Angular, beheer→registratie incl. type-only) and confirming dep:check flags them. Doc: docs/reference/architecture/dependencies.md; new-context skill updated to the single source.

Why

Bounded-context + atomic-layer boundaries are enforced only by hand-duplicated no-restricted-imports blocks in eslint.config.mjs — pass/fail, no graph, and brittle: the new-context skill literally says "grep the config and copy a block", and herregistratie is missing its explicit ban block (asymmetry). We want to see the dependencies AND enforce them from one declarative source.

Decisions

• Step 1 — tool fork: dependency-cruiser (recommended: graph + CI rules on plain Angular) vs Sheriff (tag-based, DDD/atomic-native, weaker graph). Decide before building.
• Encode context + layer rules once (contexts shared/auth/registratie/herregistratie/brief/beheer/ showcase; layers domain/application/infrastructure/contracts/ui); fix the herregistratie gap.
• Keep ESLint for the intra-file rules it does better (domain↛@angular, ApiClient value-import confinement, no-explicit-any); migrate only the cross-module direction rules to the new tool.
• Emit a graph the showcase/teaching can reuse (feeds WP-39).

Files

• New: .dependency-cruiser.js (or sheriff.config.ts); npm run graph + validate script.
• scripts/ci-local.sh + .github/workflows/ci.yml — add depcruise --validate (non-optional).
• eslint.config.mjs — remove the migrated direction rules (keep the rest).
• New doc docs/reference/architecture/dependencies.md; embed the graph in a Foundations page.
• .claude/skills/new-context/SKILL.md — point at the single declarative source.

Acceptance criteria

• One declarative config expresses all allowed context/layer edges; herregistratie included.
• npm run dep:graph produces a committed mermaid architecture graph; dep:check runs in npm run ci.
• A deliberately-illegal import fails the validate step (proven, then reverted).
• No loss of enforcement vs the old ESLint blocks; npm run ci green.