docs(architecture): refresh explainers and spec to the shipped system
Some checks failed
CI / typecheck + lint + boundaries + test + build (push) Has been cancelled
CI / Playwright e2e (push) Has been cancelled
CI / Storybook smoke tests + visual regression (push) Has been cancelled
CodeQL / Analyze (javascript-typescript) (push) Has been cancelled
Coverage snapshot / snapshot (push) Has been cancelled
Release Please / release-please (push) Has been cancelled
Sentry PII guard (R31) / pii-guard (push) Has been cancelled
Mutation testing (nightly) / mutate (push) Has been cancelled
Library trace revalidation (weekly) / revalidate (push) Has been cancelled

Bring docs/architecture/ in line with the current repo:

- feature-conformance-explainer.html: drop the "proposed / not yet
  implemented" framing — the system is shipped. Four enforcement points
  become five (adds `pnpm fallow` as the whole-codebase audit). Manifest
  playground shows `coverage`, `analyticsEvents`, `rateLimit`,
  `requiresConsent`. Milestone / anchor / open-question sections kept
  but marked historical.
- agent-first-workflow-and-conformance.md: four → five enforcement
  layers; layer table gains the Fallow row.
- di-explainer.html: bind-production sample rewritten to show
  wireUseCase() + assertFeatureConformance() + the full wrapper stack
  (span → capture → audit? → analytics? → consent? → rateLimit?).
- data-flow-explainer.html: same bind-production refresh for the
  data-flow narrative.
- audit-and-compliance-explainer.html: AuditAction enum 6 → 10 values
  (CONSENT_GRANT / WITHDRAW / RESTRICT / UNRESTRICT);
  BindProductionContext example gains analytics, consentFactory,
  rateLimit.
- vertical-feature-spec.md: §5 layout lists the 8 optional cores plus
  core-testing; §9.5 hedges the turbo.json snippet against the live
  file; §10.4 drops the dated "360 tests" metric for the ADR-020
  coverage architecture; §11 gains a historical lead-in pointing at
  docs/decisions/ as the canonical 25-ADR set.
This commit is contained in:
2026-05-23 14:06:03 +02:00
parent b455ae8018
commit 0748f9e5ed
6 changed files with 251 additions and 51 deletions

View File

@@ -111,12 +111,19 @@ repo/
storybook/ # unchanged; updates imports from @repo/ui → @repo/core-ui
packages/
# ─── CORE (foundation, tagged "core") ───
# ─── CORE — must-have (tagged "core" / "core-composition") ───
core-shared/ # generic primitives (no business knowledge)
core-cms/ # Payload composition only (aggregates feature cms exports)
core-api/ # tRPC composition only (aggregates feature api exports)
# ─── CORE — optional (scaffold via `pnpm turbo gen core-package <name>`) ───
core-trpc/ # frontend tRPC platform (client, providers per framework)
core-ui/ # design-system primitives (atoms/molecules/templates)
core-events/ # in-memory + Payload-backed event bus + job queue (ADR-015)
core-realtime/ # Socket.IO broadcaster + handler registry (ADR-016)
core-audit/ # DPA-compliant audit logging (ADR-018)
core-analytics/ # product analytics capture channel (ADR-024)
core-consent/ # consent + cookie banner (ADR-025)
core-dsr/ # data-subject-rights — export/delete/rectify/restrict (ADR-025)
# ─── FEATURES (business capabilities, tagged "feature") ───
auth/ # Users collection + sign-in/up/out
@@ -126,8 +133,9 @@ repo/
navigation/ # header global
# ─── TOOLING (tagged "tooling") ───
core-eslint/
core-typescript/
core-eslint/ # ESLint preset + the 15 conformance rules + boundary rules
core-typescript/ # tsconfig presets (base, react-library, nextjs)
core-testing/ # factories, contract suites, recording test doubles
docs/
architecture/
@@ -135,7 +143,7 @@ repo/
dependency-flow.md # rewritten
vertical-feature-spec.md # copy of source spec
decisions/
adr-001 … adr-009 # five existing + four new (see §10)
adr-001 … adr-NNN # 25 ADRs at time of writing — see §11 and `docs/decisions/`
guides/
adding-a-feature.md # rewritten
testing-strategy.md # rewritten
@@ -469,6 +477,8 @@ A feature may import another feature's **public exports** — its `@repo/<featur
### 9.5 Root `turbo.json` (unchanged concept)
The snippet below shows the original task shape. The live `turbo.json` has evolved — additional tasks (`conformance`, `fallow`, `boundaries`, `test:stories`, `build-storybook`), tweaks to `dependsOn` (`test` and `typecheck` no longer depend on `^build`), and the `boundaries.tags` block enforcing the dependency matrix (see §9.2). See the actual root `turbo.json` for the authoritative shape; the principle below is unchanged.
```json
{
"tasks": {
@@ -543,7 +553,7 @@ No shared `initializeContainer()` / `destroyContainer()`.
### 10.4 Actual test coverage
- **360 tests across 26 packages** (`pnpm test` green as of 2026-05-06)
- `pnpm test` runs green across every workspace package. Coverage thresholds are declared per-feature in `feature.manifest.ts` (ADR-020) — `entities` and `use-cases` at 100% statements/branches/functions/lines, `controllers` at 100/95/100/100, with a baseline of 80/75/80/80 elsewhere. The four coverage layers (L0 thresholds → L1 diff coverage → L2 aggregate trend → L3 mutation) are documented in `docs/guides/coverage.md`.
Key coverage areas:
@@ -583,6 +593,8 @@ Identity presenters do not require R27/R28 tests. Void-output controllers (e.g.,
## 11. Docs + ADR strategy
> **Historical.** This section captures the ADR strategy at the time of the vertical-feature refactor — 5 existing ADRs (001005), 4 new ADRs (006009), and the 2 post-spec ADRs (012013). The **canonical, current ADR set** lives in `docs/decisions/` and now spans **25 ADRs** — adding boundaries (010), TDD foundation (011), instrumentation + OpenTelemetry (014, 017), events / realtime / audit (015, 016, 018), Sandcastle (019), coverage (020), hybrid versioning (021), library policy + CI security (022, 023), product analytics (024), and the EU compliance baseline (025). Read `docs/decisions/` for the authoritative list; the tables below are preserved as the refactor's original record.
### 11.1 Existing ADRs
| File | Action | Notes |