Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-inventory/foundation.md
T

304 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Boilerplate-Inventur: Foundation & Querschnitt
> Faktische Inventur der Querschnitts-Pakete im Boilerplate-Monorepo
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`). Nachschlagewerk für
> die Modul-Abgleich-Agenten (HiveGrid M001–M017). Alle Pfade absolut.
> Stand der Quellen: Boilerplate-Repo, gelesen ohne Änderungen.
## Überblick
| Paket | npm-Name | Pfad | Zweck (1 Satz) |
| --- | --- | --- | --- |
| foundation | `@toolctrl/foundation` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation` | Reine, DB-/Framework-agnostische Querschnitt-Primitiven (Errors, Audit, Permissions, Flags, Idempotency, Adapters, Notifications, Workflows, Concurrency, sichere Outbound-HTTP). |
| view-models | `@toolctrl/view-models` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models` | VM-State-Maschine, Action-Callbacks und Registry-Gate/Shell-Registry-Typen für UI-ViewModels. |
| entitlements | `@toolctrl/entitlements` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/entitlements` | Feature-Gate-Registry, Entitlement-Auswertung, Standard-Pläne, Produkt-Blueprints, AI-Quotas/Overage. |
| feature-flags | `@toolctrl/feature-flags` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/feature-flags` | Feature-Flag-Engine v2: Targeting-Regeln, Evaluation, Cache, Invalidierung, React-Client-Hooks. |
| i18n | `@toolctrl/i18n` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n` | Locale-Config, Intl-Formatter (Zahl/Währung/Datum/Liste), ICU-MessageFormat, RTL, `useTranslate`-Factory. |
| logger | `@toolctrl/logger` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/logger` | Pino-Logger-Factory mit Redaction sensibler Felder. |
| observability | `@toolctrl/observability` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/observability` | PII-scrubbender OpenTelemetry-SpanProcessor (framework-agnostisch). |
| metrics | `@toolctrl/metrics` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/metrics` | prom-client Registry/Default-Metriken, Token-Auth für `/metrics`, AI-Cost-Counter mit Cardinality-Disziplin. |
| error-reporter | `@toolctrl/error-reporter` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/error-reporter` | Error-Reporter-Interface, Sanitizer, Sentry-Adapter, OTel-Tracing-Bootstrap. |
| url | `@toolctrl/url` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/url` | Kanonische Pfad-/URL-Builder (app/admin/api, host-aware). |
| config | `@toolctrl/config` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/config` | Env-Variablen-Katalog + Validierung, Web/API/Worker-Config-Loader, Domain-Routing, Session-Cookie-Policy, Secret-Validatoren. |
| shared | `@toolctrl/shared` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/shared` | **Aktuell leer** (`src/index.ts` enthält nur `export {}`). Platzhalter für künftige dependency-freie Cross-Cutting-Typen/Utils. |
Konventionen über alle Pakete:
- `"type": "module"`, `"sideEffects": false`, `"private": true`, `version` `0.0.0`.
- Exports zeigen auf `./src/*.ts` (kein Build-Step; `build` = `typecheck`).
- Interne Imports verwenden `.js`-Endungen (ESM/NodeNext), z. B. `export * from "./errors.js"`.
- Tests liegen als `*.test.ts(x)` neben der Quelle; `pnpm test` = `vitest run src`.
- Pakete sind bewusst Prisma-/Framework-frei: DB-Zugriff wird per strukturell typisiertem Client-Parameter (`*Client`) bzw. Loader-Callback injiziert.
---
## @toolctrl/foundation
**Zweck:** Zentrale, reine Querschnitt-Bausteine ohne harte DB-/HTTP-Framework-Abhängigkeit. Prisma-Tabellen werden über strukturell typisierte Client-Interfaces erwartet (Dependency Injection statt Import).
**Zentrale Dateien**
- Barrel: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/index.ts` (re-exportiert errors, audit, permissions, flags, idempotency, adapters, notifications, workflows, concurrency).
- `package.json` exportiert zusätzlich `./outbound-http`.
**Haupt-Exporte je Modul**
| Datei (absolut) | Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/packages/foundation/src/errors.ts` | `CatalogError` (Klasse), `CatalogErrorDefinition`, `catalogRegistry` (leer-frozen), `foundationErrors` (`forbidden` 403, `notFound` 404, `idempotencyConflict` 409, `idempotencyInProgress` 409), `toPinoLogObject(error)`, Typen `JsonValue`/`JsonPrimitive` | Querschnitt „Klartext-Diagnostik/CatalogError" — strukturierter Fehler mit `code`/`status`/`i18nKey`/`details` für alle Module M001–M017. `toPinoLogObject` für Logger-Integration. |
| `…/packages/foundation/src/audit.ts` | `auditEvent(input, client)`, `withAuditMiddleware(handler, buildEvent, client)`, Typen `AuditEventInput`, `AuditEventClient` | Querschnitt „Audit-Middleware". `withAuditMiddleware` wrappt Service-Handler und schreibt nach Erfolg ein `AuditEvent`. Relevant für jede mutierende Aktion (M001–M017). |
| `…/packages/foundation/src/permissions.ts` | `requirePermission(ctx, permission)`, `withTenantScope(tenantId, value)`, `withPermission(permission, getContext, handler)`, `withOwnerCheck(ctx, value)`, Typ `PermissionContext` | Querschnitt „withTenantScope/withPermission/withOwnerCheck". Tenant-Scoping + Permission-/Owner-Gating für alle Tenant-Module. Bei Fehlschlag `CatalogError(notFound)` (404, nicht 403 — Existenz-Versteckung). |
| `…/packages/foundation/src/flags.ts` | `defineFlag(def)`, `featureFlag(input)`, `selectFlagRecord(input)`, `normalizeFlagScope(record)`, Typen `FlagDefinition`, `FlagRecord`, `FlagResolutionInput`, `NormalizedFlagScope` | Querschnitt „defineFlag/featureFlag". Leichtgewichtige Flag-Auflösung (user > tenant > global, override). Für einfache Gates ohne Targeting-Engine. |
| `…/packages/foundation/src/idempotency.ts` | `withIdempotency(input, client, operation)`, Typen `IdempotencyClient`, `IdempotencyResponse` | Querschnitt „IdempotencyClient". Replay-sichere Mutationen (scope+key), In-Process-Lock, stabiler Fingerprint-Hash, `409`-Konflikt bei Hash-Mismatch / In-Progress. Für POST-Endpunkte mit Idempotency-Key in jedem Modul. |
| `…/packages/foundation/src/adapters.ts` | `defineAdapter(def)`, `getAdapter(key)`, Typen `AdapterDefinition`, `AdapterStatus` (`not_configured`/`configured`/`healthy`/`degraded`/`unavailable`) | Querschnitt „defineAdapter/getAdapter". Globales Adapter-Register (Provider-Slots) mit Status. `getAdapter` liefert Fallback `not_configured`. Für Provider-/Integrations-Module. |
| `…/packages/foundation/src/notifications.ts` | `notify(input, client, prefs)`, `notifyMany(...)`, `bundleNotifications(inputs)`, `isNotificationEnabled(input, prefs)`, `assertI18nKey(key)`, Typen `NotificationInput`, `NotificationClient`, `NotificationPreference`, `NotificationBundle`, `NotificationPreferenceChannel` (`IN_APP`/`EMAIL`), `NotificationDeliveryStatus` (`PENDING`/`SENT`/`FAILED`/`SKIPPED`/`READ`) | Querschnitt „notify/bundleNotifications". Tenant-pflichtige Notifications mit Preference-Check, Upsert per `sourceKey`, Metadata-Sanitizing (Redaction sensibler Keys), Bundling pro Tenant/User/Channel/Category. `assertI18nKey` erzwingt i18n-Key-Form. |
| `…/packages/foundation/src/workflows.ts` | `workflowBlockContracts`, `getWorkflowBlockContract(value)`, `CORE_/PRO_WORKFLOW_BLOCK_TYPES`, `NATIVE_WORKFLOW_TRIGGER_SUPPORTED_BLOCK_TYPES`, `extractWorkflowReferences(wf)`, `getMissingWorkflowReferences(...)`, `validateWorkflowRequiredInputs(wf)`, `preflightWorkflow(input)`, `getNativeWorkflowTriggerCapabilityErrors(blocks)`, Typen `WorkflowBlockType`, `WorkflowBlockContract`, `WorkflowPreflightResult` u. a. | Workflow-/Automation-Domäne (Block-Verträge, Referenz-Extraktion, Preflight). Relevant für ein evtl. Workflow-/Automations-Modul; ansonsten Querschnitt für Template-Variablen-Validierung. |
| `…/packages/foundation/src/concurrency.ts` | `mapWithConcurrency(items, concurrency, worker)` | Querschnitt-Utility: begrenzte parallele Verarbeitung (Batch-Jobs, Imports). |
| `…/packages/foundation/src/outbound-http.ts` (Subpath `@toolctrl/foundation/outbound-http`) | `fetchOutboundHttpWithRedirects(input, init, options)`, `readLimitedResponseText(response, limit)`, `validateOutboundHttpUrl(endpoint)`, Klasse `OutboundHttpUrlValidationError`, Typen `OutboundHttpFetchOptions`, `OutboundHttpAddressResolver`, `LimitedResponseBody` | Querschnitt-Sicherheit: SSRF-Schutz (Block private/internal IPs v4+v6, DNS-Resolve-Check, Redirect-Limit, Timeout, Response-Size-Limit). Für jede ausgehende HTTP-Aktion (Webhooks, httpRequest-Block, Integrationen). |
**Abhängigkeit:** `@toolctrl/i18n` (workspace).
**Genutzte Prisma-Modelle (per Client-Injection erwartet, Definition siehe unten):**
- `AuditEvent` — `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma:55`
- `IdempotencyKey` — `…/prisma/schema/core.prisma:84` (Unique `@@unique([scope, key], name: "idempotency_key_scope_key")`, passt exakt zur `IdempotencyClient`-Where-Form)
- `NotificationDelivery` / `UserNotificationPreference` — `…/prisma/schema/notifications.prisma:14` / `:41`
---
## @toolctrl/view-models
**Zweck:** Reine Typ-/Helper-Schicht für UI-ViewModels — VM-State-Maschine, Action-Callbacks, Registry-Gate und Shell-Registry-Item-Typen.
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/src/index.ts` (einziges Quellmodul).
| Export | Beschreibung | HiveGrid-Relevanz |
| --- | --- | --- |
| `VMState<T>` (Union), `VMStatus` (`idle`/`loading`/`ready`/`empty`/`error`) | Diskriminierte Status-Maschine; `error` trägt `{ messageKey; code? }` (i18n-Key, kein Klartext) | Querschnitt „VMState" — einheitlicher Loader-/Empty-/Error-State für alle Listen-/Detail-VMs in M001–M017. |
| `ActionCallbacks<T>` (`onCreate`/`onUpdate`/`onDelete`/`onRefresh`) | Standard-CRUD-Callback-Vertrag | Querschnitt „ActionCallbacks" — konsistente Action-Verdrahtung. |
| `RegistryGate` (`{ permission?; flag? }`), `I18nLabel` (`{ labelKey; descriptionKey? }`) | Gating-/Label-Bausteine | Querschnitt „RegistryGate" — Sidebar/Breadcrumb/Mobile/Portal-Einträge per Permission + Flag gaten. |
| `SidebarRegistryItem`, `BreadcrumbRegistryItem`, `MobileRegistryItem`, `PortalRegistryItem`, `ShellRegistries` | Shell-Navigations-Registry-Typen (alle mit `RegistryGate` + `I18nLabel`) | Navigations-Registries für die App-Shell; jedes Modul registriert seine Einträge gegated. |
| `ready<T>(data)`, `empty<T>()` | Konstruktoren für `VMState` | Helper. |
| `assertI18nLabel(label)` | Erzwingt i18n-Key-Form für `labelKey`/`descriptionKey` (wirft sonst) | i18n-Disziplin in Registries. |
Keine Runtime-Dependencies.
---
## @toolctrl/entitlements
**Zweck:** Single Source of Truth für Feature-Gates, Plan-Stubs, Produkt-Blueprints und AI-Quotas/Overage; reine Entitlement-Auswertung.
**Zentrale Datei (Barrel):** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/entitlements/src/index.ts`
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/src/features.ts` | `featureKeys` (19 Keys: `crm-basic`, `support-tickets`, `knowledge-base-read/-tenant`, `users`, `email-marketing`, `imported-lists`, `crm-based-lists`, `onboarding`, `api`, `workflow-engine`, `mcp`, `advanced-builder`, `import-export`, `rate-limit-per-minute/-second`, `priority-support`, `ai-credits`, `private-generations`), `featureGateRegistry`, `getFeatureGate`, `isFeatureKey`, `assertKnownFeatureKey`; Typen `FeatureKey`, `FeatureCategory`, `FeatureLimitType` (`not-included`/`included`/`monthly`/`max`/`unlimited`) | Querschnitt Entitlements: kanonische Feature-Keys + Limit-Typen für Gating in allen Modulen. |
| `…/src/evaluate.ts` | `evaluateEntitlement(input)`, `entitlementLimitTypes` (numerisch 0–4), Typen `EntitlementDecision`, `EntitlementDecisionReason`, `EvaluateEntitlementInput` | Kern-Entscheidung „darf der Tenant?" inkl. Trial-/Subscription-/Usage-Logik (`max`/`monthly` mit `remaining`). |
| `…/src/plans.ts` | `entitlementPlanIds`, `standardEntitlementPlans`, `getStandardEntitlementPlan`, `listStandardEntitlementPlanIds`, `getStripeProductPlaceholder`/`getStripePricePlaceholder`; Typen `EntitlementPlanStub`, `EntitlementPlanFeatureAssignment` u. a. | Standard-Plan-Stubs + Stripe-Placeholder-Mapping (Billing-Querschnitt). |
| `…/src/blueprints.ts` | `productBlueprints`, `productBlueprintIds`, `getProductBlueprint`, `getDefaultProductBlueprint`; Typen `ProductBlueprintDefinition`, `ProductBlueprintFeatureDefinition` | Produkt-Blueprints (Feature-Bündel pro Produkttyp). |
| `…/src/product-access.ts` | `evaluateProductAccess(input)`; Typen `ProductAccessInput`, `ProductAccessDecision`, `TenantFeatureOverride` (`enabled`/`disabled`/`inherit`) | Produkt-Zugriffsentscheidung inkl. Tenant-Override. |
| `…/src/ai-quotas.ts` | `aiQuotaCapabilityKeys`, `standardAIQuotaDefaults`, `getAIQuotaPlanDefaults`, `resolveTenantAIQuota`, `parseTenantAIQuotaOverride`; Typen `AIQuotaPlanDefaults`, `ResolvedTenantAIQuota`, `TenantAIQuotaOverride` | AI-Quoten pro Plan/Tenant — relevant falls HiveGrid AI-Capabilities gated. |
| `…/src/ai-overage.ts` | `resolveTenantAIOverage`, `computeMarkedUpCostCents`, `roundUpToBlock`, `getAIOveragePlanDefaults`, Defaults-Konstanten (`AI_OVERAGE_DEFAULT_MULTIPLIER` 1.5, `…_BLOCK_CENTS` 10, Min-Werte) | AI-Overage-Billing (Markup/Block-Rundung). |
Keine Runtime-Dependencies (rein, testbar). Verknüpfte Prisma-Modelle: `SubscriptionFeature` (`…/prisma/schema/subscriptions.prisma:65`), `PortalSubscriptionFeature` (`…/prisma/schema/portals.prisma:149`).
---
## @toolctrl/feature-flags
**Zweck:** Feature-Flag-Engine v2 mit Targeting-Regelbaum, zeit-/abhängigkeitsbasierter Evaluation, Variant-Bucketing, Eval-Cache und Cross-Process-Invalidierung; optionaler React-Client.
**Subpath-Exports (package.json):** `.` (Barrel), `./targeting`, `./cache`, `./client`.
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/packages/feature-flags/src/index.ts` | re-exportiert targeting + `evaluateFlag`, `getFeatureFlagVariant`, Cache- und Publisher-API | Haupteinstieg. |
| `…/src/evaluate.ts` | `evaluateFlag(name, ctx, options)`, `getFeatureFlagVariant(...)`, Typen `StoredFeatureFlag`, `FlagVariant`, `FlagLoader`, `EvaluateFlagResult` (`reason`: u. a. `flag-not-found`/`disabled`/`parent-disabled`/`time-window-future`/`matched`), `EvaluateFlagOptions` | Querschnitt Feature-Flags (mächtige Variante zu `foundation/flags`): Zeitfenster, Parent-Dependency (Zyklus-Schutz `maxDepth` 8), sticky Variant-Bucketing. DB-frei via `FlagLoader`-Callback. |
| `…/src/targeting/types.ts` | Regel-Union `TargetingRule` (`boolean`/`allowlist`/`percentage`/`plan-tier`/`role-based`/`time-based`/`composite`), `EvaluationContext` (`tenantId`/`userId`/`email`/`planTier`/`roles`/`now`) | Targeting-Modell — Rollouts pro Tenant/Plan/Rolle/Prozent für jedes Modul. |
| `…/src/targeting/evaluator.ts` | `evaluateRule(rule, ctx)` | Reine Regel-Auswertung (kein I/O). |
| `…/src/targeting/percentage.ts` | `computeBucket(key, salt)`, `isInRolloutBucket(...)` | Sticky Percentage-Rollout. |
| `…/src/cache.ts` | `createFlagEvalCache(...)`, `buildCacheKey`, `hashContext`, `FEATURE_FLAGS_INVALIDATION_CHANNEL` (`"feature-flags:invalidate"`), Typ `FlagEvalCache` | Eval-Cache + Invalidierungs-Channel-Konstante. |
| `…/src/publisher.ts` | `publishFeatureFlagInvalidationViaStore(...)`, `publishFeatureFlagInvalidationOnce(...)`, Typ `PublishFeatureFlagInvalidationOptions` | Cross-Process-Cache-Invalidierung (via shared-store). |
| `…/src/client/context.tsx` (Subpath `./client`) | `FeatureFlagProvider`, `useFeatureFlag`, `useFeatureFlagEnabled`, `useFeatureFlagVariant`, Typen `FeatureFlagProviderProps`, `FeatureFlagsHydration` | React-Hooks/SSR-Hydration für Flag-gegatete UI. |
**Dependencies:** `@toolctrl/shared-store` (Pub/Sub); optionale Peers `@toolctrl/logger`, `react`.
**Prisma-Modelle:** `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` (append-only Audit-Trail) — `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/featureFlags.prisma:1/32/44`. `StoredFeatureFlag` spiegelt eine Teilmenge der `FeatureFlag`-Row, bleibt aber Prisma-frei.
---
## @toolctrl/i18n
**Zweck:** Locale-Konfiguration, SSR-sichere Intl-Formatter, ICU-MessageFormat-Pluralisierung, RTL-Erkennung und `useTranslate`-Hook-Factory.
**Subpath-Exports:** `.` (Barrel), `./intl`, `./icu`, `./useTranslate`.
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/packages/i18n/src/index.ts` | `defaultLocale` (`"de"`), `supportedLocales` (`["de","en"]`), `i18nNamespaces` (`translations`, `errors`, `mail`, `common`, `settings`, `billing`, `crm`, `auth`, `emailMarketing`), `i18nConfig`, `isSupportedLocale`, `getDirection`, `isRTL`; re-exportiert Intl + ICU + `useTranslate` | Querschnitt i18n: Namespaces/Locales als SSOT; `assertI18nKey`/`assertI18nLabel` (in foundation/view-models) erzwingen Key-Form passend zu diesen Namespaces. |
| `…/src/intl/index.ts` → `number.ts`/`currency.ts`/`date.ts`/`list.ts` | `formatNumber`, `formatPercent`, `formatCompactNumber`, `formatCurrency`, `formatDate`, `formatRelativeTime`, `formatList` (+ Options-Typen) | Einheitliche, locale-explizite Formatierung server- wie clientseitig (Listen, Detail-Views, Mails). |
| `…/src/icu/index.ts` → `plural.ts` | `formatIcu`, `createIcuFormatter`, Typen `IcuValues`, `IcuOptions`, `IcuFormatter` | ICU-Plurale/Select für korrekte mehrsprachige Texte. |
| `…/src/useTranslate.ts` | `createUseTranslate(deps, defaults)`, `isIcuMessage`, Typen `Translator`, `ReactI18nextLike`, `UseTranslateOptions` | React-`useTranslate`-Factory mit automatischer ICU-Erkennung; react-i18next wird injiziert (kein harter Dep). |
**Dependencies:** `i18next`, `intl-messageformat`.
**Konvention (Querschnitt „i18n-assert"):** i18n-Keys folgen dem Muster `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$` — durchgesetzt von `assertI18nKey` (foundation/notifications.ts) und `assertI18nLabel` (view-models). Fehler-Objekte tragen statt Klartext einen `i18nKey` (siehe `CatalogError`, `VMState.error.messageKey`).
---
## @toolctrl/logger
**Zweck:** Pino-Logger-Factory mit eingebautem Redaction sensibler Felder.
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/logger/src/index.ts`
| Export | Beschreibung | HiveGrid-Relevanz |
| --- | --- | --- |
| `createLogger(options?)` | Erzeugt Pino-Logger; `redact.paths` deckt `authorization`, `cookie`, `password`, `token`, `secret`, `apiKey`, `redisUrl`, `connectionString` (inkl. `*.`-Wildcards) ab, Censor `[Redacted]` | Querschnitt Logging: sicheres, strukturiertes Logging für alle Module. Spielt mit `toPinoLogObject` (foundation/errors) zusammen. |
| `createChildLogger(logger, bindings)` | Child-Logger mit Bindings (z. B. `requestId`, `tenantId`) | Request-/Tenant-Scoped Logging. |
| `resolveLogLevel(env?)` | Liest `TOOLCTRL_LOG_LEVEL`/`LOG_LEVEL` (Default `info`) | Env-getriebenes Level. |
| `defaultLogger` | Vorinstanziierter Default | — |
| Typen `LogLevel`, `ToolctrlLogger`, `CreateLoggerOptions` | — | — |
**Dependency:** `pino`.
---
## @toolctrl/observability
**Zweck:** Framework-agnostischer PII-scrubbender OpenTelemetry-SpanProcessor (Decorator über bestehenden Processor; keine harte OTel-SDK-Dependency).
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/observability/src/pii-span-processor.ts` (Barrel: `…/src/index.ts`).
| Export | Beschreibung | HiveGrid-Relevanz |
| --- | --- | --- |
| `PIISpanProcessor` | Wrappt Delegate-Processor, redigiert Attribute in `onEnd()` | Querschnitt Observability: verhindert PII-Leak in Traces für alle Module. |
| `HEADER_ALLOWLIST` | Erlaubte Header-Attribute (Rest, u. a. `authorization`/`cookie`/`x-api-key`, wird gedroppt) | — |
| `redactSpanAttributes`, `scrubDbStatement`, `scrubUrlQuery`, `isHeaderAttribute` | Einzel-Scrubber (Query-String → `?[scrubbed]`, DB-Literale → `?`) | — |
| Typen `DelegateSpanProcessor`, `PiiScrubableSpan` | Strukturelle OTel-Shapes (keine SDK-Bindung) | — |
Keine Runtime-Dependencies.
---
## @toolctrl/metrics
**Zweck:** prom-client basierte Metrics-Registry, Default-HTTP-Metriken, Token-Auth für den `/metrics`-Endpoint und cardinality-disziplinierter AI-Cost-Counter.
**Zentrale Datei (Barrel):** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/metrics/src/index.ts`
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/src/registry.ts` | `createMetricsRegistry(options)`, Typen `MetricsRegistry`, `CreateMetricsRegistryOptions` | Querschnitt Metrics: zentrale Registry je App. |
| `…/src/defaults.ts` | `createDefaultMetrics(registry)`, `HISTOGRAM_BUCKETS_SECONDS`, Typen `DefaultMetrics`, `LatencyHistogramOptions` | Standard-Latenz-/Request-Metriken. |
| `…/src/auth.ts` | `isMetricsEnabled(env)`, `validateMetricsTokenAuth(options)`, `redactMetricsToken(token)`, Typen `MetricsTokenAuthResult`, `MetricsTokenAuthOptions` | Schützt `/metrics`-Endpoint per Token. |
| `…/src/ai-cost.ts` | `recordAICostCents(input, registry)`, `resetAICostMetricsForTests()`, Konstanten `MAX_TENANT_BUCKETS` (100), `OTHER_BUCKET`, `ANONYMOUS_BUCKET`, Typ `AICostMetricInput` | AI-Kosten-Counter `ai_cost_cents_total{tenant_bucket,provider,model,capability}` mit Top-N+Other-Bucketing (Cardinality-Schutz). |
**Dependency:** `prom-client`.
---
## @toolctrl/error-reporter
**Zweck:** Provider-agnostisches Error-Reporting (Interface + No-op + Sentry-Adapter), Sanitizing sensibler Daten und optionaler OTel-Tracing-Bootstrap.
**Zentrale Datei (Barrel):** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/error-reporter/src/index.ts`
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/src/index.ts` | `reportError(reporter, event)` (schluckt Reporter-Fehler), `createNoopErrorReporter()`, Typen `ErrorReporter`, `ErrorReportEvent`, `ErrorReportContext`, `ErrorReportSeverity` | Querschnitt Error-Reporting: einheitliches Melden inkl. `component`/`operation`/`requestId`/`tenant`-Kontext. Sanitisiert vor Versand. |
| `…/src/sanitize.ts` | `sanitizeErrorReportValue(value)`, `__internal` | Entfernt sensible Felder vor Reporting. |
| `…/src/sentry.ts` | `createSentryErrorReporter(options)`, `sanitizeSentryEvent(raw)`, `SENTRY_HEADER_ALLOWLIST`, `SENTRY_DROP_EXCEPTION_TYPES`, Typen `SentryErrorReporterOptions`, `SentryLikeModule`, `SentryInitOptions` | Optionaler Sentry-Adapter (Sentry-SDK strukturell injiziert). |
| `…/src/tracing.ts` | `initializeTracing(options)`, `shutdownTracing()`, Typen `TracingOptions`, `NodeSdkLikeModule`, `OtlpExporterLikeModule` | OTel-NodeSDK-Bootstrap mit OTLP-Exporter; OTel-Pakete via dynamic import optional. |
Keine festen Runtime-Dependencies (SDKs strukturell/optional).
---
## @toolctrl/url
**Zweck:** Kanonische, host-aware Pfad- und URL-Builder für App-/Admin-/API-Surfaces (multi-tenant Subdomains).
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/url/src/canonical.ts` (Barrel: `…/src/index.ts`).
| Export | Beschreibung | HiveGrid-Relevanz |
| --- | --- | --- |
| `appPath`/`appUrl` (mit `tenantSlug`), `adminPath`/`adminUrl`, `apiPath`/`apiUrl` (mit `version` `v1`), `default` | Bauen relative Pfade bzw. absolute URLs (`mode: "host-aware"`, Default-Protokoll `https`) | Querschnitt Routing/Links: konsistente Tenant-App-, Admin- und API-Links für alle Module (M001–M017). |
| Typen `AppUrlOptions`, `AdminUrlOptions`, `ApiUrlOptions`, `CanonicalUrlMode`, `ApiVersion`, `PathInput` u. a. | — | — |
Keine Runtime-Dependencies.
---
## @toolctrl/config
**Zweck:** Typisierter Env-Variablen-Katalog (SSOT für Doku/Drift), Validierungs-Helfer, Web/API/Worker-Config-Loader, Domain-Routing und Session-Cookie-Policy.
**Zentrale Datei (Barrel):** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/config/src/index.ts`
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
| --- | --- | --- |
| `…/src/index.ts` | `listEnvVariables(opts)`, `getEnvVariableDefinition(name)`, `groupEnvVariablesByClassification()`, `getRequiredEnvVariableNames(opts)`, `validateEnv(input, opts)`, `envVariableDefinitions` | Querschnitt Konfiguration: Env-Anforderungen pro Runtime-Target ableiten/validieren. |
| `…/src/catalog.ts` | `envVariableDefinitions` (große Liste; jede mit `classification`, `targets`, `kind`, `source`, `requiredInProduction`) | Single Source of Truth aller Env-Variablen. |
| `…/src/types.ts` | Typen `RuntimeTarget` (`shared`/`web`/`api`/`worker`), `EnvClassification` (6 Klassen), `EnvVariableDefinition`, Web/Api/Worker-Config-Shapes (`WebConfig`, `ApiConfig`, `WorkerConfig`, …) | Config-Vertrag. |
| `…/src/web.ts` / `api.ts` / `worker.ts` | `loadWebConfig`/`loadRequiredWebConfig` (+ `WebConfigError`); analog API/Worker | Runtime-Config-Loader mit Diagnostics. |
| `…/src/routing.ts` | `getDomainRoutingConfig`, `hostMatches`, `normalizeHost`, Typen `DomainRoutingConfig`, `DomainRoutingEnv` | Multi-Tenant Domain-Routing (passt zu `@toolctrl/url`). |
| `…/src/session-cookie.ts` | `resolveSessionCookiePolicy`, `resolveApiSessionCookiePolicy`, Typen `SessionCookiePolicy`, `SessionCookieSameSite` | Sichere Session-Cookie-Policy. |
| `…/src/secret-validator.ts` | `validateRequiredSecretString`, `validateOptionalSecretString`, `validateOptionalSecretUrl`, `validateBooleanFlag` | Secret-/Flag-Validierung mit Diagnostics. |
| `…/src/plugin-lifecycle.ts` | `resolvePluginLifecycleRuntimeEnv`, Typ `PluginLifecycleRuntimeEnv` | Plugin-Lifecycle-Env. |
Keine deklarierten Runtime-Dependencies. README dokumentiert die Klassifikation und das vollständige Inventar (`…/packages/config/README.md`).
---
## @toolctrl/shared
**Zweck:** Reservierter Platz für dependency-freie, app-übergreifende Typen/Konstanten/Utilities.
**Status:** **Leer.** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/shared/src/index.ts` enthält ausschließlich `export {};`. README (`…/packages/shared/README.md`) beschreibt nur geplante Kandidaten und die Regel „kein web/API/worker/provider/DB-spezifischer Code". Für M001–M017 derzeit ohne nutzbaren Inhalt.
---
## Relevante Prisma-Modelle (Querschnitt) — exakte Pfade
| Modell | Pfad | Genutzt von |
| --- | --- | --- |
| `AuditEvent` | `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma:55` | foundation `audit.ts` (`AuditEventClient`). Felder u. a. `tenantId`, `actorType` (req.), `action`, `targetType/Id`, `requestId`, `outcome` (Default `success`), `dataSensitivity`, `regulatoryScope[]`, `metadata`, `previousHash`/`eventHash` (Hash-Chain). |
| `IdempotencyKey` | `…/prisma/schema/core.prisma:84` | foundation `idempotency.ts`. `@@unique([scope, key], name: "idempotency_key_scope_key")` deckt die `IdempotencyClient`-Where-Form, `expiresAt`-Index für Cleanup. |
| `NotificationDelivery` | `…/prisma/schema/notifications.prisma:14` | foundation `notifications.ts`. Enums `NotificationDeliveryStatus`/`NotificationPreferenceChannel`; `@@unique([tenantId, userId, channel, sourceKey])` für Upsert. |
| `UserNotificationPreference` | `…/prisma/schema/notifications.prisma:41` | foundation `notifications.ts` (`NotificationPreference`). |
| `FeatureFlag` / `FeatureFlagFilter` / `FeatureFlagAudit` | `…/prisma/schema/featureFlags.prisma:1` / `:32` / `:44` | feature-flags-Paket (`StoredFeatureFlag` spiegelt Teilmenge; v2-Felder `rules`/`variants`/`enabledFrom`/`enabledUntil`/`parentFlagId`). |
| `SubscriptionFeature` | `…/prisma/schema/subscriptions.prisma:65` | entitlements (Plan-Feature-Zuordnung). |
| `PortalSubscriptionFeature` | `…/prisma/schema/portals.prisma:149` | entitlements (Portal-Features). |
---
## CI-/Verify-Scripts (Querschnitt-relevant)
Pfade: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/scripts/…`; npm-Scripts in `…/boilerplate/package.json`.
| Script (npm) | Datei | Bezug |
| --- | --- | --- |
| `verify:i18n` | `scripts/i18n-check.ts` + `scripts/verify-hardcoded-strings.mjs` + ESLint über `packages/ui-*` | i18n-Disziplin (Querschnitt i18n / i18n-assert). |
| `verify:env-drift` | `scripts/check-env-drift.mjs` | Prüft `@toolctrl/config`-Katalog gegen `.env*`-Beispiele + Code. |
| (Baseline) | `scripts/i18n-audit.mjs` | Baseline-Scan hardcodierter DE/EN-Strings (zählt, erzwingt nicht). |
| `verify:audit-cascade-guard` (Datei vorhanden) | `scripts/verify-audit-cascade-guard.mjs` | Schützt Audit-Cascade-Verhalten (`prisma/schema/accounts.prisma`). |
| `verify:workflow-outbox-native` | u. a. `packages/foundation/src/workflows.test.ts` | Workflow-Block-/Preflight-Verträge (foundation `workflows.ts`). |
| `verify:tenant-isolation-report` | `scripts/tenant-isolation-report.ts` | Tenant-Scoping-Report (passt zu `withTenantScope`). |
Zusätzlich besitzt jedes Paket `pnpm test` (vitest über `src`) und `pnpm typecheck`. Test-Dateien liegen jeweils neben der Quelle (z. B. `audit.test.ts`, `idempotency`-Coverage in `index.test.ts`/`concurrency.test.ts`, `evaluate.test.ts`, `pii-span-processor.test.ts`, `secret-validator.test.ts`).
---
## Kurz-Mapping „angefragte Querschnitt-Patterns → Fundort"
| Angefragtes Pattern | Fundort (Export → Datei) |
| --- | --- |
| Audit-Middleware | `withAuditMiddleware`, `auditEvent` → `…/foundation/src/audit.ts` |
| Klartext-Diagnostik / CatalogError | `CatalogError`, `foundationErrors`, `catalogRegistry`, `toPinoLogObject` → `…/foundation/src/errors.ts` |
| i18n-assert | `assertI18nKey` → `…/foundation/src/notifications.ts`; `assertI18nLabel` → `…/view-models/src/index.ts`; Key-Regex; `verify:i18n` |
| withTenantScope / withPermission / withOwnerCheck | alle → `…/foundation/src/permissions.ts` (+ `requirePermission`) |
| defineFlag / featureFlag | → `…/foundation/src/flags.ts` (leichtgewichtig); mächtige Engine: `evaluateFlag` → `…/feature-flags/src/evaluate.ts` |
| IdempotencyClient | `withIdempotency`, `IdempotencyClient` → `…/foundation/src/idempotency.ts` |
| defineAdapter / getAdapter | → `…/foundation/src/adapters.ts` |
| notify / bundleNotifications | `notify`, `notifyMany`, `bundleNotifications`, `isNotificationEnabled` → `…/foundation/src/notifications.ts` |
| VMState / ActionCallbacks / RegistryGate | alle → `…/view-models/src/index.ts` |