From a1b54ad83324ff72e603367bbd45d7eebb4f1ac3 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Mon, 11 May 2026 16:41:20 +0200 Subject: [PATCH] docs: surface core-audit as 5th optional package across discovery points --- AGENTS.md | 1 + CLAUDE.md | 3 ++- README.md | 3 ++- docs/architecture/data-flow-explainer.html | 6 +++--- docs/architecture/template-tiers.md | 1 + docs/scaffolding/core-package-generator.md | 1 + 6 files changed, 10 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 020e601..3e62041 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ This is a **Turborepo + pnpm monorepo** organized by vertical features. Each fea |---|---|---| | `@repo/core-shared` | core | Generic primitives (Zod, env, Payload hooks/fields/blocks, tRPC init/context) | | `@repo/core-ui` | core | Design system (atoms, molecules, generic organisms, templates) — **optional**, scaffold via `pnpm turbo gen core-package ui` | +| `@repo/core-audit` | core | DPA-compliant audit logging (4 impls, GDPR erasure, OTel correlation) — **optional**, scaffold via `pnpm turbo gen core-package audit` | | `@repo/core-api` | core-composition | tRPC router aggregator — imports `@repo//api` only | | `@repo/core-cms` | core-composition | Payload config aggregator — imports `@repo//cms` only | | `@repo/core-trpc` | core-composition | Frontend tRPC client + framework-specific providers (Next.js, TanStack) | diff --git a/CLAUDE.md b/CLAUDE.md index 1822ce5..91d753a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,7 @@ 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. Must-have core packages (`core-shared`, `core-cms`, `core-api`) provide foundation; four optional core packages (`core-realtime`, `core-events`, `core-trpc`, `core-ui`) scaffold on demand via `pnpm turbo gen core-package ` (see `docs/architecture/template-tiers.md`). 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. +Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) owns its Clean Architecture layers. Must-have core packages (`core-shared`, `core-cms`, `core-api`) provide foundation; five optional core packages (`core-realtime`, `core-events`, `core-trpc`, `core-ui`, `core-audit`) scaffold on demand via `pnpm turbo gen core-package ` (see `docs/architecture/template-tiers.md`). 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 @@ -41,6 +41,7 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, - `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough (manual path; for cases the generator's Phase-1 scope doesn't cover) - `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs; *requires `gen core-package events`*) - `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers (*requires `gen core-package realtime`*) +- `docs/guides/audit-and-compliance.md` — DPA-compliant audit logging cookbook (*requires `gen core-package audit`*) - `docs/architecture/template-tiers.md` — must-have vs optional packages and how to scaffold the optionals ## Key Conventions diff --git a/README.md b/README.md index c8bbe42..6907290 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,14 @@ docker compose up -d # Start PostgreSQL ## Optional packages -The default template includes the must-have core packages and all 5 feature packages. Four core packages are optional and scaffold on demand: +The default template includes the must-have core packages and all 5 feature packages. Five core packages are optional and scaffold on demand: ```bash pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016) pnpm turbo gen core-package events # Cross-feature events + Payload jobs (ADR-015) pnpm turbo gen core-package trpc # tRPC server setup pnpm turbo gen core-package ui # Design system +pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018) ``` See `docs/architecture/template-tiers.md` for the full tier list. diff --git a/docs/architecture/data-flow-explainer.html b/docs/architecture/data-flow-explainer.html index d8dff40..c095fe9 100644 --- a/docs/architecture/data-flow-explainer.html +++ b/docs/architecture/data-flow-explainer.html @@ -1703,8 +1703,8 @@ footer .colophon {

blog/di/bind-production.ts

Called from each app's bootstrap (apps/web-next/src/server/bind-production.ts) with the ctx object built once by the aggregator. BindProductionContext is imported from @repo/core-shared/di.

export function bindProductionBlog(ctx: BindProductionContext): void {
-  // bus is optional — present only when @repo/core-events is scaffolded
-  const { config, tracer, logger, bus, queue, realtime, realtimeRegistry } = ctx;
+  // bus, realtime, realtimeRegistry, auditLog are optional — present only when the corresponding optional package is scaffolded
+  const { config, tracer, logger, bus, queue, realtime, realtimeRegistry, auditLog } = ctx;
   if (blogContainer.isBound(BLOG_SYMBOLS.IArticlesRepository)) {
     blogContainer.unbind(BLOG_SYMBOLS.IArticlesRepository);
   }
@@ -2193,7 +2193,7 @@ footer .colophon {
     

       
di/bind-production.ts

       
Production binder

-      
bindProduction<F>(ctx: BindProductionContext) — unbinds the mock, rebinds the real Payload-backed impl. The ctx arg carries required fields (tracer, logger, config) and optional cross-cutting deps (queue). Event bus (bus) is also optional — present only when @repo/core-events is scaffolded via pnpm turbo gen core-package events; absent, bus?.subscribe/publish calls are no-ops. Realtime deps (realtime, realtimeRegistry) are also optional — present only when @repo/core-realtime is scaffolded via pnpm turbo gen core-package realtime.

+      
bindProduction<F>(ctx: BindProductionContext) — unbinds the mock, rebinds the real Payload-backed impl. The ctx arg carries required fields (tracer, logger, config) and optional cross-cutting deps (queue). Event bus (bus) is also optional — present only when @repo/core-events is scaffolded via pnpm turbo gen core-package events; absent, bus?.subscribe/publish calls are no-ops. Realtime deps (realtime, realtimeRegistry) are also optional — present only when @repo/core-realtime is scaffolded via pnpm turbo gen core-package realtime. Audit log (auditLog) is also optional — present only when @repo/core-audit is scaffolded via pnpm turbo gen core-package audit; absent, ctx.auditLog?.record(entry) calls are no-ops. When present, auditLog is a TraceIdEnrichingAuditLog that auto-populates AuditEntry.correlationId from the active OTel span.

       

         
Pros
    
           
  • Decouples Payload config from the feature package — boundary stays clean
    • 
diff --git a/docs/architecture/template-tiers.md b/docs/architecture/template-tiers.md
index 1ce9a8a..23027a3 100644
--- a/docs/architecture/template-tiers.md
+++ b/docs/architecture/template-tiers.md
@@ -21,6 +21,7 @@ Plus all 5 feature packages: auth, blog, marketing-pages, navigation, media.
 | core-events | `pnpm turbo gen core-package events` | ADR-015 | docs/guides/events-and-jobs.md |
 | core-trpc | `pnpm turbo gen core-package trpc` | (none) | (none) |
 | core-ui | `pnpm turbo gen core-package ui` | (none) | (none) |
+| core-audit | `pnpm turbo gen core-package audit` | ADR-018 | docs/guides/audit-and-compliance.md |
 
 ## Why optional
 
diff --git a/docs/scaffolding/core-package-generator.md b/docs/scaffolding/core-package-generator.md
index 115bcea..ecdbc26 100644
--- a/docs/scaffolding/core-package-generator.md
+++ b/docs/scaffolding/core-package-generator.md
@@ -23,6 +23,7 @@ The generator emits the package files, updates consuming-app config (e.g. `apps/
 | `events` | Cross-feature event bus + Payload jobs adapter (ADR-015) | Phase 4 |
 | `trpc` | tRPC server setup | Phase 5 |
 | `ui` | Design-system package | Phase 6 |
+| `audit` | DPA-compliant audit logging (ADR-018) | Phase 7 |
 
 ## Verifying an existing project