Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,252 @@
|
||||
# Boilerplate-Inventur: Apps & Infra
|
||||
|
||||
Faktische Bestandsaufnahme der Boilerplate unter `/Users/raffaelsheikh/Documents/GitHub/boilerplate`.
|
||||
Bereich: deploybare Apps (API, Worker, Mobile, Hocuspocus) + Root-Config, CI-Gates (`.gitea`), `verify:*`-Scripts, Dockerfile, `infra/`, `react-router.config.ts`.
|
||||
|
||||
Stand: nur dokumentiert, was tatsaechlich existiert. Pfade sind absolut.
|
||||
Nicht-Apps-Pakete (`apps/web`, `apps/storybook`) werden hier nur erwaehnt, wo Apps&Infra darauf verweisen — sie gehoeren zu anderen Inventur-Bereichen.
|
||||
|
||||
Konventionen, die uebergreifend gelten:
|
||||
- Alle Apps sind pnpm-Workspace-Pakete unter `@toolctrl/*`, `"type": "module"`, ESM mit `.js`-Suffix in relativen Imports (TS-NodeNext).
|
||||
- Geteilte Logik kommt aus `@toolctrl/*`-Workspace-Paketen (`config`, `db`, `logger`, `metrics`, `queue`, `storage`, `shared-store`, `observability`, `foundation`, `plugin-runtime`, `mail`, `ai`, `search`, `vector-store`, `exports`, `imports`, `entitlements`, `email-sequences`, `email-templates`, `marketing-outbound`, `form-widget`, `realtime`, `error-reporter`).
|
||||
- Keine App besitzt ein eigenes Prisma-Schema. Alle DB-Zugriffe laufen ueber `@toolctrl/db` (`@toolctrl/db/client.server`, `@toolctrl/db/*.server`). Modelle liegen in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`.
|
||||
- Jede App haelt `src/otel.ts` (OpenTelemetry, self-noop ohne `OTEL_EXPORTER_OTLP_ENDPOINT`) und `src/sentry.ts` (self-disable ohne DSN).
|
||||
- Build via `node scripts/build.mjs` pro App; OTel-Datei steht in `package.json` `sideEffects`.
|
||||
|
||||
---
|
||||
|
||||
## 1. `@toolctrl/api` — Public-API-Runtime (Hono)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/api`
|
||||
**Zweck:** Dedizierte Hono-API-App fuer `api.<domain>/v1`. Kanonischer API-Host fuer externe Integrationen; betreibt API-eigene Usage- und Billing-Webhook-Handler im eigenen Runtime statt ueber Web-Proxy. Listen-Port: `API_PORT` -> `PORT` -> `3001`.
|
||||
|
||||
**Stack:** `hono` 4, `@hono/node-server`, `zod`, `bcryptjs`, `jsonwebtoken`, `stripe` 19, `@sentry/node`, OpenTelemetry.
|
||||
|
||||
**Scripts (`package.json`):** `dev` (`tsx watch src/server.ts`), `start` (`node dist/server.js`), `typecheck`, `build` (`node scripts/build.mjs`). Package-Export: `"./openapi": "./src/openapi.ts"`.
|
||||
|
||||
### Zentrale Dateien
|
||||
|
||||
| Datei | Pfad | Inhalt |
|
||||
|---|---|---|
|
||||
| App-Komposition | `apps/api/src/app.ts` | `export const app = new Hono<ApiEnv>()`; Middleware-Kette + Route-Registrierung. Bewusst listener-frei (Tests/Adapter importieren die App). |
|
||||
| Server-Entry | `apps/api/src/server.ts` | Startet den HTTP-Listener. |
|
||||
| Dependency-Injection | `apps/api/src/app-dependencies.ts` | `getApiAppDependencies()`, `configureApiAppDependenciesForTests()`, Typ `ApiAppDependencies` (DB-Readiness, Usage, Billing). |
|
||||
| Env-Typen | `apps/api/src/api-types.ts` | `ApiEnv` (Hono-Context-Typ). |
|
||||
| OpenAPI | `apps/api/src/openapi.ts` | OpenAPI-Contract-Bausteine (Error-Envelope-Schema mit `code`/`message`/`requestId`, Rate-Limit-Responses); via `verify:openapi-security` geprueft. |
|
||||
| Route-Inventar | `apps/api/src/route-access-inventory.ts` | `routeAccessInventory` + `routeAccessClasses` (11 Klassen: `public-health`, `public-docs`, `service-token`, `service-or-tenant-api-key`, `tenant-api-key`, `webhook-signature`, `jwt-auth`, `auth-credential-exchange`, `public-analytics-token`, `optional-api-key-validation`, `canonical-redirect`). Quelle der Wahrheit fuer Auth-Klasse je Route. |
|
||||
| Auth-Primitive | `apps/api/src/auth.ts` | `authenticateServiceRequest`, `extractBearerToken`, `extractApiKeyFromRequest`, `isValidServiceToken`, `createServicePrincipal`, Typ `ServicePrincipal` (Service-Token via `API_ACCESS_TOKEN`). |
|
||||
|
||||
### Route-Module (`apps/api/src/routes/`)
|
||||
|
||||
`accounts-routes.ts`, `analytics-routes.ts`, `auth-routes.ts`, `devices-routes.ts`, `entity-row-routes.ts`, `maintenance-routes.ts`, `metrics.ts`, `notifications-routes.ts`, `relationship-routes.ts`, `system-routes.ts`, `workspace-routes.ts`, `shared.ts`, `status.ts`. Registriert in `app.ts` via `register*Routes(app)`.
|
||||
Dokumentierte Endpunkte (README + app.ts): `GET /v1/health`, `GET /healthz`, `GET /readyz`, `GET /status`, `GET /metrics` (token), `GET /v1/openapi.json`, `GET /v1/docs`, `GET /v1/session/current-user`, `POST /v1/api-keys/validate`, `GET /v1/accounts[/:id]`, `GET /v1/usage`, `/v1/entities/*`, `/v1/relationships/*`, `/v1/exports/*`, `/v1/workspaces/*`, `POST /v1/billing/stripe/webhooks`, `POST /v1/events/webhooks/attempts/:id`.
|
||||
|
||||
### Querschnitt-Module (`apps/api/src/`)
|
||||
|
||||
- Auth-Tiefe: `auth/cookie/session-cookie.ts`, `auth/session/session-store.ts`, `auth/login-rate-limit.ts`, `auth/permission.ts`, `auth/scope.ts`.
|
||||
- Middleware (`middleware/`): `sentryTracing.ts` (muss erstes Middleware sein), `request-id.ts`, `audit-context.ts`, `body-limit.ts`, `metrics.ts`, `error-envelope.ts` (`createErrorHandler`/`createNotFoundHandler`). Security-Header + CORS direkt in `app.ts`.
|
||||
- Billing: `billing/stripe-webhook-route.ts` (`postStripeBillingWebhookRequest`).
|
||||
- Idempotenz: `idempotency/store.ts`, `idempotency/shared-store-client.ts`.
|
||||
- Weitere: `usage/usage-route.ts`, `pagination/rows.ts`, `cache/subscription-cache-publisher.ts`, `export-progress.ts`, `exportRetentionQueue.ts`, `webhookDeliveryQueue.ts`, `webhooks/mailersend-signature.ts`, `email-sequences/provider-webhook-route.ts`, `platform/maintenance/maintenance.ts` (Maintenance-Middleware), `plugin-hook-publisher.ts`, `validation/request-schemas.ts`, `config.ts` (Env via `@toolctrl/config`).
|
||||
|
||||
**Prisma-Modelle:** keine eigenen — DB-Zugriff via `@toolctrl/db`.
|
||||
|
||||
**HiveGrid-Relevanz:** Fundament fuer die **Public-API / externe API** (Service-Token + Tenant-API-Key, OpenAPI-Contract, Route-Access-Inventar als Auth-Matrix). Direkt nutzbar fuer HiveGrid-Module, die externen API-Zugriff brauchen (Integrations, Webhooks, Usage/Billing-Ingress, Entity-/Relationship-CRUD ueber API). Error-Envelope + Request-ID-Korrelation sind ein wiederverwendbares API-Querschnittsmuster.
|
||||
|
||||
---
|
||||
|
||||
## 2. `@toolctrl/worker` — BullMQ-Worker-Runtime (Cron + Queue-Consumer)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker`
|
||||
**Zweck:** Opt-in BullMQ-Worker. Standardmaessig deaktiviert (`WORKER_ENABLED!="true"` -> sofortiger Exit). Bei Aktivierung benoetigt `DATABASE_URL`; Redis aus `BULLMQ_REDIS_URL` (Fallback `REDIS_URL`). Verarbeitet Queue-Jobs + registriert single-instance Cron-Scheduler.
|
||||
|
||||
**Stack:** `bullmq` 5, `ioredis`, `pino`, `prom-client`, `@aws-sdk/client-s3` + `lib-storage`, `@qdrant/js-client-rest`, `meilisearch`, `clamscan`, `gpt-tokenizer`, `semver`, `stripe`, `@sentry/node`, OTel. Breitester `@toolctrl/*`-Abhaengigkeitsgraph aller Apps (u.a. `ai`, `search`, `vector-store`, `exports`, `imports`, `mail`, `marketing-outbound`, `entitlements`, `email-sequences`, `form-widget`).
|
||||
|
||||
**Scripts:** `dev` (`tsx src/index.ts`), `start`, `health` (`node dist/health.js`), `build`, `typecheck`.
|
||||
|
||||
### Zentrale Dateien
|
||||
|
||||
| Datei | Pfad | Inhalt |
|
||||
|---|---|---|
|
||||
| Entry | `apps/worker/src/index.ts` | Boot: laedt `otel.js` zuerst, validiert `WORKER_QUEUE_GROUP`, startet Runtime + Admin/Health-Server + alle Cron-Scheduler. ~1678 Zeilen. |
|
||||
| Runtime | `apps/worker/src/runtime.ts` | `startWorkerRuntime` / `shutdownWorkerRuntime`, Typ `WorkerRuntimeStatus`. |
|
||||
| Handler-Registry | `apps/worker/src/handlers.ts` | `buildHandlerRegistry(deps)`, `createRegisteredProcessor`, Typ `HandlerDependencies` (DI-Seams fuer mail/scan/export/import/notification/plugin/dsgvo/ai-cost). Pro `QueueName` ein Handler. |
|
||||
| Queue-Auswahl | `apps/worker/src/queues.ts` | `getWorkerQueueNames(env)`, `defaultWorkerQueueNames` (`email`, `notifications`); Feature-Flags `IMPORT_QUEUE_ENABLED`, `EXPORT_RETENTION_QUEUE_ENABLED`, `SCAN_QUEUE_ENABLED`. |
|
||||
| Queue-Gruppen | `apps/worker/src/group-runtime.ts` | `bootstrapWorkerGroup`, `resolveWorkerQueueGroup`, `resolveGroupConcurrency`, `InvalidWorkerQueueGroupError`, `DEFAULT_GROUP_CONCURRENCY`. Gruppen: `general`(10), `mail`(5), `import`(1), `webhook`(20), `plugin`(5); Override `WORKER_CONCURRENCY_<GROUP>`. |
|
||||
| Connection | `apps/worker/src/connection.ts` | `createWorkerConnection(group)` — ioredis-Verbindung getaggt `worker-<group>-<pid>`. |
|
||||
| Admin-Server | `apps/worker/src/admin-server.ts` | `startWorkerAdminServer` — `/status` (JSON) + `/metrics` (token, nur bei `METRICS_ENABLED`), Typ `WorkerStatusReport`. |
|
||||
| Health-Server | `apps/worker/src/health-server.ts` | `startWorkerHealthServer` — Liveness/Readiness inkl. Redis-/DB-Probes, getrennter Port. |
|
||||
| Outbox | `apps/worker/src/outbox/{bootstrap,dispatcher,event-router}.ts` | Transactional-Outbox-Dispatcher (FOR UPDATE SKIP LOCKED). `event-router.ts`: `resolveOutboxQueueName` + `DEFAULT_OUTBOX_ROUTING` (Prefix->Queue, longest-prefix-wins: `mail.`, `webhook.`, `notification.`, `audit.`, `workflow.`, `search.index.`, `rag.index.`, `ai.cost.`, `marketing.lead.`, `form.submission.`, `billing.`, `plugin.hook.`, `plugin.capability-use.`, `tenant.subscription.`). |
|
||||
| Scan | `apps/worker/src/scanService.ts` | ClamAV-Datei-Scan (Storage-Objekte). |
|
||||
| Metrics-Scheduler | `apps/worker/src/metrics-scheduler.ts` | periodische Metrik-Erhebung. |
|
||||
|
||||
### Konkrete Queues (README + handlers.ts)
|
||||
|
||||
`toolctrl.email`, `toolctrl.notifications`, `toolctrl.maintenance`, `toolctrl.ai-chatbot`, `toolctrl.browser-automation`, `toolctrl.file-scan`, `toolctrl.exports`, `toolctrl.imports`, `toolctrl.plugin-invoke`. (`aiChatbot`/`browserAutomation` werfen `UnsupportedWorkerJobError` — bewusst nicht verdrahtet.)
|
||||
|
||||
### Jobs / Cron-Scheduler (`apps/worker/src/jobs/`, Auswahl, alle single-instance auf `general` sofern nicht anders)
|
||||
|
||||
- AI-Cost: `ai-cost-persist*`, `ai-cost-aggregate*` (daily), `ai-cost-reconciliation*` (monthly, nur mit `STRIPE_SK`), `ai-cost-stripe-report*` (24h), `ai-cost-alert.ts`.
|
||||
- DSGVO/GDPR: `dsgvo-grace-cron.ts` (24h), `dsgvo-deletion.ts`, `dsgvo-export.ts`, `dsgvo-verify.ts`.
|
||||
- Audit: `audit-event-persist*`, `audit-retention.ts`, `plugin-audit-retention.ts` (naechtlich 03:00 UTC, `PLUGIN_AUDIT_RETENTION_CRON`).
|
||||
- Workflow-Engine: `workflow-trigger*` (Outbox-Subscriber + Executor http/native/hybrid), `workflow-execution-stalled-reconciler*` (5m).
|
||||
- Mail/Marketing: `transactional-mail-outbox*` (Gruppe `mail`), `email-sequence-*` (Gruppe `mail`, `MARKETING_SEQUENCES_ENABLED`), `marketing-outbound.ts`, `lead-stale-trigger.ts`, `trial-expiring-trigger.ts`.
|
||||
- Forms: `form-submission-route*`, `form-submission-webhook-delivery*`, `form-submission-followups.ts`.
|
||||
- Suche/RAG: `search-indexer*`, `rag-indexer*` (Qdrant via `@toolctrl/vector-store`).
|
||||
- Plugins: `plugin-invoke*` (Gruppe `plugin`, WASM-Sandbox, prod-gated `PLUGIN_RUNTIME_PRODUCTION_ENABLED`), `plugin-hook-fanout*`, `plugin-capability-use*`, `plugin-sandbox-isolated.ts`, `plugin-sandbox-worker.ts`.
|
||||
- Sonstiges: `export.ts`, `push-notification.ts`, `legacy-event-receiver*`, `outbox-done-retention-cron.ts` (24h).
|
||||
|
||||
**Prisma-Modelle:** keine eigenen — via `@toolctrl/db/*.server` (z.B. `export-jobs.server`, `import-jobs.server`, `notifications.server`, `outbox`, `outbox-retention`, `event-webhook-attempts.server`, `entities.server`, `rows.server`).
|
||||
|
||||
**HiveGrid-Relevanz:** Direktes Fundament fuer alle **asynchronen / geplanten** HiveGrid-Querschnitte: Cron/Scheduling, Queue-Consumer, Transactional-Outbox (Event-Routing), DSGVO/Compliance-Jobs, Mail-/Notification-Versand, Import/Export-Pipelines, Such-/RAG-Indexierung, AI-Cost-Tracking, Workflow-Engine-Trigger und Plugin-Invoke-Sandbox. Das Gruppen-/Concurrency-Modell und die DI-`HandlerDependencies` sind das Muster fuer jedes neue HiveGrid-Hintergrund-Modul.
|
||||
|
||||
---
|
||||
|
||||
## 3. `@toolctrl/mobile` — Capacitor-7-Native-Wrapper
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/mobile`
|
||||
**Zweck:** iOS+Android-Shell, die das React-Router-v7-Web-Build (`apps/web/build/client`) als WebView laedt. **Keine eigene UI** — exakt ein Produkt-UI (Web). Bundelt nur native Konzerne: Bundle-ID, Plugins, Session-Persistenz, Sentry, Push-Registration. App-Status: Scaffold + Push-Backend (Task #65, Phase 08); echte Builds/Store-Submission sind Operator-Tasks.
|
||||
|
||||
**Stack:** Capacitor 7 (`@capacitor/core` 7.4.3, CLI/ios/android), Plugins `app`, `browser`, `local-notifications`, `preferences`, `push-notifications`, `splash-screen`, `status-bar`; `@sentry/capacitor`; `@toolctrl/api-client-ts` (TS-SDK). Tests via `vitest`.
|
||||
|
||||
**Scripts:** `cap`, `sync`, `open:ios`, `open:android`, `build:web` (`pnpm --filter @toolctrl/web build`), `typecheck`, `test` (`vitest run src`).
|
||||
|
||||
### Zentrale Dateien
|
||||
|
||||
| Datei | Pfad | Inhalt |
|
||||
|---|---|---|
|
||||
| Capacitor-Config | `apps/mobile/capacitor.config.ts` | `appId: "de.toolctrl.app"`, `appName: "ToolCtrl"`, `webDir: "../web/build/client"`. `readLiveReloadUrl()` injiziert `server.url` aus `MOBILE_LIVE_RELOAD_URL` (nur Dev). Plugin-Config Splash/StatusBar/Push/Preferences (Suite `de.toolctrl.app.secure`). |
|
||||
| Boot | `apps/mobile/src/index.ts` | `bootstrapMobileShell(options, deps)` — idempotenter Boot: Sentry-Init, Auth-Rehydrate, opt-in Push-Registration. Side-effect-frei in Tests. |
|
||||
| Auth | `apps/mobile/src/auth.ts` | Session-Persistenz (Capacitor Preferences, **unverschluesselt**) um `@toolctrl/api-client-ts`. Typ `MobileSession`, `rehydrateAuth`. |
|
||||
| Push | `apps/mobile/src/pushRegistration.ts` | `registerPushNotifications({apiBaseUrl})` — APNs/FCM-Token gegen Backend registrieren. |
|
||||
| Sentry | `apps/mobile/src/sentry.ts` | `initMobileSentry` (Sentry-Capacitor), spiegelt `apps/web/app/sentry.client.ts`. |
|
||||
| Native | `apps/mobile/ios/`, `apps/mobile/android/` | Minimal-Skelette (Info.plist, project.pbxproj, AppDelegate, build.gradle, AndroidManifest, MainActivity). Operator regeneriert via `npx cap add ios/android`. |
|
||||
|
||||
**Prisma-Modelle:** keine.
|
||||
|
||||
**HiveGrid-Relevanz:** Fertiges Muster fuer eine **mobile App-Huelle**, falls HiveGrid native iOS/Android-Distribution braucht: WebView-Wrapper um die bestehende Web-UI, Push-Notification-Anbindung, mobile Session-Persistenz, SDK-Konsum (`api-client-ts`). Hinweis: Capacitor Preferences ist nicht verschluesselt (Token kurzlebig halten).
|
||||
|
||||
---
|
||||
|
||||
## 4. `@toolctrl/hocuspocus` — Realtime-Collab-Server (Yjs)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/hocuspocus`
|
||||
**Zweck:** Standalone-Node-Service (eigener Container) fuer Echtzeit-Kollaboration ueber Yjs/Hocuspocus. Persistiert CRDT-Dokumente in Postgres, authentifiziert via kurzlebiges JWT, ist tenant-isoliert.
|
||||
|
||||
**Stack:** `@hocuspocus/server` 4 + `@hocuspocus/extension-database` + `@hocuspocus/extension-logger`, `yjs` 13.6, `y-protocols`, `jsonwebtoken`, `@toolctrl/db`, `@toolctrl/logger`. Port: `HOCUSPOCUS_PORT` -> `PORT` -> `1234`.
|
||||
|
||||
**Scripts:** `dev` (`tsx watch src/index.ts`), `start`, `build`, `typecheck`, `test` (`vitest run src`). Eigenes `apps/hocuspocus/Dockerfile`.
|
||||
|
||||
### Zentrale Dateien
|
||||
|
||||
| Datei | Pfad | Inhalt |
|
||||
|---|---|---|
|
||||
| Entry | `apps/hocuspocus/src/index.ts` | `Server`-Bootstrap; refuses boot ohne `HOCUSPOCUS_AUTH_SECRET`. Debounce 2s / maxDebounce 10s / timeout 30s. Verdrahtet Logger + Auth + Database-Extension. |
|
||||
| Config | `apps/hocuspocus/src/config.ts` | `getHocuspocusRuntimeConfig(env)` -> `{ port, host, authSecret, maxPayloadBytes }` (default 10 MiB). Env: `HOCUSPOCUS_PORT/HOST/AUTH_SECRET/MAX_PAYLOAD_BYTES` (+ Aliase). |
|
||||
| Auth-Extension | `apps/hocuspocus/src/extensions/auth.ts` | `createAuthExtension({secret})`, `verifyCollabToken`, `parseDocumentName`, Typ `HocuspocusConnectionContext`. JWT HS256, prueft `tenantId:resourceType:resourceId`-Parity gegen DocumentName (Cross-Tenant-Schutz). Leeres Secret = jede Connection abgelehnt. |
|
||||
| Database-Extension | `apps/hocuspocus/src/extensions/database.ts` | `createDatabaseExtension({db, maxPayloadBytes})`, `fetchCollabDoc`/`storeCollabDoc`. Upsert auf `collabDoc` (Composite-Key `tenantId_resourceType_resourceId`), bumpt `version`, refresht `lastUpdatedAt`, Bytes <-> Uint8Array. |
|
||||
|
||||
**Prisma-Modell (konsumiert, nicht besessen):** `CollabDoc` in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/collabDocs.prisma` (Feld `ydocState: Bytes`, Composite-Unique `(tenantId, resourceType, resourceId)`, `version`, `lastUpdatedAt`). Zugriff via `@toolctrl/db/client.server` (`getWriteDbClient`).
|
||||
|
||||
**HiveGrid-Relevanz:** Direktes Fundament fuer **Realtime-Collaboration / kollaborative Dokumente** in HiveGrid (z.B. geteilte Notizen, Live-Editing, gemeinsame Boards). Liefert tenant-isolierte CRDT-Persistenz + JWT-Auth-Bridge out-of-the-box. Web-Seite muss ein Collab-Token-Endpoint bereitstellen (verifiziert in `auth.ts`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Root-Config & Build/Deploy
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/`
|
||||
|
||||
| Datei/Bereich | Pfad | Inhalt / Relevanz |
|
||||
|---|---|---|
|
||||
| React-Router-Config | `react-router.config.ts` | RR7: `ssr: true`, `future.unstable_optimizeDeps`. Steuert das Web-Build, das auch Mobile (`webDir`) konsumiert. |
|
||||
| Dockerfile (multistage) | `Dockerfile` | Stages: `base` (node:20-bookworm-slim, amd64), `deps`, `production-deps`, `build`, `web-build`/`api-build`/`worker-build`, `*-runtime-artifacts`, finale Targets **`web` / `api` / `worker`** (`--target`). Non-root erzwungen (`verify:docker-non-root`). |
|
||||
| Hocuspocus-Dockerfile | `apps/hocuspocus/Dockerfile` | Eigenes Image fuer den Collab-Service. |
|
||||
| Compose (dev) | `docker-compose.yml` | Worker-Topologie: 5 Gruppen-Services `worker-general/-mail/-import/-webhook/-plugin` + `redis`; Processors per Default disabled. |
|
||||
| Compose (staging) | `docker-compose.staging.yml` | Staging-Topologie. |
|
||||
| ~~Fly~~ | ~~`fly.toml`~~ | _Entfernt 2026-06-15 — Infra = Hetzner/Coolify (ADR-009/010), nicht mehr Fly.io._ |
|
||||
| Prisma-Config | `prisma.config.ts`, `prisma/schema/` | Multi-File-Prisma-Schema (Owner: `@toolctrl/db`); Apps konsumieren generierten Client. |
|
||||
| Env | `.env.example`, `.env.fly.example`, `.env.production.example`, `.env.e2e-readiness`, `.env.test`, `env.d.ts` | Env-Katalog; Drift via `verify:env-drift`. |
|
||||
| Lint/Format | `.eslintrc`, `.eslintrc.a11y-baseline.json`, `.prettierrc`, `tsconfig.json`, `vitest.config.ts`, `vitest.setup.ts` | Repo-weite Qualitaets-Config. |
|
||||
| Lighthouse | `.lighthouserc.json`, `.lighthouserc.staging.json` | Lighthouse-CI-Budgets. |
|
||||
| Hooks | `lefthook.yml` | Git-Hooks. |
|
||||
| Playwright | `playwright.config.ts` | E2E-Config (a11y/mutating readiness). |
|
||||
|
||||
**HiveGrid-Relevanz:** Das Multistage-Dockerfile (gemeinsame `base`/`build`, getrennte Runtime-Targets `web`/`api`/`worker`) ist das wiederverwendbare Deploy-Fundament; die Compose-Worker-Gruppen geben die Produktions-Skalierungstopologie vor.
|
||||
|
||||
---
|
||||
|
||||
## 6. CI-Gates (`.gitea/workflows/`)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/.gitea/`
|
||||
|
||||
| Workflow | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| CI | `.gitea/workflows/ci.yml` | Haupt-PR-Gate. Jobs: `quality` (Quality Gates), `api`, `worker`, `database`, `docker-smoke` (needs quality/api/worker/database), `resolve-sentry-environment`, `sentry-release-{api,worker,web}`. Runner `toolctrl-ci`, pnpm 10.33.0. |
|
||||
| Deploy | `.gitea/workflows/deploy.yml` | Auf `push main` + `workflow_dispatch` (`stage`/`promote`). Preflight-Gates, Docker stage/promote in Gitea-Registry, cosign-Signatur, Coolify-Staging-Deploy + Health-Wait, DB-Migrate-Command. |
|
||||
| a11y | `.gitea/workflows/a11y.yml` | Accessibility-CI. |
|
||||
| Bundle-Budget | `.gitea/workflows/bundle-budget.yml` | Bundle-Size-Budget. |
|
||||
| Coverage | `.gitea/workflows/coverage.yml` | Test-Coverage-Gate. |
|
||||
| E2E-Readiness | `.gitea/workflows/e2e-readiness.yml` | E2E-Vorbedingungen. |
|
||||
| Lighthouse | `.gitea/workflows/lighthouse.yml` | Performance/Lighthouse. |
|
||||
| Promptfoo | `.gitea/workflows/promptfoo.yml` | LLM-Eval-Gate. |
|
||||
| SDK-Codegen | `.gitea/workflows/sdk-codegen.yml` | TS-SDK aus OpenAPI generieren. |
|
||||
| Storybook | `.gitea/workflows/storybook.yml` | Storybook-Build. |
|
||||
| Sentry-Release (reusable) | `.gitea/workflows/_sentry-release.yml` + `.gitea/actions/sentry-release/action.yml` | Sentry-Release/Sourcemap-Upload. |
|
||||
| Renovate | `.gitea/renovate.json` | Dependency-Updates. |
|
||||
|
||||
### CI-`quality`-Job — Gate-Reihenfolge (ci.yml, Auswahl)
|
||||
|
||||
verify:github-ci-workflow -> verify:gitea-ci-workflow -> verify:deploy-workflow -> verify:deploy-readiness -> verify:docker-non-root -> verify:ci-baseline -> verify:source-health -> verify:eslint-baseline -> verify:env-drift -> verify:health-baseline -> verify:ai-provider-deps -> verify:promptfoo-baseline -> verify:api-inventory -> verify:tenant-isolation-report -> verify:sidebar-routes -> **verify:i18n** -> verify:tenant-auth-baseline + verify:onboarding-flow -> **verify:phase-c-boundaries** -> verify:core-build-without-plugins-smoke + verify:removed-modules -> **verify:ui-visual** -> **test:hot-swap** -> verify:a11y-coverage -> test:a11y -> Docs-Gates -> typecheck -> lint -> test:foundation -> test:packages -> **test:mobile** -> test (unit) -> build:ci -> verify:bundle-size -> Sourcemap-Check -> verify:production-seed-artifact.
|
||||
|
||||
**`api`-Job:** verify:openapi-security -> typecheck -> `vitest run apps/api/src` -> build.
|
||||
**`worker`-Job:** typecheck -> `vitest run` -> verify:workflow-outbox-native -> build -> `health` (mit `WORKER_ENABLED=false`).
|
||||
**`database`-Job:** db:generate -> verify:db-migrate-status:staging (nicht-PR) -> `@toolctrl/db test`.
|
||||
**`docker-smoke`-Job:** baut `--target web/api/worker` parallel, validiert Artefakte + Runtime-Smoke (`scripts/docker-{web,api,worker}-runtime-smoke.sh`) + `docker compose config`.
|
||||
|
||||
---
|
||||
|
||||
## 7. `verify:*`-Scripts (`scripts/verify-*`)
|
||||
|
||||
Alle `verify:*` sind npm-Scripts in `package.json`, die `scripts/verify-*.mjs` / `.ts` / `.sh` ausfuehren. Jeder Verifier hat i.d.R. eine `*.test.mjs/.ts`-Datei daneben (selbst getestet). Die vom Task explizit genannten Gates:
|
||||
|
||||
| Script (via `pnpm run`) | Datei | Was es prueft |
|
||||
|---|---|---|
|
||||
| `verify:phase-c-boundaries` | `scripts/verify-phase-c-boundaries.mjs` | Architektur-Boundaries der Phase-C-Pakete: `packages/foundation`, `view-models`, `ui-app`, `ui-subframe`, `ui-mock` duerfen **kein** `@toolctrl/db` (foundation/view-models zusaetzlich kein `react`/`react-dom`); prueft Paketnamen, verbotene deps, verbotene Imports (`~/`, `app/`), `packages/*` im Workspace. |
|
||||
| `verify:i18n` | `scripts/i18n-check.ts` + `scripts/verify-hardcoded-strings.mjs` + ESLint auf `ui-*` | i18n-Key-Vollstaendigkeit + keine hardcodierten UI-Strings in den UI-Paketen. |
|
||||
| `verify:ui-visual` | `scripts/verify-ui-mock-visual.ts` | Statischer Visual-Baseline-Check fuer das UI-Mock-Paket. |
|
||||
| `verify:ui-hot-swap` / `test:hot-swap` | `scripts/verify-ui-hot-swap.ts` (+ `.test.ts`) | UI-Mock-Hot-Swap (Austauschbarkeit der UI-Implementierung). |
|
||||
| `test` (unit) | inline (`scripts/vitest-cli-compat.mjs`) | Core-Tests (web app, scripts, api-inventory, db-boundary, create-toolctrl). |
|
||||
|
||||
**Weitere relevante `verify:*` (Auswahl, Apps&Infra-naeher Querschnitt):**
|
||||
- API/Auth: `verify:openapi-security`, `verify:api-inventory`, `verify:api-auth-routing-baseline`, `verify:api-auth-enforced-baseline`, `verify:api-auth-hardening-baseline`, `verify:auth-api-body-baseline`, `verify:route-inventory`, `verify:tenant-auth-baseline`, `verify:mfa-scope-baseline`, `verify:impersonation-scope-baseline`, `verify:permission-matrix`, `verify:role-permission-baseline`, `verify:permissions-audit-baseline`.
|
||||
- Worker/Domain-Boundaries: `verify:workflow-outbox-native`, `verify:db-boundary-baseline`, `verify:export-boundary-baseline`, `verify:import-boundary-baseline`, `verify:notification-boundary-baseline`, `verify:realtime-boundary-baseline`, `verify:storage-boundary-baseline`, `verify:billing-boundary-baseline`, `verify:transactional-mail-provider-baseline`, `verify:compliance-retention-baseline`, `verify:audit-cascade-guard`.
|
||||
- Build/Deploy/Docker/CI: `verify:docker-baseline`, `verify:docker-non-root`, `verify:docker-runtime-smoke`, `verify:docker-api-runtime-smoke`, `verify:docker-worker-runtime-smoke`, `verify:ci-baseline`, `verify:github-ci-workflow`, `verify:gitea-ci-workflow`, `verify:deploy-workflow`, `verify:deploy-readiness`, `verify:db-migrate-status[:staging]`, `verify:bundle-size`, `verify:health-baseline`, `verify:health-ci-quality-baseline`, `verify:env-drift`, `verify:secrets`, `verify:licenses`, `verify:production-seed-artifact`.
|
||||
- Qualitaet/Docs/a11y: `verify:source-health`, `verify:eslint-baseline`, `verify:test-density`, `verify:test-coverage`, `verify:a11y-baseline`, `verify:a11y-coverage`, `verify:color-contrast`, `verify:hardcoded-strings`, `verify:i18n-hardcoded-baseline`, `verify:theme-error-state-baseline`, plus diverse `verify:*-docs(-baseline)` und `verify:*-decision-report`.
|
||||
- Plugins/Features: `verify:plugin-runtime-live`, `verify:core-build-without-plugins-smoke`, `verify:removed-modules`, `verify:feature-manifest-baseline`, `verify:ai-provider-deps`, `verify:promptfoo-baseline`.
|
||||
|
||||
**HiveGrid-Relevanz der Gates:** Dieses `verify:*`-Set ist die wiederverwendbare **Guard-Rail-Bibliothek** — Architektur-Boundaries (phase-c), i18n-Disziplin, UI-Hot-Swap/Visual, Docker-Non-Root, Deploy-Readiness, API-Auth-Baselines, Tenant-Isolation. HiveGrid-Module sollten dieselben Gates erben/erweitern; jeder neue Boundary (z.B. neues Querschnittspaket) bekommt einen eigenen `verify:*-baseline`.
|
||||
|
||||
---
|
||||
|
||||
## 8. `infra/` — Self-hosted Observability & Auth
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/infra`
|
||||
|
||||
| Verzeichnis | Pfad | Inhalt |
|
||||
|---|---|---|
|
||||
| Grafana | `infra/grafana/` | `docker-compose.yml`, Provisioning (Datasource Prometheus, Dashboards). Dashboards: `overview.json`, `api-latency.json`, `queue-health.json`, `business-kpi.json`, `ai-cost-per-tenant.json`. |
|
||||
| Prometheus | `infra/prometheus/` | `prometheus.yml`, `docker-compose.yml`, `secrets/` (scrapt API+Worker `/metrics`, token-protected). |
|
||||
| Sentry | `infra/sentry/` | Self-hosted Sentry: `install.sh`, `docker-compose.override.yml`, `relay/config.yml`, `sentry/sentry.conf.py`, Backup-Setup, Traefik-Labels. |
|
||||
| Authentik | `infra/authentik/` | Self-hosted IdP: `docker-compose.yml`, Bootstrap-Blueprints (`01-groups.yaml`, `02-policies.yaml`, `03-application-toolctrl-admin.yaml`), Backup, Smoke, Traefik-Labels. |
|
||||
| PgBouncer | `infra/pgbouncer/` | `pgbouncer.ini`, `userlist.txt.template` (Connection-Pooling vor Postgres). |
|
||||
|
||||
**HiveGrid-Relevanz:** Komplettes **self-hosted Observability-/Auth-Stack-Fundament**: Prometheus-Scrape von API+Worker-Metriken, vorgefertigte Grafana-Dashboards (inkl. Queue-Health + AI-Cost-per-Tenant + Business-KPI), Sentry fuer Error-Reporting (DSN je App), Authentik als IdP, PgBouncer fuer DB-Pooling. Direkt uebernehmbar fuer HiveGrid-Betrieb.
|
||||
|
||||
---
|
||||
|
||||
## Hinweise / Grenzen dieser Inventur
|
||||
|
||||
- Keine der vier Apps besitzt ein eigenes Prisma-Schema; alle Modelle (inkl. das von Hocuspocus konsumierte `CollabDoc`) liegen unter `prisma/schema/` und gehoeren zum `@toolctrl/db`-Paket (anderer Inventur-Bereich).
|
||||
- `apps/web` und `apps/storybook` sind hier bewusst **nicht** inventarisiert (gehoeren zu Web-/UI-Bereichen), werden aber referenziert: Mobile laedt `apps/web/build/client`, Hocuspocus braucht einen Collab-Token-Endpoint der Web-App.
|
||||
- `worker/src/index.ts` (~1678 Z.) wurde teil-gelesen (Boot/Cron-Registrierung bis Z. ~1100); die hier gelistete Job-/Cron-Menge stammt aus dem Datei-Listing `apps/worker/src/jobs/` + den gelesenen Bootstrap-Bloecken und ist faktisch, aber nicht jede einzelne Job-Datei wurde voll geoeffnet.
|
||||
- `verify:*`-Beschreibungen basieren auf Script-Namen + `package.json`-Kommandos; voll gelesen wurde `verify-phase-c-boundaries.mjs`.
|
||||
@@ -0,0 +1,261 @@
|
||||
# Boilerplate-Inventur: Daten-Layer (Prisma)
|
||||
|
||||
> FAKTISCHE Inventur des Datenbank-Bereichs der Boilerplate.
|
||||
> Boilerplate-Wurzel: `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
|
||||
> Nur gelesen — nichts verändert. Diese Datei ist das einzige Schreib-Artefakt.
|
||||
|
||||
## Übersicht
|
||||
|
||||
| Aspekt | Fakt |
|
||||
| --- | --- |
|
||||
| Paket | `@toolctrl/db` (`packages/db/package.json`, `private`, `type: module`) |
|
||||
| ORM | Prisma `7.8.0` + `@prisma/client` `7.8.0` + `@prisma/adapter-pg` `7.8.0` (Decision: bei Prisma 7 bleiben — `packages/db/ORM-DECISION.md`) |
|
||||
| Datenbank | PostgreSQL |
|
||||
| Schema-Ort | `prisma/schema/*.prisma` (27 `.prisma`-Dateien inkl. `schema.prisma` + `app.prisma`-Platzhalter) |
|
||||
| Migrationen | `prisma/migrations/` (150 Migrations-Ordner; `migration_lock.toml` → provider `postgresql`) |
|
||||
| Generierter Client | `packages/db/generated/prisma/client` (Output via `generator client` in `schema.prisma`) |
|
||||
| Modelle gesamt | **190** Prisma-Modelle (Brief nannte ~184) + **6** Enums |
|
||||
| Verbindungs-URLs | NICHT im Schema (Prisma 7) — liegen in `packages/db/prisma.config.ts`: Migrate nutzt `DIRECT_URL` (Port 5432), Runtime `DATABASE_URL` (Port 6432 / PgBouncer); optional `DATABASE_READ_URL` für Read-Replica |
|
||||
|
||||
### Modelle pro Schema-Datei (faktische Zählung)
|
||||
|
||||
| Datei | Modelle | Datei | Modelle |
|
||||
| --- | ---: | --- | ---: |
|
||||
| `accounts.prisma` | 13 | `knowledgeBase.prisma` | 9 |
|
||||
| `ai.prisma` | 8 | `marketingLeads.prisma` | 4 |
|
||||
| `analytics.prisma` | 4 | `notifications.prisma` | 3 |
|
||||
| `app.prisma` | 0 (Platzhalter `// custom database models`) | `onboarding.prisma` | 7 |
|
||||
| `appsEngine.prisma` | 5 | `outbox.prisma` | 1 |
|
||||
| `collabDocs.prisma` | 1 | `permissions.prisma` | 6 |
|
||||
| `core.prisma` | 16 | `plugins.prisma` | 5 |
|
||||
| `email.prisma` | 10 | `portals.prisma` | 12 |
|
||||
| `emailSequences.prisma` | 3 | `promptFlows.prisma` | 12 |
|
||||
| `entityBuilder.prisma` | 36 | `queue.prisma` | 2 |
|
||||
| `featureFlags.prisma` | 3 | `sites.prisma` | 1 |
|
||||
| `formWidget.prisma` | 2 | `subscriptions.prisma` | 14 |
|
||||
| `helpDesk.prisma` | 2 | `workflows.prisma` | 10 |
|
||||
| `imports.prisma` | 1 | `schema.prisma` | 0 (generator + datasource) |
|
||||
|
||||
---
|
||||
|
||||
## Querschnitt-Konventionen (über alle Schemas)
|
||||
|
||||
| Konvention | Fakt | Beispiele |
|
||||
| --- | --- | --- |
|
||||
| Primärschlüssel | `id String @id @default(cuid())` durchgängig. Ausnahmen: `FileChunk.id Int @default(autoincrement())`, `PluginInvocation.id String @id` (extern gesetzt), Join-Tabellen mit `@@id([...])` (z.B. `PromptFlowGroupEntity`). | — |
|
||||
| Audit-Timestamps | `createdAt DateTime @default(now())` fast überall; `updatedAt DateTime @updatedAt` auf mutierbaren Entitäten. | nahezu alle Modelle |
|
||||
| Tenant-Scoping | `tenantId String` (pflicht) oder `tenantId String?` (nullable für system-/global-scoped). `tenant Tenant @relation(... onDelete: Cascade)`. Nullable = system-/operator-weit. | `App.tenantId` (pflicht), `Workflow.tenantId?` (nullable), `Lead` (KEIN tenantId — operator-scoped bis Conversion) |
|
||||
| Soft-Delete | NUR `Row.deletedAt DateTime?` (`entityBuilder.prisma`) mit `@@index([deletedAt])`. `ExportJob` hat `deletedAt` + `hardDeletedAt` (Retention). Sonst Hard-Delete via `onDelete: Cascade`. | `Row`, `ExportJob` |
|
||||
| FK-Delete-Strategie | `onDelete: Cascade` (Default), `onDelete: SetNull` (Audit-/Tombstone-Spalten), `onDelete: NoAction`. | `ImpersonationAudit` (SetNull), `Chat.user` (NoAction) |
|
||||
| Tamper-Evidenz | Hash-Ketten: `AuditEvent` (`previousHash`/`eventHash`), `PluginCapabilityUse` (`prevHash`/`rowHash`), `FeatureFlagAudit` (append-only). | `core.prisma`, `plugins.prisma`, `featureFlags.prisma` |
|
||||
| DSGVO/PII | IPs als SHA-256-Hash (`ipHash`, `lastIpHash`); Pseudonymisierungs-Flags auf `User` (`pseudonymized`, `scheduledDeletionAt`, `deletionRequestId`); zentrale FK-Karte `packages/db/src/dsgvo/user-fk-map.ts`. | `FormSubmission.ipHash`, `Lead.lastIpHash`, `User` |
|
||||
| Idempotenz | `dispatchKey`/`requestId`/`triggerEventId` `@unique`; `IdempotencyKey`-Modell für HTTP-Response-Caching. | `OutboxEvent.dispatchKey`, `AICostEvent.requestId` |
|
||||
| MFA/Secrets | Verschlüsselte Spalten mit `…Encrypted`-Suffix; JSON-Configs mit verschlüsselten Secrets (`configJson`). | `User.totpSecretEncrypted`, `MarketingIntegration.configJson` |
|
||||
|
||||
---
|
||||
|
||||
## Paket `@toolctrl/db`
|
||||
|
||||
**Zweck:** Eigentümer-Paket für die server-seitige Prisma-Client-Grenze, den generierten Client und die Repository-Datenbank-Befehlsfläche. Schema + Migrationen bleiben (Stand jetzt) unter `prisma/`.
|
||||
|
||||
### Zentrale Dateien (mit absolutem Pfad)
|
||||
|
||||
| Datei | Inhalt / API |
|
||||
| --- | --- |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/index.ts` | Root-Barrel: re-exportiert auth-boundary, conversations/history, audit-events, export-jobs, idempotency-keys, import-jobs, notifications, outbox(+claim/retention/receiver), permissions-seed, seed, settings, transactions, workspace-invites; `databaseBoundary` / `getDatabaseBoundary()` Metadaten-Objekt |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/client.server.ts` | `getDbClient()` (Dev-Singleton), `getWriteDbClient()` (Primary), `getReadDbClient()` (Replica via `DATABASE_READ_URL`, Fallback Primary), `getExtendedDbClient()` (`$extends` mit `.read`/`.write`), Typen `DbClient`/`ExtendedDbClient`. Nutzt `PrismaPg`-Adapter + `@toolctrl/logger` |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/transactions.server.ts` | `runDbTransaction(callback, client?)`, `runDbTransactionBatch(operations, client?)`, Typen `DbTransactionClient`/`DbTransactionRunner` |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/prisma.ts` | Konstanten der Ownership-Metadaten: `PRISMA_SCHEMA_PATH="prisma/schema"`, `PRISMA_MIGRATIONS_PATH="prisma/migrations"`, `PRISMA_GENERATED_CLIENT_PATH`, `PRISMA_SEED_COMMAND="tsx prisma/seed.ts"` |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/audit-hash.ts` | Tamper-evidente Hash-Kette für `AuditEvent`: `computeAuditHash()`, `verifyAuditChain()`, `canonicalizeAuditPayload()`; HMAC-SHA-256 via `AUDIT_CHAIN_SECRET` (Fallback SHA-256) |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/dsgvo/user-fk-map.ts` | `USER_FK_MAP` — enumeriert ALLE Modelle mit FK auf `User.id` + Cascade-Strategie (`hard-delete` / `pseudonymize` / `retain-tombstone`) + `includeInExport`. Test erzwingt Vollständigkeit gegen Schema (`user-fk-map.test.ts`) |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/dsgvo/pseudonymize.ts` | DSGVO-Pseudonymisierungs-Helfer |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/outbox.ts` | Transaktionaler Outbox-Publisher: `publishOutboxEvent(tx, args)`, `OUTBOX_EVENT_TYPE_PATTERN` (`<domain>.<entity>.<verb>`), `OUTBOX_DISPATCH_KEY_PATTERN`, `OUTBOX_MAX_PAYLOAD_BYTES=64 KiB` |
|
||||
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/prisma.config.ts` | Prisma-7-Config: Schema-/Migrations-Pfad, Seed-Befehl, `datasource.url = env("DATABASE_URL")` |
|
||||
|
||||
### Server-Module (Repository-Befehlsfläche, je `*.server.ts` mit `*.test.ts`)
|
||||
|
||||
Alle unter `packages/db/src/` (Auswahl der Domänen-Repositories):
|
||||
`accounts`, `analytics`, `api-keys`, `audit-events`, `auth-boundary`, `auth-providers`, `conversations/history`, `device-tokens`, `email-sequences`, `entities`, `entitlements-seed`, `events`, `event-webhook-attempts`, `export-jobs`, `import-jobs`, `idempotency-keys`, `impersonation-audit`, `kpi`, `logs`, `notifications`, `permissions-seed`, `queue-failed-jobs`, `relationships`, `rows`, `seed`, `settings`, `subscriptions`, `support-tickets`, `telemetry`, `transactions`, `usage`, `users`, `widgets`, `workspace-invites`.
|
||||
Subpath-Exporte sind in `package.json` deklariert (z.B. `@toolctrl/db/rows.server`, `@toolctrl/db/audit-events.server`, `@toolctrl/db/outbox`).
|
||||
|
||||
### Scripts & CI / verify
|
||||
|
||||
| Script | Zweck |
|
||||
| --- | --- |
|
||||
| `prisma:generate` | `prisma generate` (Root-Config) |
|
||||
| `prisma:migrate:check` | `scripts/db/check-direct-url.sh --skip-ping` (erzwingt DIRECT_URL) |
|
||||
| `prisma:migrate:deploy` | check + `prisma migrate deploy` |
|
||||
| `prisma:migrate:status` | Migrations-Status |
|
||||
| `seed` / `permissions:sync` | `tsx prisma/seed.ts` bzw. permissions-seed |
|
||||
| `build` | esbuild-Bundles: `permissions-seed`, `production-seed`, `e2e-readiness-seed` |
|
||||
| Root `verify:db-migrate-status` | `scripts/verify-db-migrate-status.mjs` (CI-Gate, benötigt `DATABASE_URL`) |
|
||||
| Root `verify:db-migrate-status:staging` | `scripts/verify-db-migrate-status-staging.sh` |
|
||||
|
||||
**HiveGrid-Relevanz:** Fundament für JEDES HiveGrid-Modul. Die Client-/Transaktions-/Outbox-/Audit-Helfer und das Tenant-Scoping-Muster sind direkt wiederverwendbar. `getReadDbClient()`/`getExtendedDbClient()` deckt Read-Heavy HiveGrid-Dashboards ab. `user-fk-map.ts` ist Pflicht-Referenz für jedes neue Modul mit User-Bezug (DSGVO).
|
||||
|
||||
---
|
||||
|
||||
## Schema-Domänen (Modelle + Kernfelder + HiveGrid-Relevanz)
|
||||
|
||||
### accounts.prisma (13) — `prisma/schema/accounts.prisma`
|
||||
Modelle: `User`, `MagicLinkToken`, `AdminUser`, `Tenant`, `TenantChatbotAccess`, `WorkspaceAuthProvider`, `ImpersonationAudit`, `TenantUser`, `TenantUserInvitation`, `Registration`, `Blacklist`, `TenantIpAddress`, `TenantType`.
|
||||
- `User`: email-unique, `passwordHash?`, OAuth (`githubId`/`googleId`), MFA (`totpSecretEncrypted`, `mfaRecoveryCodeHashes`), DSGVO-Flags (`pendingDeletion`, `scheduledDeletionAt`, `pseudonymized`, `deletionRequestId`), `defaultTenantId`. Index `user_pending_deletion_due_idx`.
|
||||
- `Tenant`: `slug @unique`, `name`, `active`, `subscriptionId?`, Chatbot-Felder, AI-Cost-Override-Felder, Theme. Zentraler Tenant-Scope-Anker.
|
||||
- `TenantUser` (Membership: `type`/`joined`/`status` als Int), `TenantUserInvitation` (`tokenHash`/`tokenPrefix`/`expiresAt`/`status`), `WorkspaceAuthProvider` (SSO/SAML/OIDC pro Tenant), `AdminUser` (Admin-Panel + Authentik-OIDC `ssoProvider`/`ssoSubjectId`), `ImpersonationAudit`.
|
||||
|
||||
**HiveGrid-Relevanz:** Identity / Auth / Mandanten-Kern für ALLE HiveGrid-Module (Multi-Tenant-Fundament, SSO, Invitations, Impersonation-Audit). MFA + DSGVO-Selfservice direkt nutzbar.
|
||||
|
||||
### core.prisma (16) — `prisma/schema/core.prisma`
|
||||
Modelle: `AppConfiguration`, `Log`, `AuditEvent`, `IdempotencyKey`, `ApiKey`, `ApiKeyLog`, `Event`, `EventWebhookAttempt`, `MetricLog`, `FileUploadProgress`, `FileChunk`, `FileObject`, `IpAddress`, `IpAddressLog`, `Widget`, `Credential`.
|
||||
- `AuditEvent`: tamper-evidente Hash-Kette (`previousHash`/`eventHash`), `actorType`/`actorId`/`actorEmail`, `dataSensitivity`, `regulatoryScope[]`, `outcome`. Reichlich Indizes auf `(tenantId, createdAt)` etc.
|
||||
- `ApiKey`: `keyHash`/`keyPrefix`/`keyLastFour`/`keyVersion` (gehashte Keys), `@@unique([tenantId, alias])`. `ApiKeyLog` für Request-Logging.
|
||||
- `IdempotencyKey` (`@@unique([scope, key])`), `FileObject`/`FileUploadProgress`/`FileChunk` (Storage-Metadaten), `Credential` (globaler Secret-Store, `value Json`).
|
||||
|
||||
**HiveGrid-Relevanz:** Querschnitt — Audit-Trail (Compliance), API-Keys, File-Storage, Idempotenz, Telemetrie. Für HiveGrid-Logging/Audit und externe API-Integrationen unmittelbar verwendbar.
|
||||
|
||||
### permissions.prisma (6) — `prisma/schema/permissions.prisma`
|
||||
Modelle: `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser`.
|
||||
- `Role` (tenant-scoped optional, `type`, `isDefault`, `assignToNewUsers`), `Permission` (global `name @unique`, optional `entityId`), Join `RolePermission`. `UserRole` mit nullable `tenantId` (partielle Eindeutigkeit via Migration-SQL). `Group`/`GroupUser` für Gruppen-basierte Berechtigung.
|
||||
|
||||
**HiveGrid-Relevanz:** RBAC-Fundament. Jedes HiveGrid-Modul mit Rollen/Rechten baut hierauf auf. Entity-gebundene Permissions koppeln an den Entity-Builder.
|
||||
|
||||
### app.prisma (0) — `prisma/schema/app.prisma`
|
||||
Reiner Platzhalter (`// custom database models`) für projekt-/HiveGrid-spezifische Modelle.
|
||||
**HiveGrid-Relevanz:** Vorgesehener Ort für HiveGrid-eigene Modelle ohne die Boilerplate-Domänen zu verändern.
|
||||
|
||||
### appsEngine.prisma (5) — `prisma/schema/appsEngine.prisma`
|
||||
Modelle: `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`.
|
||||
- `App` (`type`, `config` JSON-String, `@@unique([tenantId, type])`), `DataConnection` (verschlüsselte Credentials), `AppSyncRun` (Status/Mode/Metriken `itemsProcessed`…), `AppSyncItem` (Source→Destination-Mapping + Rollback).
|
||||
|
||||
**HiveGrid-Relevanz:** Integrations-/Sync-Engine — relevant für HiveGrid-Module, die externe Datenquellen (REST/OAuth/Webhook) synchronisieren, inkl. Rollback-fähiger Sync-Runs.
|
||||
|
||||
### subscriptions.prisma (14) — `prisma/schema/subscriptions.prisma`
|
||||
Modelle: `SubscriptionProduct`, `SubscriptionPrice`, `SubscriptionUsageBasedPrice`, `SubscriptionUsageBasedTier`, `SubscriptionFeature`, `TenantSubscription`, `TenantSubscriptionProduct`, `TenantSubscriptionProductPrice`, `TenantSubscriptionUsageRecord`, `TenantProductConfiguration`, `TenantFeatureOverride`, `CheckoutSessionStatus`, `Credit`.
|
||||
- Stripe-gekoppelt (`stripeId`, `stripeCustomerId`, `stripeSubscriptionId`), Usage-Based-Billing (Tiers, UsageRecords), `TenantFeatureOverride` (`@@unique([tenantId, featureKey])`), `TenantProductConfiguration.blueprintId` (Default `crm-saas`), `Credit` (Guthaben pro Tenant/User).
|
||||
|
||||
**HiveGrid-Relevanz:** Billing / Entitlements / Feature-Gating-Fundament für HiveGrid-Pläne. Gekoppelt mit `@toolctrl/entitlements` (Workspace-Dependency).
|
||||
|
||||
### notifications.prisma (3) — `prisma/schema/notifications.prisma`
|
||||
Enums: `NotificationDeliveryStatus`, `NotificationPreferenceChannel`. Modelle: `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`.
|
||||
- `NotificationDelivery` (Channel IN_APP/EMAIL, `status`, `attemptsMade`, `providerMessageId`, `@@unique([tenantId, userId, channel, sourceKey])`), `UserNotificationPreference` (pro Channel+Category), `DeviceToken` (APNs/FCM/WebPush, `token @unique`, `revokedAt`).
|
||||
|
||||
**HiveGrid-Relevanz:** Benachrichtigungs-Querschnitt (In-App + E-Mail + Push) für alle HiveGrid-Module mit User-Notifications. Mobile-Push (Capacitor) bereits modelliert.
|
||||
|
||||
### email.prisma (10) — `prisma/schema/email.prisma`
|
||||
Modelle: `TenantInboundAddress`, `Email`, `EmailRead`, `EmailCc`, `EmailAttachment`, `EmailSender`, `Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`.
|
||||
- Inbound (`Email` inbound/outbound, `messageId @unique`) + Outbound-Kampagnen (`Campaign`, `OutboundEmail` mit `sentAt`/`bouncedAt`/`unsubscribedAt`, Open/Click-Tracking).
|
||||
|
||||
**HiveGrid-Relevanz:** E-Mail-Infrastruktur (transaktional + Kampagnen) für HiveGrid-Kommunikationsmodule und CRM-Outreach.
|
||||
|
||||
### emailSequences.prisma (3) — `prisma/schema/emailSequences.prisma`
|
||||
Modelle: `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery`.
|
||||
- Drip-Kampagnen via Outbox-Events (`triggerEvent`), `stepsJson` (linear), Run-State, Step-Delivery mit Open/Click/Bounce. `@@unique([sequenceId, triggerEventId])` (Idempotenz).
|
||||
|
||||
**HiveGrid-Relevanz:** Marketing-/Lifecycle-Automation. Relevant für HiveGrid-Onboarding-/Nurture-Flows; eng an Outbox + marketingLeads gekoppelt.
|
||||
|
||||
### marketingLeads.prisma (4) — `prisma/schema/marketingLeads.prisma`
|
||||
Enum: `LeadStatus`. Modelle: `Lead`, `LeadEvent`, `TenantAcquisition`, `MarketingIntegration`.
|
||||
- `Lead` (NICHT tenant-scoped — operator-/sales-scoped, `email @unique`, First-Touch-UTM-Attribution, `score`, `convertedToTenantId`, `lastIpHash`), `LeadEvent` (Timeline-Append-Log), `TenantAcquisition` (Attributions-Snapshot bei Conversion, `tenantId @unique`), `MarketingIntegration` (verschlüsselte `configJson`, `triggerEvents[]`).
|
||||
|
||||
**HiveGrid-Relevanz:** Lead-/Funnel-/Attribution-Modul. Relevant für HiveGrid-Akquise/Marketing; zeigt das Muster „operator-scoped statt tenant-scoped".
|
||||
|
||||
### entityBuilder.prisma (36) — `prisma/schema/entityBuilder.prisma`
|
||||
Größte Domäne (No-Code-/Dynamic-Entity-Engine). Kernmodelle:
|
||||
- `Entity` (`name`/`slug`/`prefix` unique, `type` app/admin/all, Feature-Flags `hasTags`/`hasComments`/`hasTasks`/`hasViews`, `defaultVisibility`), `Property` (typisierte Spalten, `type Int`/`subtype`, `formulaId?`, `@@unique([entityId, name, tenantId])`), `EntityView` (Layout table/board/calendar…, Grid-Konfig, Filter/Sort/GroupBy), `EntityViewProperty`/`EntityViewFilter`/`EntityViewSort`, `PropertyAttribute`/`PropertyOption`, `EntityTag`, `EntityRelationship`/`RowRelationship` (Parent/Child), `EntityWebhook`/`EntityWebhookLog`.
|
||||
- **Row-Daten:** `Row` (`folio`, `deletedAt?` Soft-Delete, `order`, FK auf Entity/Tenant/User), `RowValue` (polymorphe Werte: text/number/date/boolean), `RowValueMultiple`, `RowValueRange`, `RowMedia`, `RowPermission` (row-level: role/group/user/public), `RowTag`, `RowComment`/`RowCommentReaction`, `RowTask`.
|
||||
- `Formula`/`FormulaComponent`/`FormulaLog`/`FormulaComponentLog`, `EntityGroup`/`EntityGroupEntity`/`EntityGroupConfiguration(Row)`, `EntityTemplate`, `ApiKeyEntity` (per-Entity-CRUD-Rechte), `TenantSettingsRow`, `SampleCustomEntity`.
|
||||
|
||||
**HiveGrid-Relevanz:** Kern-Datenmodell-Engine. Wenn HiveGrid dynamische/benutzerdefinierte Entitäten, Tabellen-Views, Row-Level-Permissions, Tags/Tasks/Comments oder Formeln braucht, ist dies das Fundament. Größter Wiederverwendungs-Hebel und größte Komplexität.
|
||||
|
||||
### portals.prisma (12) — `prisma/schema/portals.prisma`
|
||||
Modelle: `Portal`, `PortalUser`, `PortalPage`, `PortalUserRegistration`, `PortalSubscriptionProduct`, `PortalSubscriptionPrice`, `PortalSubscriptionFeature`, `PortalUserSubscription`, `PortalUserSubscriptionProduct`, `PortalUserSubscriptionProductPrice`, `PortalCheckoutSessionStatus`.
|
||||
- `Portal` (`subdomain @unique`, optional `domain`, SEO/Branding/Auth-Flags, eigene Stripe-Account), `PortalUser` (separate End-User-Identität pro Portal, `@@unique([portalId, email])`), eigenes Subscription-Subsystem (gespiegelt vom Haupt-Subscriptions-Modell).
|
||||
|
||||
**HiveGrid-Relevanz:** Customer-Portal / White-Label-Public-Sites mit eigener User-Basis und eigenem Billing. Relevant falls HiveGrid kundenseitige Portale (B2B2C) anbietet.
|
||||
|
||||
### promptFlows.prisma (12) — `prisma/schema/promptFlows.prisma`
|
||||
Modelle: `PromptFlowGroup`, `PromptFlowGroupTemplate`, `PromptFlowGroupEntity`, `PromptFlow`, `PromptFlowInputVariable`, `PromptTemplate`, `PromptFlowOutput`, `PromptFlowOutputMapping`, `PromptFlowExecution`, `PromptTemplateResult`.
|
||||
- LLM-Prompt-Pipelines, an `Entity`/`Property` gekoppelt (Output-Mapping in Row-Properties), `executionType` sequential/parallel, Streaming-Flag, Execution + Result-Log.
|
||||
|
||||
**HiveGrid-Relevanz:** AI-Prompt-Orchestrierung an Entity-Daten. Relevant für HiveGrid-Module, die strukturierte LLM-Outputs in Datensätze schreiben.
|
||||
|
||||
### ai.prisma (8) — `prisma/schema/ai.prisma`
|
||||
Modelle: `Chat`, `ChatMessage`, `ChatMessagePart`, `GeneratedObject`, `AICostEvent`, `TenantAICostSummary`.
|
||||
- `Chat` (Typ tenant/admin/marketing, Scope, anonym via `sessionId`), `ChatMessage`/`ChatMessagePart` (Multi-Part), `GeneratedObject` (LLM-Generierungen + Token/Cost-Felder), `AICostEvent` (append-only Cost-Log, `requestId @unique`, KEINE Prompt-Bodies, Stripe-Overage-Felder), `TenantAICostSummary` (vor-aggregiert pro Periode).
|
||||
|
||||
**HiveGrid-Relevanz:** AI-Chatbot + AI-Kostentracking/Billing. Für HiveGrid-Assistenten und AI-Cost-Dashboards direkt nutzbar.
|
||||
|
||||
### workflows.prisma (10) — `prisma/schema/workflows.prisma`
|
||||
Modelle: `Workflow`, `WorkflowBlock`, `WorkflowBlockConditionGroup`, `WorkflowBlockCondition`, `WorkflowBlockToBlock`, `WorkflowExecution`, `WorkflowInputExample`, `WorkflowBlockExecution`, `WorkflowVariable`, `WorkflowCredential`.
|
||||
- Visueller Workflow-Builder: Blocks + Conditions + Block-zu-Block-Edges, Execution-Tracking pro Block, tenant-scoped + `appliesToAllTenants`. `WorkflowVariable`/`WorkflowCredential` (`@@unique([tenantId, name])`).
|
||||
|
||||
**HiveGrid-Relevanz:** Automatisierungs-/Workflow-Engine (node-basiert). Relevant für HiveGrid-Prozessautomatisierung, gekoppelt an Outbox-Events.
|
||||
|
||||
### knowledgeBase.prisma (9) — `prisma/schema/knowledgeBase.prisma`
|
||||
Modelle: `KnowledgeBase`, `KnowledgeBaseCategory`, `KnowledgeBaseCategorySection`, `KnowledgeBaseArticle`, `KnowledgeBaseRelatedArticle`, `KnowledgeBaseViews`, `KnowledgeBaseArticleViews`, `KnowledgeBaseArticleUpvotes`, `KnowledgeBaseArticleDownvotes`.
|
||||
- Mehrsprachige Wissensdatenbank, tenant-scoped optional (`ownerKey` default "global"), Artikel mit Draft/Published-Content, Voting + View-Tracking.
|
||||
|
||||
**HiveGrid-Relevanz:** Help-Center / Docs-Modul. Relevant für HiveGrid-Self-Service-Wissensbasis.
|
||||
|
||||
### onboarding.prisma (7) — `prisma/schema/onboarding.prisma`
|
||||
Modelle: `Onboarding`, `OnboardingFilter`, `OnboardingStep`, `OnboardingSession`, `OnboardingSessionAction`, `OnboardingSessionFilterMatch`, `OnboardingSessionStep`.
|
||||
- Onboarding-Flows (modal/page), Filter-Targeting, Session-Tracking pro User/Tenant (`@@unique([onboardingId, userId, tenantId])`).
|
||||
|
||||
**HiveGrid-Relevanz:** User-Onboarding / Produkt-Touren für HiveGrid-Adoption.
|
||||
|
||||
### analytics.prisma (4) — `prisma/schema/analytics.prisma`
|
||||
Modelle: `AnalyticsSettings`, `AnalyticsUniqueVisitor`, `AnalyticsPageView`, `AnalyticsEvent`.
|
||||
- First-Party-Web-Analytics (Cookie-basiert, UTM, Device/Browser), an `Portal`/`User`/`PortalUser`/`FeatureFlag` gekoppelt.
|
||||
|
||||
**HiveGrid-Relevanz:** Eingebettetes Web-Analytics für HiveGrid-Portale/Sites; FeatureFlag-Event-Korrelation.
|
||||
|
||||
### featureFlags.prisma (3) — `prisma/schema/featureFlags.prisma`
|
||||
Modelle: `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit`.
|
||||
- `FeatureFlag` (scope global/tenant/user, v2-Targeting `rules`/`variants` JSON, `enabledFrom/Until`, Flag-Dependencies via self-relation), `FeatureFlagFilter` (Prozent/Sprache/Page…), `FeatureFlagAudit` (append-only).
|
||||
|
||||
**HiveGrid-Relevanz:** Feature-Toggles / Gradual-Rollout / A-B für alle HiveGrid-Module.
|
||||
|
||||
### plugins.prisma (5) — `prisma/schema/plugins.prisma`
|
||||
Modelle: `Plugin`, `TenantPluginCapabilityGrant`, `PluginUserConfig`, `PluginInvocation`, `PluginCapabilityUse`.
|
||||
- WASM-Plugin-Runtime: `Plugin` (`wasmSha256`, `signaturePublicKey` Ed25519, `manifest` JSON, `@@unique([tenantId, pluginId])`), explizite Capability-Grants pro Tenant, per-User-Config, Invocation-Audit + per-Capability-Use mit Hash-Kette (`prevHash`/`rowHash`).
|
||||
|
||||
**HiveGrid-Relevanz:** Erweiterbarkeit via signierte sandboxed Plugins. Relevant falls HiveGrid Third-Party-/Custom-Erweiterungen unterstützt.
|
||||
|
||||
### imports.prisma (1) — `prisma/schema/imports.prisma`
|
||||
Enum: `ImportJobStatus`. Modell: `ImportJob` (tenant-scoped, `importType`/`format`, Source-Bucket/Key, `acceptedRows`/`rejectedRows`, Error-Report-Bucket, `requestId`).
|
||||
**HiveGrid-Relevanz:** Daten-Import-Jobs (CSV/etc.) für HiveGrid-Bulk-Onboarding.
|
||||
|
||||
### queue.prisma (2) — `prisma/schema/queue.prisma`
|
||||
Enum: `ExportJobStatus`. Modelle: `QueueFailedJob` (BullMQ-DLQ, `@@unique([queueName, jobName, jobId])`), `ExportJob` (Daten-Export mit Retention `expiresAt`/`deletedAt`/`hardDeletedAt`).
|
||||
**HiveGrid-Relevanz:** Background-Job-Fehler-Observability + DSGVO-konformer Datenexport.
|
||||
|
||||
### outbox.prisma (1) — `prisma/schema/outbox.prisma`
|
||||
Enum: `OutboxStatus`. Modell: `OutboxEvent` (`eventType`, `payload` JSON, `status`, `retries`, `scheduledAt`, `dispatchKey @unique` für Idempotenz, `priority`, `lockedUntil`). Reiche Indizes für Dispatcher-Polling.
|
||||
**HiveGrid-Relevanz:** Transaktionales Outbox-Muster — atomare Side-Effects mit DB-Writes. Querschnitt für ALLE HiveGrid-Module mit zuverlässiger Event-Auslieferung (Publisher: `packages/db/src/outbox.ts`).
|
||||
|
||||
### sites.prisma (1) — `prisma/schema/sites.prisma`
|
||||
Modell: `Site` (tenant-scoped, `type` community/booking, `siteId @@unique([type, siteId])`, Branding/Copy JSON, Server-Resolution domain/path/subdomain).
|
||||
**HiveGrid-Relevanz:** Multi-Site / Public-Sites (z.B. Booking/Community). Relevant für HiveGrid-Endkunden-Frontends.
|
||||
|
||||
### collabDocs.prisma (1) — `prisma/schema/collabDocs.prisma`
|
||||
Modell: `CollabDoc` (Y.js/Hocuspocus Realtime-Docs, `ydocState Bytes`, `version`, `@@unique([tenantId, resourceType, resourceId])`).
|
||||
**HiveGrid-Relevanz:** Realtime-Kollaboration (Live-Editing) für HiveGrid-Dokumente/Notizen.
|
||||
|
||||
### helpDesk.prisma (2) — `prisma/schema/helpDesk.prisma`
|
||||
Modelle: `Feedback` (tenant/user-scoped, `message`, `fromUrl`), `SupportTicket` (`source`/`status`/`priority`, `inboundMessageId @unique`).
|
||||
**HiveGrid-Relevanz:** Support-/Feedback-Modul für HiveGrid-Kundenservice.
|
||||
|
||||
### formWidget.prisma (2) — `prisma/schema/formWidget.prisma`
|
||||
Modelle: `Form` (tenant-scoped, embeddable, `key @unique`, `definition` JSON, `fieldMapping`, `allowedOrigins[]`, Anti-Spam-`config`), `FormSubmission` (`payload` JSON, `ipHash`, `status` received/processed/failed/spam).
|
||||
**HiveGrid-Relevanz:** Eingebettete Formulare (Lead-Capture, Kontakt) für HiveGrid-Public-Surfaces; koppelt an CRM/Entity-Rows.
|
||||
|
||||
---
|
||||
|
||||
## Hinweise für Modul-Abgleich-Agenten
|
||||
|
||||
- **Tenant-Scope-Regel:** `tenantId` nullable ⇒ system-/operator-weit; `tenantId` pflicht ⇒ strikt mandanten-isoliert. `Lead` ist bewusst NICHT tenant-scoped.
|
||||
- **Soft-Delete ist die Ausnahme:** nur `Row.deletedAt` + `ExportJob`. Default ist Hard-Delete via `onDelete: Cascade`.
|
||||
- **Vor jedem neuen User-FK:** Eintrag in `packages/db/src/dsgvo/user-fk-map.ts` ergänzen — der Test bricht CI sonst.
|
||||
- **Side-Effects:** über Outbox (`publishOutboxEvent` in `$transaction`), nicht direkt.
|
||||
- **Verbindungen:** Migrate = `DIRECT_URL`, Runtime = `DATABASE_URL` (PgBouncer), Reads optional `DATABASE_READ_URL`.
|
||||
- **HiveGrid-eigene Modelle:** `prisma/schema/app.prisma` ist der vorgesehene leere Platzhalter.
|
||||
@@ -0,0 +1,366 @@
|
||||
# Boilerplate-Inventur: Domaenen-Pakete (Spezial)
|
||||
|
||||
> Faktische Bestandsaufnahme der fertigen Domaenen-Bausteine in der Boilerplate
|
||||
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`), die HiveGrid-Module direkt
|
||||
> nutzen koennten. Quelle: gelesene Pakete, `index.ts`, READMEs, Prisma-Schemas,
|
||||
> Service-Layer in `apps/web/app/modules/*` und Worker-Jobs.
|
||||
>
|
||||
> Konvention im gesamten Repo: Pakete heissen `@toolctrl/<name>`, sind `private: true`,
|
||||
> `type: module`, ESM-only, `exports` zeigen direkt auf `./src/*.ts` (kein Build-Output);
|
||||
> Build = `pnpm run typecheck`. Tests via `vitest run src`. Prisma-Schema ist
|
||||
> per-Domain aufgesplittet unter `prisma/schema/*.prisma`. DB-spezifische
|
||||
> Service-Logik liegt in `*.db.server.ts` / `*.server.ts` Dateien im Web-App-Modul.
|
||||
|
||||
---
|
||||
|
||||
## Reifegrad-Legende
|
||||
|
||||
- **Reif (fertig)** — Prisma-Modell + Service-Layer + Worker/Route + Tests vorhanden.
|
||||
- **Solide (Helper/Schema-Layer)** — eigenstaendiges Paket mit Tests, aber bewusst dependency-frei (kein DB-/UI-Layer im Paket selbst).
|
||||
- **Daten-Modell + Service** — Prisma-Modell + DB-/Service-Layer im Web-App-Modul (kein eigenes npm-Paket).
|
||||
|
||||
---
|
||||
|
||||
## Uebersichts-Tabelle
|
||||
|
||||
| Baustein | Code-Ort | Reifegrad | HiveGrid-Modul (Kandidat) |
|
||||
| --- | --- | --- | --- |
|
||||
| Subscriptions/Billing (Stripe) | `prisma/schema/subscriptions.prisma` + `apps/web/app/utils/stripe.server.ts` + `packages/entitlements` | Reif | Billing / Plaene / Entitlements-Querschnitt |
|
||||
| Onboarding-Wizard | `prisma/schema/onboarding.prisma` + `apps/web/app/modules/onboarding` | Reif | Onboarding / User-Aktivierung |
|
||||
| Help-Desk / Support | `prisma/schema/helpDesk.prisma` + `apps/web/app/modules/helpDesk` | Reif | Support / Feedback |
|
||||
| Customer-Portals | `prisma/schema/portals.prisma` + `apps/web/app/modules/portals` | Reif | Kunden-/Partner-Portale, White-Label-Subdomains |
|
||||
| Form-Widget / Form-Builder | `packages/form-widget` + `prisma/schema/formWidget.prisma` + `apps/web/app/modules/formWidget` | Reif | Lead-Capture / Formulare / Embeds |
|
||||
| Import (DSGVO/CSV/JSON/XLSX) | `packages/imports` + `prisma/schema/imports.prisma` | Solide + Job | Daten-Import / Migration |
|
||||
| Export (CSV/JSON/XLSX/PDF, DSGVO) | `packages/exports` + Worker `export.ts`/`dsgvo-export.ts` | Solide + Job | Daten-Export / DSGVO-Auskunft / Audit-PDF |
|
||||
| Branding / Theme | `packages/brand` | Solide | Theming-Querschnitt / Mail-Branding |
|
||||
| Entity-Builder (Custom-Felder) | `prisma/schema/entityBuilder.prisma` + `apps/web/app/components/entities` | Reif | No-Code-Entitaeten / Custom-Felder |
|
||||
| Knowledge-Base (Help-Center) | `prisma/schema/knowledgeBase.prisma` + `apps/web/app/modules/knowledgeBase` | Reif | Help-Center / Wissensdatenbank |
|
||||
| Analytics (Visitor/Event) | `prisma/schema/analytics.prisma` + `apps/web/app/modules/portals/utils/analytics-redaction.ts` | Daten-Modell + Service | Web-Analytics (Portal-fokussiert) |
|
||||
| Marketing-Leads / Funnel | `prisma/schema/marketingLeads.prisma` + `packages/marketing-outbound` + `apps/web/app/utils/leads` | Reif | Marketing / Lead-Funnel / Attribution |
|
||||
| Shared-Store (Redis-KV) | `packages/shared-store` | Solide | Querschnitt: Rate-Limit, Cache, Sessions, Idempotenz |
|
||||
| API-Client / API-Types (SDK) | `packages/api-client-ts`, `packages/api-types` | Solide | Externe Integration / SDK / Webhook-Verify |
|
||||
|
||||
---
|
||||
|
||||
## 1. `@toolctrl/form-widget` + Form-Builder
|
||||
|
||||
**Zweck:** Geteilte Typen & Helper fuer das einbettbare iframe-Formular-Widget. Bewusst
|
||||
**ohne Runtime-Abhaengigkeiten** auf den Rest des Codebases (nur `zod`), damit Web/API/Worker/CLI
|
||||
es importieren koennen, ohne Prisma/React mitzuziehen.
|
||||
|
||||
**Haupt-Exporte** (`packages/form-widget/src/index.ts`):
|
||||
|
||||
| Export | Datei | Funktion |
|
||||
| --- | --- | --- |
|
||||
| `FormDefinitionSchema`, `FormFieldSchema`, `FormThemeSchema`, `FormSubmissionPayloadSchema`, `FieldTypeSchema` | `src/schema.ts` | Zod-Definitionen fuer Form/Feld/Theme/Submission-JSON. Feldtypen: text, email, number, textarea, select, radio, checkbox, honeypot |
|
||||
| `HONEYPOT_FIELD_KEY` (= `"hp_extra_data"`) | `src/schema.ts` | Stabiler Honeypot-Feldschluessel |
|
||||
| `matchAllowedOrigin`, `normalizeOrigin` | `src/origin.ts` | Origin-Allowlist mit Wildcard-Subdomain (`*.example.com`); leere Allowlist = nicht submittbar |
|
||||
| `isHoneypotTriggered` | `src/honeypot.ts` | Anti-Spam Honeypot-Erkennung (still 204 zurueck) |
|
||||
| `resolveSubmissionTarget`, `applyFieldMapping` | `src/routing.ts` | Submission-Routing: `generic` \| `crm-contact` \| `entity-row` + Field-Mapping (worker-hot-path, sync) |
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/formWidget.prisma`):
|
||||
- `Form` — tenant-authored Definition + Theme + Delivery-Config (versioniertes `definition` JSON, `theme`, `targetType`, `targetEntityId`, `fieldMapping`, `allowedOrigins[]`, `notifyEmails[]`, `webhookUrl`, `config`, `key` fuer `<script data-form-key>`).
|
||||
- `FormSubmission` — Inbox fuer Payloads (`payload` JSON, `sourceOrigin`, `ipHash` = SHA-256, kein Raw-IP, `status`: received/processed/failed/spam, `result` JSON).
|
||||
|
||||
**Form-Builder UI** (`apps/web/app/modules/formWidget/builder/`): `FormBuilder.tsx`, `Canvas.tsx`,
|
||||
`FieldPalette.tsx`, `FieldProperties.tsx`, `SettingsTab.tsx`, `PreviewTab.tsx`, `SortableField.tsx`, `palette.ts`, `types.ts`.
|
||||
|
||||
**Worker-Jobs** (`apps/worker/src/jobs/`): `form-submission-route.ts`, `form-submission-webhook-delivery.ts`,
|
||||
`form-submission-followups.ts` (+ Bootstraps).
|
||||
|
||||
**HiveGrid-Relevanz:** Direkt nutzbar fuer Lead-Capture-Formulare, eingebettete Kontakt-/Anfrage-Formulare,
|
||||
Formular-zu-Entity-Routing. Das schema-Paket ist als zod-Contract sofort wiederverwendbar; CRM-Contact-Routing
|
||||
und Entity-Row-Routing passen zum Entity-Builder.
|
||||
|
||||
---
|
||||
|
||||
## 2. `@toolctrl/imports` (Daten-Import)
|
||||
|
||||
**Zweck:** Dependency-freies (kein DB/Netz) Parser-/Dry-Run-Framework fuer CSV/JSON/XLSX-Importe inkl.
|
||||
Column-Mapping, Validierung, Diagnose-Redaction (Secrets/PII) und Dedupe.
|
||||
|
||||
**Haupt-Exporte** (`packages/imports/src/index.ts`):
|
||||
- `IMPORT_FORMATS` = `["csv","json","xlsx"]`, `ImportFormat`.
|
||||
- Format-Erkennung: `detectImportFormatFromExtension`, `detectImportFormatFromContentType`, `isSupportedImportFormat`.
|
||||
- Dry-Run-Preview: `createImportDryRunPreview` (mappt Quellspalten -> Zielfelder, prueft Pflichtfelder).
|
||||
- Diagnose-Redaction: `createRedactedParserDiagnostic`, `redactDiagnosticMessage` (entfernt api-key/token/password/secret/body via Regex).
|
||||
- `summarizeRowResults`.
|
||||
- Zentrale Typen: `ColumnMapping`, `NormalizedImportRow`, `ImportRowResult`, `ParserDiagnostic`, `ImportParser`, `ImportParserInput/Output`, `ImportDryRunSummary`.
|
||||
- Dedupe (`src/dedupe.ts`): `DuplicateKeyField`, `DuplicateDetectionRow`, etc.
|
||||
|
||||
**Prisma-Modell** (`prisma/schema/imports.prisma`):
|
||||
- `ImportJob` — Job-Tracking (`status` enum `ImportJobStatus`: PENDING/RUNNING/COMPLETED/FAILED, `importType`, `format`, `sourceBucket`/`sourceKey`, `rowCount`, `acceptedRows`, `rejectedRows`, `errorReportBucket`/`errorReportKey`, `requestId`, tenant-scoped).
|
||||
|
||||
**HiveGrid-Relevanz:** Direkt nutzbar fuer Daten-Migration / Bulk-Import in Custom-Entities. Die
|
||||
PII-/Secret-Redaction in Diagnose-Meldungen ist DSGVO-relevant. Dry-Run-Preview passt zu einem Import-Wizard.
|
||||
|
||||
---
|
||||
|
||||
## 3. `@toolctrl/exports` (Daten-Export inkl. DSGVO & Audit-PDF)
|
||||
|
||||
**Zweck:** Streaming-Export-Framework fuer CSV/JSON/XLSX/PDF mit Plan-/Format-Row-Caps,
|
||||
S3-Multipart-Sink, Spreadsheet-Injection-Safety und einem dedizierten Compliance-Audit-PDF-Renderer.
|
||||
|
||||
**Haupt-Exporte** (`packages/exports/src/index.ts` re-exportiert):
|
||||
|
||||
| Subpfad | Datei | Inhalt |
|
||||
| --- | --- | --- |
|
||||
| `./csv`, `./json`, `./xlsx`, `./pdf` | `src/{csv,json,xlsx,pdf}/index.ts` | Format-Serializer (jeweils mit `stream.ts`) |
|
||||
| `./types` | `src/types.ts` | `ExportTable`, `normalizeExportTable`, `ExportColumn`, `ExportRecord`, `ExportTableValidationError` |
|
||||
| `./limits` | `src/limits.ts` | `EXPORT_PLAN_ROW_CAPS` (free 10k / pro 100k / enterprise unlimited), `TenantPlanTier`, `ExportFormat`, `ExportRowCapExceededError` |
|
||||
| `./s3-multipart` | `src/sinks/s3-multipart.ts` | `createS3MultipartUploadSink` (8 MB Parts, Concurrency 4, AbortMultipartUpload on failure) |
|
||||
| `./audit-pdf` | `src/audit-pdf.ts` | `serializeAuditEventsToPdf` / `serializeAuditEventsToPdfStream`, `AuditPdfEvent`, SOC2/HIPAA/GDPR-Evidence-PDF |
|
||||
|
||||
Format-Caps (`src/format-caps.ts`): `PDF_STREAM_HARD_ROW_LIMIT = 5.000`, `XLSX_STREAM_HARD_ROW_LIMIT = 500.000`, `XLSX_STREAM_THRESHOLD = 50.000`.
|
||||
Zusaetzlich `src/spreadsheet-safety.ts` (CSV/XLSX-Injection-Schutz).
|
||||
|
||||
**Dependencies:** `@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, `@react-pdf/renderer`, `exceljs`.
|
||||
|
||||
**Worker-Jobs** (`apps/worker/src/jobs/`):
|
||||
- `export.ts` — generischer Export-Job.
|
||||
- `dsgvo-export.ts` — DSGVO Personal-Data-Export (Phase 10 #68): aggregiert alle Rows mit `userId` via `USER_FK_MAP` (`packages/db/src/dsgvo/user-fk-map.ts`), serialisiert als JSON-Bundle, streamt zu S3, mintet Signed-URL, schreibt `AuditEvent` action=EXPORT_PERSONAL_DATA (regulatoryScope gdpr, dataSensitivity pii).
|
||||
**Prisma:** Export-Jobs-Migration `prisma/migrations/20260508000000_export_jobs/`.
|
||||
|
||||
**HiveGrid-Relevanz:** Direkt nutzbar fuer DSGVO-Auskunft (Recht auf Datenkopie), Daten-Export aus
|
||||
Custom-Entities, Audit-/Compliance-Reports als PDF. Plan-basierte Row-Caps koppeln an Entitlements/Billing.
|
||||
|
||||
---
|
||||
|
||||
## 4. `@toolctrl/brand` (Branding / Theme-Tokens)
|
||||
|
||||
**Zweck:** Dependency-freie (zod-frei, nur Node-Types) Brand-Token-Aufloesung: Produktname, Site-URL,
|
||||
Legal-Links (Impressum/Datenschutz/AGB), Support-Kontakt, Logo/Favicon, Social-Links, transaktionale Mail-Farben.
|
||||
|
||||
**Haupt-Exporte** (`packages/brand/src/index.ts`):
|
||||
- Typen: `BrandTokens`/`ToolCTRLBrandTokens`, `BrandTokenOverrides`, `BrandLinkConfiguration`, `BrandLegalLinks`, `BrandSupportContact`, `BrandAssets`, `BrandSocialLinks`, `TransactionalMailColors`, `AppConfigurationLike`.
|
||||
- Defaults: `defaultBrandTokens`, `defaultBrandLinks` (Default Produktname "ToolCTRL", `tool-ctrl.de`).
|
||||
- `createBrandTokens(overrides)` — Merge mit Defaults.
|
||||
- `resolveTransactionalBrandTokens(appConfigLike)` — leitet Tokens aus einer App-Konfiguration ab (mehrstufiger Fallback brand.* -> top-level Felder).
|
||||
- `brandCssVariables(tokens)` — CSS-Custom-Properties (`--toolctrl-*`).
|
||||
- `loadBrandFromEnv(env)` + `BrandEnvSource` (`src/env.ts`) — laedt Overrides aus `BRAND_*` Env-Variablen (PRODUCT_NAME, SITE_URL, SUPPORT_EMAIL, LEGAL_*, LOGO_URL, MAIL_*).
|
||||
|
||||
**HiveGrid-Relevanz:** Theming-Querschnitt. Token-Modell (Legal/Support/Assets/Mail-Farben) ist
|
||||
white-label-/multi-tenant-tauglich und direkt fuer Mail-Branding + CSS-Variablen einsetzbar. Hinweis:
|
||||
Defaults sind ToolCTRL-spezifisch und muessten fuer HiveGrid umgesetzt/overriden werden.
|
||||
|
||||
---
|
||||
|
||||
## 5. `@toolctrl/shared-store` (Redis-KV-Querschnitt)
|
||||
|
||||
**Zweck:** Cross-Replica-State-Primitive auf Redis (prod) bzw. In-Memory (dev/test). Fundament fuer
|
||||
horizontale Skalierung stateful Subsysteme. Dependency: `ioredis`. Optional: `@toolctrl/logger`.
|
||||
|
||||
**Haupt-Exporte** (`packages/shared-store/src/index.ts`):
|
||||
- Adapter: `SharedStoreAdapter` (Interface, `src/adapters/adapter.ts`), `MemoryAdapter`, `RedisAdapter`.
|
||||
- Factory: `createSharedStore` (`src/factory.ts`) — namespace, ttlDefault, redisUrl, redisDbIndex.
|
||||
- Helper (`src/helpers/`): `createFixedWindowRateLimiter`, `createSlidingWindowRateLimiter`, `createCacheStore` (mit Cross-Instance-Invalidation), `createSessionStore`, `createIdempotencyStore`, `createTwoTierCache`.
|
||||
|
||||
**Konventionen** (README): Keys = `shared-store:<namespace>:<prefix>:<suffix>`; Redis-DB-Index-Allokation
|
||||
(0 = BullMQ/`@toolctrl/queue`, 1 = shared-store KV, 2 = Pub/Sub). Lua-Skripte sind Konstanten (kein User-Input).
|
||||
|
||||
**HiveGrid-Relevanz:** Querschnitts-Infrastruktur fuer Rate-Limiting (Login/MFA/API),
|
||||
Subscription-/Feature-Flag-Cache, Web-Sessions, Webhook-/Payment-Idempotenz. Kein Domaenen-Baustein im
|
||||
engeren Sinn, aber Voraussetzung fuer skalierbares Multi-Replica-Deployment der Domaenen-Module.
|
||||
|
||||
---
|
||||
|
||||
## 6. `@toolctrl/api-client-ts` + `@toolctrl/api-types` (SDK)
|
||||
|
||||
**Zweck:** Offizielles TypeScript-SDK fuer die Boilerplate-REST-API, generiert aus dem OpenAPI-Spec
|
||||
(`@hey-api/openapi-ts`), mit Wrapper fuer Auth, Retry (exp. Backoff, Retry-After), Idempotency-Keys,
|
||||
Pagination-Iterator und HMAC-Webhook-Signatur-Verify.
|
||||
|
||||
**`@toolctrl/api-client-ts` Haupt-Exporte** (`src/index.ts`):
|
||||
- `createToolctrlClient`, `ToolctrlApiError`, `ToolctrlNetworkError`, Typen `ToolctrlClient/ClientConfig/AuthConfig/RetryConfig/IdempotencyConfig`, `PaginatedResponse`, `PaginateOptions` (`src/client.ts`).
|
||||
- `verifyWebhookSignature`, `signWebhookPayload`, `VerifyWebhookOptions`, `SignWebhookOptions` (`src/webhooks.ts`).
|
||||
- Subpfade: `./client`, `./webhooks`, `./types` (generierte `types.gen.ts`), `./generated`.
|
||||
- OpenAPI-Spec: `packages/api-client-ts/openapi.json`; Spec-Generator-Scripts `scripts/generate-spec.ts`.
|
||||
|
||||
**`@toolctrl/api-types` Haupt-Exporte** (`src/index.ts`):
|
||||
- Zero-Runtime Re-Export: Wrapper-Typen aus `@toolctrl/api-client-ts` + `export type * from "@toolctrl/api-client-ts/types"` (alle OpenAPI-Operation-Typen). Dependency-frei.
|
||||
|
||||
**HiveGrid-Relevanz:** Direkt nutzbar, falls HiveGrid eine REST-API exponiert und ein typisiertes
|
||||
SDK/Webhook-Verify braucht. Webhook-HMAC-Verify ist auch fuer Inbound-Webhooks (z.B. Stripe-Style) relevant.
|
||||
Hinweis: `types.gen.ts` ist aus dem Boilerplate-Spec generiert — fuer HiveGrid neu zu generieren.
|
||||
|
||||
---
|
||||
|
||||
## 7. Subscriptions / Billing (Stripe) — Schema + Service
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/subscriptions.prisma`):
|
||||
|
||||
| Modell | Zweck |
|
||||
| --- | --- |
|
||||
| `SubscriptionProduct` | Stripe-Produkt-Spiegel (order, title, model, public, badge, billingAddressCollection, hasQuantity, canBuyAgain) |
|
||||
| `SubscriptionPrice` | Preis pro Produkt (stripeId, type, billingPeriod, price Decimal, currency, trialDays) |
|
||||
| `SubscriptionUsageBasedPrice` + `SubscriptionUsageBasedTier` | Metered/Usage-Based Billing (unit, usageType, aggregateUsage, tiersMode, billingScheme, Tier from/to/perUnit/flatFee) |
|
||||
| `SubscriptionFeature` | Feature-Liste pro Produkt (name, type, value, accumulate) |
|
||||
| `TenantSubscription` -> `TenantSubscriptionProduct` -> `TenantSubscriptionProductPrice` -> `TenantSubscriptionUsageRecord` | Tenant-Abo-Status, Stripe-Customer/Subscription-IDs, Period-Start/End, Quantity, Usage-Records |
|
||||
| `TenantProductConfiguration` | `blueprintId` (default `crm-saas`) pro Tenant |
|
||||
| `TenantFeatureOverride` | Per-Tenant Feature-Override (featureKey/override/reason) |
|
||||
| `CheckoutSessionStatus` | Stripe-Checkout-Session-Tracking (pending, email, fromUrl/User/Tenant) |
|
||||
| `Credit` | Guthaben/Credits pro Tenant/User (amount, type, objectId) |
|
||||
|
||||
**Service-Layer** (`apps/web/app/`):
|
||||
- `utils/stripe.server.ts` — Stripe-Client (API-Version `2025-10-29.clover`), `getStripeClient`, `isStripeConfigured`, `isStripeTestMode`, Webhook-Signing-Secret. Config via `@toolctrl/config`.
|
||||
- `utils/services/.server/subscriptionService.ts`, `subscriptionCache.server.ts`, `pricingService.ts`, `tenantPlanLookup.server.ts`.
|
||||
- `utils/db/subscriptions/tenantSubscriptionProducts.db.server.ts`, `utils/db/stripe/checkoutSessions.db.server.ts`.
|
||||
- `utils/helpers/SubscriptionHelper.ts`, `application/pricing/plans.server.ts`.
|
||||
- UI: `components/core/settings/subscription/*` (Plans, ChangeSubscription, MyPayments, MyInvoices, MyUpcomingInvoice, MyPaymentMethods, TenantProduct), `components/core/pricing/*`.
|
||||
- DTOs/Enums: `application/dtos/subscriptions/*`, `application/enums/subscriptions/*`.
|
||||
|
||||
**Entitlements-Paket** (`packages/entitlements/src/index.ts`) — Plan-/Feature-Gate-Engine:
|
||||
- `evaluateEntitlement`, `evaluateProductAccess`, `featureGateRegistry`, `featureKeys`, `getFeatureGate`.
|
||||
- `standardEntitlementPlans`, `getStandardEntitlementPlan`, `getStripePricePlaceholder`/`ProductPlaceholder`.
|
||||
- Blueprints (`src/blueprints.ts`): `productBlueprints` (aktuell nur `crm-saas`), `getProductBlueprint`.
|
||||
- AI-Quotas/Overage: `resolveTenantAIQuota`, `getAIQuotaPlanDefaults`, `resolveTenantAIOverage`, `computeMarkedUpCostCents`.
|
||||
|
||||
**Worker:** `apps/worker/src/jobs/ai-cost-stripe-report.ts` (+ cron/submitter/bootstrap) — meldet AI-Kosten als Stripe-Usage.
|
||||
|
||||
**HiveGrid-Relevanz:** Vollstaendiger Stripe-Billing-Stack (Produkte, Preise, Usage-Based, Trials,
|
||||
Checkout, Tenant-Subscriptions, Credits) + Entitlements/Feature-Gating. Direkt als Billing-Modul nutzbar.
|
||||
Blueprint-System (`crm-saas`) ist erweiterbar fuer HiveGrid-spezifische Plaene.
|
||||
|
||||
---
|
||||
|
||||
## 8. Onboarding-Wizard — Schema + Service
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/onboarding.prisma`):
|
||||
- `Onboarding` (type: modal/page, realtime, active, canBeDismissed) -> `OnboardingFilter` (Zielgruppen-Filter), `OnboardingStep` (order, block JSON).
|
||||
- Session-Tracking: `OnboardingSession` (status active/completed/dismissed, started/completed/dismissedAt, unique [onboarding,user,tenant]) -> `OnboardingSessionStep` (seenAt/completedAt), `OnboardingSessionAction`, `OnboardingSessionFilterMatch`.
|
||||
|
||||
**Service-Layer** (`apps/web/app/modules/onboarding/`):
|
||||
- `services/OnboardingService.ts`, `OnboardingSessionService.ts`, `OnboardingStepsService.ts`, `OnboardingFiltersService.ts`.
|
||||
- `db/onboarding.db.server.ts`, `onboardingSessions.db.server.ts`, `onboardingSessionSteps.db.server.ts`.
|
||||
- Blocks/Components/DTOs/Utils: `blocks/OnboardingBlock*.tsx`, `components/Onboarding*.tsx`, `dtos/Onboarding*.ts`, `utils/Onboarding*Utils.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** Fertiger Onboarding-/Aktivierungs-Flow mit Modal/Page-Varianten, Zielgruppen-Filtern,
|
||||
Step-Tracking und Realtime-Trigger. Direkt fuer User-Onboarding nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## 9. Help-Desk / Support — Schema + Service
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/helpDesk.prisma`):
|
||||
- `Feedback` — schlankes In-App-Feedback (message, fromUrl, tenant/user optional).
|
||||
- `SupportTicket` — Tickets (source, status default `open`, priority default `normal`, subject, message, fromEmail, fromUrl, `inboundMessageId` unique fuer E-Mail-Dedup). Indizes auf [tenant,status,createdAt] und [source,createdAt].
|
||||
|
||||
**Service-Layer** (`apps/web/app/modules/helpDesk/`):
|
||||
- `services/Feedback.server.ts`, `SupportTickets.server.ts`, `FeedbackRedaction.server.ts` (+ `.ts`).
|
||||
- `db/feedback.db.server.ts`, `supportTickets.db.server.ts`.
|
||||
- `components/FeedbackTable.tsx`.
|
||||
|
||||
**HiveGrid-Relevanz:** Leichtgewichtiges Support-/Feedback-Modul (kein voller Helpdesk mit Threads, aber
|
||||
Ticket-Aufnahme inkl. Inbound-E-Mail-Dedup und PII-Redaction). Direkt fuer Support-Inbox nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## 10. Customer-Portals — Schema + Service
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/portals.prisma`): umfangreiches White-Label-Portal-System:
|
||||
- `Portal` — Subdomain (unique) + optional Custom-`domain`, SEO-Felder, Branding (Logo/Icon/Favicon + DarkMode), Auth-Anforderungen (EmailVerification/Organization/Name), Analytics-Toggles (Simple/Plausible/Google), `stripeAccountId` (Connect), `metadata`.
|
||||
- `PortalUser` (separate Portal-User mit passwordHash, github/google OAuth, locale) + `PortalUserRegistration` (Token-basierte Einladung).
|
||||
- `PortalPage` (name + attributes JSON).
|
||||
- Eigenes Portal-Subscription-Subsystem: `PortalSubscriptionProduct/Price/Feature`, `PortalUserSubscription(Product)(Price)`, `PortalCheckoutSessionStatus` (gespiegeltes Tenant-Subscription-Modell fuer Portal-Endkunden).
|
||||
|
||||
**Service-Layer** (`apps/web/app/modules/portals/`):
|
||||
- `services/Portal.server.ts`, `PortalStripe.server.ts`, `PortalPricing.server.ts`, `PortalSubscription.server.ts`, `StripeConnect.server.ts`.
|
||||
- `db/portals.db.server.ts`, `portalUsers.db.server.ts`, `portalSubscriptionProducts.db.server.ts`, `portalUserSubscriptions.db.server.ts`, `portalCheckoutSessions.db.server.ts`, `portalPages.db.server.ts`.
|
||||
- `utils/StripeConnectUtils.ts`, `PortalUtils.ts`, `analytics-redaction.ts`; `helpers/PortalUser*ModelHelper.ts`; `dtos/PortalDto.ts`, `PortalUserDto.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** Vollstaendiges Customer-/Partner-Portal mit eigener User-Basis, White-Label-Branding,
|
||||
eigenem Stripe-Connect-Billing und eigener Analytics. Direkt fuer kundeneigene/partner-Portale nutzbar
|
||||
(z.B. End-Kunden eines HiveGrid-Tenants). Komplexester Domaenen-Baustein im Set.
|
||||
|
||||
---
|
||||
|
||||
## 11. Entity-Builder (Custom-Felder / No-Code-Entitaeten)
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/entityBuilder.prisma`) — sehr umfangreich, Kern des No-Code-Systems:
|
||||
- `Entity` — Definition (name/slug/prefix unique, type app/admin/all, hasTags/Comments/Tasks/Activity/Views/BulkDelete, defaultVisibility, onCreated/onEdit, hasApi).
|
||||
- `Property` (Feld-Definition, type Int + subtype, isRequired/Hidden/Unique/ReadOnly, formula) -> `PropertyAttribute` (pattern/min/max/...), `PropertyOption` (Select-Optionen).
|
||||
- `EntityView` + `EntityViewProperty/Filter/Sort` — Views (table/board/calendar/list/gallery, Grid-Spalten, groupBy).
|
||||
- `Row` -> `RowValue` (text/number/date/boolean) + `RowValueMultiple`/`RowValueRange`/`RowMedia` — Datensaetze.
|
||||
- Relationen: `EntityRelationship` (one-to-many etc.) + `RowRelationship`.
|
||||
- Cross-Cutting auf Rows: `RowComment` (+ `RowCommentReaction`), `RowTag` (+ `EntityTag`), `RowTask`, `RowPermission` (row-level ACL: tenant/role/group/user/public).
|
||||
- `EntityWebhook` (+ `EntityWebhookLog`) — Per-Entity-Outbound-Webhooks.
|
||||
- `EntityTemplate`, `EntityGroup`/`EntityGroupEntity`/`EntityGroupConfiguration(Row)` — Gruppierung & Templates.
|
||||
- `Formula`/`FormulaComponent`/`FormulaLog`/`FormulaComponentLog` — berechnete Felder.
|
||||
- `ApiKeyEntity` — Per-Entity-API-Key-CRUD-Rechte. `TenantSettingsRow`, `SampleCustomEntity`.
|
||||
|
||||
**Service-/UI-Layer** (`apps/web/app/`):
|
||||
- `components/entities/{rows,properties,views,relationships,webhooks,templates,entityTemplates}/...`.
|
||||
- `utils/db/entities/...`, `routes/admin/entities`, `routes/app.$tenant/$entity.__autogenerated/...` (auto-generierte CRUD-Routen).
|
||||
- `application/dtos/entities/*`, `application/enums/entities/*`, `modules/formulas/...`.
|
||||
|
||||
**HiveGrid-Relevanz:** Kompletter No-Code-Entity-Builder mit Custom-Feldern, Views, Relationen, Formeln,
|
||||
Row-Level-Permissions, Kommentaren/Tasks/Tags und Per-Entity-Webhooks. Zentraler Baustein fuer
|
||||
benutzerdefinierte Datenobjekte / Custom-Felder in HiveGrid-Modulen. Form-Widget routet direkt auf Entity-Rows.
|
||||
|
||||
---
|
||||
|
||||
## 12. Knowledge-Base (Help-Center) — Schema + Service
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/knowledgeBase.prisma`):
|
||||
- `KnowledgeBase` (tenant-optional + `ownerKey` default `global`, basePath, slug, multi-language `languages`, layout, color, enabled, SEO).
|
||||
- `KnowledgeBaseCategory` -> `KnowledgeBaseCategorySection` — Hierarchie.
|
||||
- `KnowledgeBaseArticle` — Draft + Published Content (`contentDraft`, `contentPublished`, `contentPublishedAsText` fuer Suche), contentType, language, featuredOrder, publishedAt, related Articles (`KnowledgeBaseRelatedArticle`).
|
||||
- Analytics/Voting: `KnowledgeBaseViews`, `KnowledgeBaseArticleViews/Upvotes/Downvotes` (je unique pro userAnalyticsId).
|
||||
|
||||
**Service-Layer** (`apps/web/app/modules/knowledgeBase/`):
|
||||
- `service/KnowledgeBaseService.server.ts`, `KnowledgeBaseTemplatesService.server.ts`.
|
||||
- `services/kbArticleSearch.server.ts`, `kbArticleRag.server.ts` (RAG/AI-Suche).
|
||||
- `db/knowledgeBase.db.server.ts`, `kbArticles.db.server.ts`, `kbCategories.db.server.ts`, `kbCategorySections.db.server.ts`, `kbAnalytics.db.server.ts`.
|
||||
- Public Components: `components/Kb*.tsx` (Search/Header/FeaturedArticles/Skeletons); DTOs `dtos/Kb*Dto.ts`; `utils/DefaultKbsTemplate.ts`, `KnowledgeBaseUtils.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** Fertiges Help-Center mit Kategorien/Sektionen/Artikeln, Draft/Publish-Workflow,
|
||||
Multi-Language, Voting/Views-Analytics und AI/RAG-Suche. Direkt als Wissensdatenbank/Help-Center nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## 13. Analytics (Visitor / PageView / Event)
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/analytics.prisma`):
|
||||
- `AnalyticsSettings` (public, ignorePages/onlyPages).
|
||||
- `AnalyticsUniqueVisitor` (cookie unique, UTM source/medium/campaign/content/term, referrer, Browser/OS/Device, Geo country/city, optional user/portal/portalUser).
|
||||
- `AnalyticsPageView`, `AnalyticsEvent` (action/category/label/value, optional featureFlag-Bezug).
|
||||
|
||||
**Service-Layer:** v.a. portal-zentriert — `apps/web/app/modules/portals/utils/analytics-redaction.ts`
|
||||
(PII-Redaction). Modelle haengen ueberwiegend an `Portal`/`PortalUser`.
|
||||
|
||||
**HiveGrid-Relevanz:** Eingebaute First-Party-Web-Analytics (Visitor/PageView/Event + UTM + Geo + Device).
|
||||
Stark an Portals gekoppelt; fuer allgemeines Tracking als Vorlage nutzbar. Reifegrad: Daten-Modell + Service
|
||||
(kein eigenstaendiges Paket, kein dediziertes Analytics-Dashboard-Modul nachgewiesen).
|
||||
|
||||
---
|
||||
|
||||
## 14. Marketing-Leads / Funnel + Outbound
|
||||
|
||||
**Prisma-Modelle** (`prisma/schema/marketingLeads.prisma`):
|
||||
- `Lead` — system-of-record fuer Marketing-Prospects (NICHT tenant-scoped, gehoert Operator). First-Touch-Attribution (utmSource/Medium/Campaign/Term/Content, gclid, fbclid, referrer, landingPage, nie ueberschrieben), `status` enum `LeadStatus` (new/contacted/qualified/trial/customer/churned/disqualified), `score`, `notes` JSON, `convertedToTenantId`, `lastIpHash` (SHA-256, kein Raw-IP).
|
||||
- `LeadEvent` — Activity-Timeline (captured/re-captured/status-changed/assigned/note-added/score-changed/converted).
|
||||
- `TenantAcquisition` — Attribution-Snapshot eingefroren bei Tenant-Erstellung (tenantId unique, leadId optional, UTM-Spalten bleiben stabil auch nach GDPR-Anonymisierung des Leads).
|
||||
- `MarketingIntegration` — operator-konfigurierte Outbound-Integration (type slack/discord/mailchimp/hubspot/brevo/webhook, `configJson` mit AES-256-GCM-verschluesselten Secrets, `triggerEvents[]`, lastDeliveredAt/lastError).
|
||||
|
||||
**Paket `@toolctrl/marketing-outbound`** (`packages/marketing-outbound/src/index.ts`):
|
||||
- Adapter-Registry: `slack`, `discord`, `mailchimp`, `hubspot`, `brevo`, `webhook` (custom). `resolveAdapter(type)`, `ADAPTER_TYPES`.
|
||||
- Pro Adapter `*Config` + `build*Payload`/`build*Blocks/Embed`. Typen `MarketingOutboundAdapter`, `MarketingLeadPayload`, `MarketingLeadEventType` (`src/types.ts`).
|
||||
|
||||
**Service-/Worker-Layer:**
|
||||
- `apps/web/app/utils/leads/...` (Capture-/Admin-Logik), public Endpoint `/api/leads/capture` + `marketing.js` SDK (laut Schema-Kommentar).
|
||||
- Worker: `apps/worker/src/jobs/marketing-outbound.ts` (dispatcht Outbox-Events durch Adapter), `lead-stale-trigger.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** Vollstaendiger Lead-Funnel: Public Lead-Capture mit First-Touch-Attribution,
|
||||
Lead-Scoring, Status-Pipeline, Konversion-zu-Tenant mit DSGVO-festen Attribution-Snapshots, und
|
||||
Outbound-Integrationen (Slack/Discord/Mailchimp/HubSpot/Brevo/Webhook). Direkt fuer Marketing-/Sales-Funnel nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## Quellen-Hinweise
|
||||
|
||||
- Pakete: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/{form-widget,imports,exports,brand,shared-store,api-client-ts,api-types,entitlements,marketing-outbound}`
|
||||
- Prisma-Schemas: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/{subscriptions,onboarding,helpDesk,portals,knowledgeBase,analytics,marketingLeads,entityBuilder,formWidget,imports}.prisma`
|
||||
- Service-Layer: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/modules/{onboarding,helpDesk,portals,knowledgeBase,formWidget}` und `apps/web/app/utils/{stripe.server.ts,db,services,leads}`
|
||||
- Worker-Jobs: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/jobs/{export,dsgvo-export,form-submission-*,marketing-outbound,ai-cost-stripe-*,lead-stale-trigger}.ts`
|
||||
- Stripe-API-Version im Code: `2025-10-29.clover` (`apps/web/app/utils/stripe.server.ts`)
|
||||
</content>
|
||||
@@ -0,0 +1,303 @@
|
||||
# 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` |
|
||||
@@ -0,0 +1,345 @@
|
||||
# Boilerplate-Inventur: Integrationen, KI & Apps-Engine
|
||||
|
||||
> Faktische Inventur des Boilerplate-Bereichs "Integrationen, KI & Apps-Engine".
|
||||
> Quelle (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
|
||||
> Erstellt fuer den Modul-Abgleich gegen HiveGrid 2.0. Alle Pfade absolut.
|
||||
> Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en).
|
||||
|
||||
## Inhaltsverzeichnis / abgedeckte Pakete
|
||||
|
||||
| Paket | npm-Name | Zweck (kurz) |
|
||||
|---|---|---|
|
||||
| `packages/ai` | `@toolctrl/ai` | KI-Provider-Layer (Mistral/Scaleway/Aleph Alpha), Multi-Provider-Fallback, Embeddings/RAG-Pipeline, Cost-Tracking, Prompt-/Tool-Registry, Guards, Streaming |
|
||||
| `packages/vector-store` | `@toolctrl/vector-store` | Vektor-Store-Adapter (pgvector + Qdrant) hinter einem Interface, tenant-scoped Wrapper |
|
||||
| `packages/search` | `@toolctrl/search` | Typisierter Meilisearch-Wrapper, tenant-scoped Such-Index, Index-Schemas, Outbox-Publisher |
|
||||
| `packages/plugins` | `@toolctrl/plugins` | Feature-Manifest-Schema + Loader (Apps-/Feature-Inventur-Manifeste) |
|
||||
| `packages/plugin-runtime` | `@toolctrl/plugin-runtime` | WASM-Sandbox, Capability-Gateway, Manifest, Signatur, Hooks, Audit-Chain, Crash-Tracker, Migrations |
|
||||
| `packages/plugin-sdk` | `@toolctrl/plugin-sdk` | Typdefinitionen + Settings-Iframe-Client fuer Plugin-Autoren (`defineHook`, `HostApi`) |
|
||||
| `packages/storage` | `@toolctrl/storage` | S3/Scaleway-Storage-Adapter + lokaler Adapter, Signed-URLs, Virus-Scan (ClamAV/magic-bytes), Quarantaene |
|
||||
| `packages/realtime` | `@toolctrl/realtime` | SSE/Realtime-Event-Serialisierung + Client/Server-Helfer (Notifications) |
|
||||
| `packages/mail` | `@toolctrl/mail` | MailerSend-Provider, Queued-Mail-Provider, React-Email Transaktionstemplates |
|
||||
| `packages/email-templates` | `@toolctrl/email-templates` | React-basierte Sequenz-Email-Templates (welcome, trial-reminder, re-activation) |
|
||||
| `packages/email-sequences` | `@toolctrl/email-sequences` | Reine Logik: Sequenz-Engine, Condition-DSL, Step-Runner, Unsubscribe-Token |
|
||||
| `packages/marketing-outbound` | `@toolctrl/marketing-outbound` | Outbound-Webhook-Adapter (Slack, Discord, Mailchimp, HubSpot, Brevo, Custom) |
|
||||
| `packages/queue` | `@toolctrl/queue` | BullMQ-Wrapper: Queue-Namen, typisierte Producer/Jobs, Idempotenz, Prioritaeten, Redis-Connection |
|
||||
|
||||
Konvention durchgaengig: jedes Paket exportiert `exports` mit `.` -> `./src/index.ts` (Source-Exports, kein Build-Schritt zwingend), Scripts meist `test` / `typecheck` (teils `build`, `preview`). Pakete sind bewusst **dependency-arm** und lesen **nie `process.env` direkt** — Boundary-Code (apps/api, apps/worker) reicht env-Snapshots herein (Env-Access-Enforcement-Tests).
|
||||
|
||||
---
|
||||
|
||||
## 1. `@toolctrl/ai` — KI-Provider-Layer, Fallback, RAG, Cost
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ai`
|
||||
**Deps:** `@ai-sdk/mistral`, `@ai-sdk/openai-compatible`, `ai` (Vercel AI SDK), `gpt-tokenizer`, `@toolctrl/entitlements`
|
||||
**Subpath-Exports:** `.`, `./cost`, `./embeddings`, `./embeddings/providers/{openai,scaleway,aleph-alpha,anthropic}`
|
||||
|
||||
### 1.1 Provider-Adapter & Multi-Provider-Fallback
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Provider-Adapter-Interface + Registry | `packages/ai/src/index.ts` | `AIProviderAdapter`, `AIProviderName = "mistral" \| "scaleway" \| "aleph-alpha"`, `getAIProviderAdapter()`, `getAIProviderAdapterForModel()`, `getPrimaryProvider()`, `getAIProviderDiagnostics()`, Modell-Katalog `aiModels` (mit Preisen pro Mio Tokens), `defaultAIModel = "mistral-large-latest"`, `AIProviderAdapterError` mit typisierten Codes |
|
||||
| Mistral-Provider | `packages/ai/src/providers/mistral.ts` | `createMistralLanguageModel()` via `@ai-sdk/mistral` `createMistral`, `resolveMistralModel(env)`, `MISTRAL_API_KEY`/`MISTRAL_MODEL` |
|
||||
| Scaleway-Provider (OpenAI-kompatibel) | `packages/ai/src/providers/scaleway.ts` | `createScalewayLanguageModel()`, Default-BaseURL `https://api.scaleway.ai/v1`, Default-Modell `mistral-small-3.2-24b-instruct-2506`, `SCALEWAY_API_KEY`/`SCALEWAY_BASE_URL`/`SCALEWAY_MODEL` |
|
||||
| Aleph-Alpha-Provider (OpenAI-kompatibel) | `packages/ai/src/providers/aleph-alpha.ts` | `createAlephAlphaLanguageModel()`, Default-BaseURL `https://api.aleph-alpha.com/v1`, Default-Modell `pharia-1-llm-7b-control`, `ALEPH_ALPHA_API_KEY`/`...BASE_URL`/`...MODEL` |
|
||||
| OpenAI-Compatible-Bruecke | `packages/ai/src/providers/compatible.ts` | `createCompatibleLanguageModel()` ueber `@ai-sdk/openai-compatible` — gemeinsame Basis fuer Scaleway + Aleph Alpha |
|
||||
| Health-Tracker + Fallback | `packages/ai/src/fallback.ts` | `AIProviderHealthTracker` (Failure-Window 30 min), `getFallbackProviderSelection()`, `fallbackProviderOrder = ["mistral","scaleway","aleph-alpha"]` — durchlaeuft Provider in fester Reihenfolge, ueberspringt ungesunde/unkonfigurierte |
|
||||
|
||||
**HiveGrid-Relevanz:** Kern fuer jedes KI-Modul (Chatbot, Prompt-Flows, Generieren, RAG-Antworten). EU-Provider Scaleway/Aleph Alpha = DSGVO-Argument. Multi-Provider-Fallback deckt Querschnitt "KI-Verfuegbarkeit/Resilienz" ab.
|
||||
|
||||
### 1.2 Embeddings-Pipeline (RAG-Schreib-/Leseseite)
|
||||
|
||||
**Pfad:** `packages/ai/src/embeddings` — Subpath `@toolctrl/ai/embeddings`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Provider-Interface + Typen | `packages/ai/src/embeddings/types.ts` | `EmbeddingProvider` (`embed`/`embedSingle`, `dimensions`, `maxBatchSize`), `EmbeddingProviderName = "openai" \| "scaleway" \| "aleph-alpha" \| "anthropic"`, `EmbeddingProviderError` mit typisierten Codes, `EmbeddingProviderEnv`-Snapshot |
|
||||
| Factory + Registry | `packages/ai/src/embeddings/factory.ts` | `createEmbeddingProvider()`, `registerEmbeddingProviderAdapter()` (Adapter registrieren sich selbst), `resolveEmbeddingProviderName(env)` (Default openai->scaleway->aleph-alpha), `resolveEmbeddingDimensions(env)` |
|
||||
| Embed-Adapter (opt-in subpaths) | `packages/ai/src/embeddings/providers/{openai,scaleway,aleph-alpha,anthropic}.ts` | Scaleway-Default `bge-multilingual-gemma2` (1024 dim), Batch 64, max 4096 Tokens; Anthropic ist bewusst Stub/Platzhalter |
|
||||
| Schreibseite | `packages/ai/src/embeddings/embed-and-upsert.ts` | `embedAndUpsert()` — chunked, embeds, upsert in `VectorUpsertSink`; erzwingt `tenantId` im Payload; deterministische `buildChunkId()`; optionale Kostenverfolgung ueber `executeLLMCall` (capability `embedding`) |
|
||||
| Leseseite | `packages/ai/src/embeddings/retrieve.ts` | `retrieveRelevantContext()` — Query embedden, Fan-out ueber Collections, Rank-Merge, min-Score 0.7, top-K 8; tenant-scoped via `RagRetrievalStore.searchForTenant` |
|
||||
| Chunking | `packages/ai/src/embeddings/chunking.ts` | `splitForEmbedding()`, `countTokens()`, `DEFAULT_CHUNK_TOKENS`/`...OVERLAP_TOKENS` |
|
||||
| Outbox-Publisher (RAG-Index) | `packages/ai/src/embeddings/outbox-publisher.ts` | `publishRagUpsertEvent`/`publishRagDeleteEvent`, `ragEventType()` -> `rag.index.<entity>.<verb>` (mapped auf BullMQ-Queue `outbox.rag-index`), Idempotenz via `dispatchKey` |
|
||||
|
||||
**HiveGrid-Relevanz:** Komplette RAG-Grundlage (Knowledge-Base-Suche, KI-Antworten mit Quellen, semantische Suche). Outbox-Pattern erlaubt async Reindex bei jedem Domain-Write. Direkt nutzbar fuer HiveGrid-Module "Wissensdatenbank/RAG" und "KI-Assistent".
|
||||
|
||||
### 1.3 Cost-Tracking, Quota & Guards
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Cost-Barrel | `packages/ai/src/cost/index.ts` | Re-Export: `countTokens`, `countCallCost`, `executeLLMCall`, `estimateLLMCost`, Pricing-Tabelle (`getPricingTable`, `LATEST_PRICING_VERSION`), Spend-Cache, Quota |
|
||||
| LLM-Wrapper | `packages/ai/src/cost/executeLLMCall.ts` | `executeLLMCall()` — wrappt jeden Provider-Call, leitet Token/Kosten ab, emittiert Outbox-Event `ai.cost.event.persist`, Quota-Pre-Check + Soft-Degradation + Concurrency-Slot; `setLLMCostPublisher/MetricsHook/ErrorHandler`; Flag `AI_COST_TRACKING_ENABLED=false` deaktiviert; capabilities `chat`/`chat-stream`/`embedding`/`completion`/`rerank`/`tool-call` |
|
||||
| Quota-Guard | `packages/ai/src/cost/assertCredit.ts` | `assertTenantAICreditAccess()`, Concurrency-Counter (Redis-aehnlich), Soft-Degradation-Threshold |
|
||||
| Spend-Cache | `packages/ai/src/cost/spend-cache.ts` | `createSpendCache()`, Monatsspend-Caching (TTL) |
|
||||
| Token-Zaehlung | `packages/ai/src/cost/tokens.ts` | `countTokens`/`countMessageTokens` (gpt-tokenizer + Heuristik-Fallback) |
|
||||
| Guards | `packages/ai/src/guards/index.ts` | `assertAICostBudget()`, `createFixedWindowAIRateLimiter()` (pro userId), `createAIAuditEvent()`/`redactAIAuditPayload()` (PII-Redaction, prompt/tool_call/mutation), `createReviewRequiredResult()`, `AIGuardError` |
|
||||
|
||||
**HiveGrid-Relevanz:** Querschnitt "Billing/Usage-Metering" (KI-Kosten pro Tenant), "Rate-Limiting", "Audit/DSGVO" (Redaction). Persistiert in Prisma `AICostEvent` (siehe unten). Direkt fuer HiveGrid-Modul "KI-Kontingente/Abrechnung".
|
||||
|
||||
### 1.4 Prompt-/Tool-Registry, Streaming, Eval
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Prompt-Registry | `packages/ai/src/prompts/index.ts` | `createAIPromptRegistry()` mit Versionierung, `render(selection, variables)`, `{{var}}`-Templates, `AIPromptRegistryError` |
|
||||
| Tool-Registry | `packages/ai/src/tools/index.ts` | `createAIToolRegistry()` (scoped Tools fuer Vercel AI SDK `ToolSet`), `toToolSet(selection)`, Secret-Redaction in Fehlern |
|
||||
| Streaming | `packages/ai/src/streaming/index.ts` | `createAITextStream()` ueber `streamText` (Vercel AI SDK), Guard-Evaluator, Prompt-/Tool-Registry-Integration, `getAITextStreamDiagnostics()` mit Redaction |
|
||||
| Promptfoo-Provider + Evals | `packages/ai/src/promptfoo-provider.ts`, `packages/ai/test/evals/`, Repo-Root `promptfoo.config.yaml` | Eval-Harness (promptfoo-Baseline-Test) |
|
||||
|
||||
**HiveGrid-Relevanz:** "Prompt-Flows / Prompt-Bibliothek" (Versionierung), "KI-Tools/Agenten" (scoped Tool-Registry), Streaming-Chat-UX.
|
||||
|
||||
---
|
||||
|
||||
## 2. `@toolctrl/vector-store` — Vektor-Store-Adapter (pgvector + Qdrant)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/vector-store`
|
||||
**Deps:** `@qdrant/js-client-rest`
|
||||
**Subpath-Exports:** `.`, `./factory`, `./adapters/pgvector`, `./adapters/qdrant`, `./wrappers/tenant-scoped`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Adapter-Interface + Typen | `packages/vector-store/src/types.ts` | `VectorStoreAdapter` (createCollection/upsert/search/delete/health), `VectorItem` mit Pflicht-`payload.tenantId`, `VectorFilter`/`FilterClause` (Qdrant-Filter-Sprache), `VectorMetric = "cosine"\|"euclidean"\|"dot"`, `VectorDimensionMismatchError` |
|
||||
| Factory (Adapter-Auswahl) | `packages/vector-store/src/factory.ts` | `createVectorStore()` -> waehlt pgvector (Default) oder Qdrant (`adapter:` oder `qdrantUrl`); `resolveAdapter()`; Namespace-Pflicht; gibt tenant-scoped Store zurueck |
|
||||
| pgvector-Adapter | `packages/vector-store/src/adapters/pgvector.ts` | `PgvectorAdapter` ueber `PrismaLike` (`$queryRawUnsafe`/`$executeRawUnsafe`), erstellt `vec_<namespace>_<collection>`-Tabellen, HNSW-Index (`m`, `efConstruction`), Payload-Filter via `payload ->> 'key'` |
|
||||
| Qdrant-Adapter | `packages/vector-store/src/adapters/qdrant.ts` | `QdrantAdapter` ueber `QdrantClientLike`, Namespace-Praefix |
|
||||
| Tenant-Scope-Wrapper | `packages/vector-store/src/wrappers/tenant-scoped.ts` | `withTenantScope()` -> `TenantScopedVectorStore`; `searchForTenant()` injiziert `tenantId`-must-Filter zwingend; bare `searchVectors()` wirft; `listVectorIds()` scoped nach tenant/sourceType/sourceId |
|
||||
| Konformanztest | `packages/vector-store/src/adapters/conformance.test.ts` | Erzwingt byte-fuer-byte gleiches Verhalten beider Adapter |
|
||||
|
||||
**Prisma:** Kein Prisma-Modell — pgvector legt eigene `vec_*`-Tabellen via Raw-SQL an. Migration: `prisma/migrations/20260517085146_04_enable_pgvector/migration.sql` (aktiviert `pgvector`-Extension).
|
||||
|
||||
**HiveGrid-Relevanz:** Speicher-Backend fuer RAG/semantische Suche. pgvector = "kein Extra-Service" (laeuft auf Haupt-Postgres), Qdrant = Upgrade-Pfad. Tenant-Isolation built-in. Direkt fuer HiveGrid "RAG"/"semantische Suche".
|
||||
|
||||
---
|
||||
|
||||
## 3. `@toolctrl/search` — Meilisearch Such-Index
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/search`
|
||||
**Deps:** `meilisearch`, `zod`
|
||||
**Subpath-Exports:** `.`, `./schemas`, `./testing`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Client-Adapter | `packages/search/src/client.ts` | `createSearchClient()` — kapselt Meilisearch-SDK (nie re-exportiert), `SearchClient`/`IndexHandle` (ensure/search/upsert/delete/deleteByFilter), `meiliFactory`-Injection fuer Tests |
|
||||
| Query-Layer (tenant-scoped) | `packages/search/src/query.ts` | `searchInIndex`, `searchWithFallback`, `bulkIndex`, `deleteFromIndex`, `health`, `TenantScopeError` — jede Suche erzwingt `tenantId`-Filter |
|
||||
| Index-Helper | `packages/search/src/index-helper.ts` | `createSearchIndex()`, `validateIndexSchema()`, `IndexSchemaValidationError` |
|
||||
| Index-Schemas | `packages/search/src/schemas/` (`kb-articles.ts`, `crm-contacts.ts`, `rows.ts`, `entities.ts`, `users.ts`, `index.ts`) | `ALL_SEARCH_INDEXES`, `BULK_REINDEX_SUPPORTED_INDEXES`, `getSearchIndexSchema()` |
|
||||
| Outbox-Publisher | `packages/search/src/outbox-publisher.ts` | `publishSearchUpsertEvent`/`publishSearchDeleteEvent`/`publishSearchBulkReindexEvent`, `searchEventType()` |
|
||||
| Sanitize | `packages/search/src/sanitize.ts` | `sanitizeDocument()` |
|
||||
|
||||
**HiveGrid-Relevanz:** Volltextsuche fuer KB-Artikel, CRM-Kontakte, generische Entity-Rows, User. Outbox-getriebener Reindex. Querschnitt "Suche" parallel zur Vektorsuche (hybrid moeglich).
|
||||
|
||||
---
|
||||
|
||||
## 4. Apps-Engine / Plugin-System (Kern-Fokus)
|
||||
|
||||
Wichtige Unterscheidung im Boilerplate:
|
||||
- **`@toolctrl/plugins`** = Feature-/App-**Manifest-Inventur** (Klassifizierung von Features als core/plugin-candidate, Integration-Surfaces) — kein Laufzeit-Sandbox.
|
||||
- **`@toolctrl/plugin-runtime` + `@toolctrl/plugin-sdk`** = echtes **WASM-Plugin-Laufzeitsystem** mit Capability-Modell (das "Apps-Engine"-Adapter-/Sandbox-Pattern).
|
||||
- **Prisma `appsEngine.prisma`** = separate **Data-Sync-"App"-Engine** (App/DataConnection/AppSyncRun) fuer externe Datenquellen-Integrationen.
|
||||
|
||||
### 4.1 `@toolctrl/plugins` — Feature-Manifest-Schema + Loader
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/plugins` (keine Deps)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Manifest-Schema | `packages/plugins/src/manifest-schema.ts` | `FeatureManifest` (schemaVersion "1.0", classification core/plugin-candidate/remove-candidate/mixed, `integration.surfaces` admin/tenant/public/api-Routes, `integration.workers` queues/jobs, externalProviders, permissions, auditEvents, billingImpacts, uat, `boundaries`, `pruning`), `validateFeatureManifestShape()` (handgeschriebener Validator, kein zod) |
|
||||
| Loader | `packages/plugins/src/manifest-loader.ts` | `loadFeatureManifests()` |
|
||||
|
||||
**HiveGrid-Relevanz:** Methodik-/Governance-Werkzeug — beschreibt, welche Features Plugin-Kandidaten sind und welche Surfaces/Worker/Provider sie brauchen. Nuetzlich als Vorlage fuer HiveGrid-Modul-/Plugin-Klassifizierung, weniger als Laufzeit.
|
||||
|
||||
### 4.2 `@toolctrl/plugin-runtime` — WASM-Sandbox + Capability-Gateway
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/plugin-runtime`
|
||||
**Deps:** `@toolctrl/logger`, `@toolctrl/shared-store`, `semver`, `zod`
|
||||
**Subpath-Exports:** `.`, `./capabilities`, `./hooks/registry`, `./manifest`
|
||||
**README:** `packages/plugin-runtime/README.md`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| WASM-Sandbox | `packages/plugin-runtime/src/runtime.ts` | `createPluginSandbox()` — Node-22 `WebAssembly`, Memory-Cap (Default 64 MB), Fuel-Budget (Default 1.000.000), JSON-Payload-ABI (`toolctrl_payload_len`/`...byte`), `invoke(hookName, payload)`, typisierte Failures (compile/instantiate/fuel_exhausted/memory_limit/trap). Upgrade-Pfad: Wasmer/Wasmtime hinter gleichem Interface |
|
||||
| Capability-Enum | `packages/plugin-runtime/src/capabilities.ts` | `PLUGIN_CAPABILITY_NAMES` (http.outbound, db.read/write, storage.read/write, log, audit, tenant.info, secret.read), Risk-Metadata, **`PLUGIN_AVAILABLE_HOST_CAPABILITY_NAMES = ["log","audit"]`** (nur diese in Prod aktiv), `productionAvailable`-Flags |
|
||||
| Capability-Gateway | `packages/plugin-runtime/src/capability-gateway.ts` | `createCapabilityGateway()` — deny-by-default; prueft manifest-deklariert + tenant-granted + Scope; `CapabilityDeniedError` mit Gruenden (not_declared/not_granted/scope_violation/no_host_implementation); laedt Fuel pro Call; `onCall`-Hook fuer Audit |
|
||||
| Manifest (Plugin) | `packages/plugin-runtime/src/manifest.ts` | `PluginManifestSchema` (zod): Reverse-DNS-id, SemVer, `entry` (.wasm), `wasmSha256`, Ed25519 `signature`/`signedBy`, `allowedHosts` (SSRF-Allowlist, kein localhost/IP/.internal), `capabilities` mit `scope` (allowedHosts/keyPattern/tablePrefix), `hooks` (name->export), optional `ui.settings` (HTML + SHA256/Integrity), `min/maxHostVersion`; `parsePluginManifest()` (safe), `manifestDeclaresCapability()` |
|
||||
| Signatur | `packages/plugin-runtime/src/signature.ts` | `verifyPluginSignature()` (Ed25519), `parseTrustedPublicKeys()`, `canonicalPluginSignaturePayload()` |
|
||||
| Capability-Grants/Scope | `packages/plugin-runtime/src/capability-grants.ts`, `.../capability-scope.ts` | `PluginCapabilityGrant`, `isCapabilityGrantScopeSatisfied()`, `isCapabilityCallWithinScope()` |
|
||||
| Hooks-Registry | `packages/plugin-runtime/src/hooks/registry.ts` | zod-validierte Hook-Payloads: `tenant.created`, `user.created`, `entity.{created,updated,deleted}`, `workflow.{created,updated,deleted,executed,failed}`; `registerHook()`, `validatePluginHookPayload()`, Prod-Available-Liste |
|
||||
| Hook-Emit | `packages/plugin-runtime/src/hooks/emit.ts` | `emitPluginHook(tx, def, payload, publish)` — validiert + publiziert `plugin.hook.<name>` Outbox-Event in der DB-Transaktion (Fan-out auf Worker-Seite), `PluginHookValidationError` |
|
||||
| Audit (Capability-Use) | `packages/plugin-runtime/src/audit.ts` | `createPluginCapabilityUseRecorder()`, `hashCapabilityPayload()` (kein Roh-Payload), Batch-Sink |
|
||||
| Audit-Chain (Tamper-Evidence) | `packages/plugin-runtime/src/audit-chain.ts` | Per-Tenant Hash-Chain (`prevHash`/`rowHash`), `stampPluginCapabilityUseChain()`, `verifyPluginCapabilityUseChain()` |
|
||||
| Crash-Tracker | `packages/plugin-runtime/src/crash-tracker.ts` | `createCrashTracker()` — auto-disable Plugin nach N Crashes |
|
||||
| Migrations | `packages/plugin-runtime/src/migrations.ts` | `validatePluginMigration()`/`applyPluginMigration()` — Plugin-eigene SQL mit Keyword-Blocklist + Statement-Limit + `tablePrefix`-Scoping |
|
||||
| Version-Check | `packages/plugin-runtime/src/version-check.ts` | `isPluginCompatibleWithHost()` (semver-Range gegen Host) |
|
||||
| Production-Gate | `packages/plugin-runtime/src/production-gate.ts` | `assertPluginRuntimeProductionEnabled()`, Env `PLUGIN_RUNTIME_PRODUCTION_GATE_ENV` |
|
||||
|
||||
### 4.3 `@toolctrl/plugin-sdk` — Autoren-Typen + Settings-Client
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/plugin-sdk` (keine Deps)
|
||||
**README + Beispiele:** `packages/plugin-sdk/README.md`, `packages/plugin-sdk/examples/{hello-world,simple-hook-listener,capability-use,async-task}/` (jeweils `plugin.toml` + `handler.ts`)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| SDK-Typen + `defineHook` | `packages/plugin-sdk/src/index.ts` | `HookHandler`/`TypedHookHandler`, `defineHook()`, `PluginContext`, `HostApi` (log/audit/tenant/http/storage/secret), `PluginCapabilityName`/`PluginHookName` (gespiegelt aus runtime), Hook-Payload-Typen, ABI-Konstanten (`PLUGIN_PAYLOAD_ABI_VERSION`), Settings-Iframe-Protokoll: `createPluginSettingsClient()` (postMessage get/set, Timeout, Channel) |
|
||||
|
||||
**Prisma (Plugins):** `prisma/schema/plugins.prisma`
|
||||
- `Plugin` (tenantId, pluginId, version, manifest Json, wasmSha256, signaturePublicKey, enabled)
|
||||
- `TenantPluginCapabilityGrant` (per-tenant Consent pro Capability, scopeJson) — Install darf erst `enabled` werden, wenn alle deklarierten Capabilities Grants haben
|
||||
- `PluginUserConfig` (per-user opt-in + configJson)
|
||||
- `PluginInvocation` (Audit pro Invoke: outcome/durationMs/fuelUsed)
|
||||
- `PluginCapabilityUse` (per-Capability-Call Audit mit `payloadHash`, Hash-Chain `prevHash`/`rowHash`)
|
||||
|
||||
**Queue:** Queue-Name `toolctrl.plugin-invoke`, Job `plugin.invoke` (siehe Queue-Abschnitt).
|
||||
|
||||
**HiveGrid-Relevanz (4.2/4.3):** Das ist das eigentliche **Apps-Engine/Plugin-Adapter-Pattern** fuer HiveGrid: sicheres, sandboxed Drittanbieter-/Erweiterungssystem mit Capability-Consent, Signatur-Verifikation, Hook-Lifecycle, Audit-Chain und Crash-Schutz. Direkt relevant fuer HiveGrid-Module "Apps/Marketplace", "Integrationen", "Erweiterbarkeit". Achtung: in Prod sind nur `log`/`audit`-Capabilities freigeschaltet — http/db/storage/secret sind Foundation-Stubs (`productionAvailable: false`).
|
||||
|
||||
### 4.4 Prisma Apps-Engine (Data-Sync) — `appsEngine.prisma`
|
||||
|
||||
**Pfad:** `prisma/schema/appsEngine.prisma`
|
||||
|
||||
| Modell | Was |
|
||||
|---|---|
|
||||
| `App` | Installierte App pro Tenant (`type`-Identifier z.B. "sample-data-sync", `config` JSON, isActive) |
|
||||
| `DataConnection` | Verbindung zu externer Datenquelle (`type` "rest-api"/"oauth2"/"webhook", verschluesselte Credentials in `config`) |
|
||||
| `AppSyncRun` | Sync-Lauf (status pending/running/completed/partial/failed/..., executionMode manual/scheduled/webhook, items processed/created/updated/failed) |
|
||||
| `AppSyncRunLog` | Log-Eintraege pro Lauf |
|
||||
| `AppSyncItem` | Einzel-Item-Mapping (sourceId/destinationId, action, rollback-Daten) |
|
||||
|
||||
**HiveGrid-Relevanz:** Separate "Apps-Engine" fuer **externe Datensynchronisation** (ETL-aehnlich, idempotent, mit Rollback + Audit). Relevant fuer HiveGrid-Module "Integrationen/Datenimport" und externe Connector-Apps — komplementaer zum WASM-Plugin-System (4.2).
|
||||
|
||||
---
|
||||
|
||||
## 5. `@toolctrl/storage` — S3/Scaleway-Storage, Signed-URLs, Virus-Scan
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage`
|
||||
**Deps:** `@aws-sdk/client-s3`, `clamscan`, `file-type`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| S3-/Local-Adapter | `packages/storage/src/index.ts` | `createS3StorageAdapter()` (endpoint/region/bucket/credentials, forcePathStyle, publicBaseUrl) ueber `@aws-sdk/client-s3` — Scaleway-/jeder-S3-kompatibel; `createLocalStorageAdapter()` (Dev, Pfad-Traversal-Schutz); `StorageAdapter` (putObject/deleteObject), `StorageAdapterError` mit typisierten Codes + Secret-Redaction |
|
||||
| Signed-URLs | `packages/storage/src/signed/index.ts` | `createSignedUploadUrl`/`createSignedDownloadUrl` (PUT/GET, expiry, contentType, checksumSha256) |
|
||||
| Virus-Scan-Service | `packages/storage/src/scan/index.ts` | `createStorageScanService()` (scan -> bei infected quarantaene), `ScanVerdict` clean/infected/error |
|
||||
| ClamAV-Scanner | `packages/storage/src/scan/clamav-scanner.ts` | `createClamAVStorageScanner()` ueber `clamscan`, `ClamAVUnreachableError` |
|
||||
| Magic-Bytes-Adapter | `packages/storage/src/scan/magic-bytes-adapter.ts` | `createMagicBytesScanAdapter()` ueber `file-type` (Content-Type-Verifikation) |
|
||||
| Allow-List | `packages/storage/src/scan/allow-list.ts` | `DEFAULT_ALLOW_LIST`, `resolveAllowList()` |
|
||||
| S3-Quarantaene | `packages/storage/src/scan/s3-quarantine.ts` | `createS3StorageQuarantineAdapter()` |
|
||||
| Access-Control | `packages/storage/src/access/index.ts` | Storage-Zugriffspruefung |
|
||||
|
||||
**HiveGrid-Relevanz:** Datei-Uploads/Anhaenge (KB, CRM, Apps), DSGVO-EU-Storage via Scaleway-S3. Virus-Scan + magic-bytes-Pruefung = Sicherheits-Querschnitt fuer jedes Upload-Modul. Signed-URLs fuer direkten Client-Upload/Download.
|
||||
|
||||
---
|
||||
|
||||
## 6. `@toolctrl/realtime` — SSE/Realtime-Events
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/realtime` (keine Deps)
|
||||
**README:** `packages/realtime/README.md`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Event-Typen | `packages/realtime/src/events.ts` | `REALTIME_EVENT_NAMES` (notification.snapshot/update, keepalive, error), `RealtimeEvent`-Union, `validateRealtimeEvent()`, Notification-Stream-Item-Typen |
|
||||
| Server (SSE-Serialisierung) | `packages/realtime/src/server.ts` | `serializeRealtimeEvent()` (SSE `id/event/data`, retry), `serializeRealtimeComment()`, Newline-Sanitizing |
|
||||
| Client | `packages/realtime/src/client.ts` | Client-seitige Event-Verarbeitung |
|
||||
| Guards | `packages/realtime/src/guards.ts` | Type-Guards fuer Events |
|
||||
|
||||
**HiveGrid-Relevanz:** Live-Benachrichtigungen (In-App-Notifications) via SSE — kein WebSocket-Server, sondern SSE-Stream. Querschnitt "Realtime/Notifications". Hinweis: WebSocket im engeren Sinn ist hier **nicht** vorhanden; Realtime = SSE.
|
||||
|
||||
---
|
||||
|
||||
## 7. E-Mail-Stack
|
||||
|
||||
### 7.1 `@toolctrl/mail` — Provider + Templates
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/mail`
|
||||
**Deps:** `@react-email/components`, `@react-email/render`, `@toolctrl/brand`, `@toolctrl/queue`, `react`, `react-dom`
|
||||
**README:** `packages/mail/README.md`; Preview-Server: `packages/mail/scripts/preview-server.ts`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| MailerSend-Provider | `packages/mail/src/mailersend.ts` | `createMailerSendProvider()`/`...FromEnv()`, API `https://api.mailersend.com`, Timeout, `MailMetricsHook`, Templates/Personalization/Attachments/Tracking |
|
||||
| Queued-Mail-Provider | `packages/mail/src/queue.ts` | `createQueuedMailProvider()` — Versand via `@toolctrl/queue` (async) statt direkt |
|
||||
| Mail-Typen | `packages/mail/src/types.ts` | `MailProvider`, `SendMailInput`, `MailAddress`, `MailAttachment`, `MailProviderError` |
|
||||
| React-Email Render | `packages/mail/src/templates-react/render.ts` | `renderTransactionalEmail()`, `reactTransactionalTemplateNames`, Brand-Helfer |
|
||||
| Transaktionstemplates | `packages/mail/src/templates-react/transactional/` | Welcome, MagicLink, PasswordReset, Invitation, InvoiceSent, InvoiceTenant, SubscriptionSuccess/Failed, TenantNotification |
|
||||
| Layout-Primitives | `packages/mail/src/templates-react/_layout/` | BaseLayout, Header, Footer, Button (`assertSafeUrl`/`InvalidActionUrlError`), InfoBox, Eyebrow, theme |
|
||||
|
||||
### 7.2 `@toolctrl/email-templates` — Sequenz-Templates
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/email-templates`
|
||||
**Subpath-Exports:** `./sequences/{welcome,trial-reminder,re-activation,generic-step}`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Render + Theme | `packages/email-templates/src/render.ts`, `.../theme.ts` | React-Email Render-Layer |
|
||||
| Sequenz-Templates | `packages/email-templates/src/sequences/` | welcome, trial-reminder, re-activation, generic-step |
|
||||
|
||||
### 7.3 `@toolctrl/email-sequences` — Sequenz-Engine (reine Logik)
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/email-sequences` (keine Deps)
|
||||
**Subpath-Exports:** `.`, `./types`, `./engine`, `./step-runner`, `./conditions`, `./unsubscribe-token`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Engine | `packages/email-sequences/src/engine.ts` | `startSequenceRun()`/`advanceSequenceRun()` — Store + Queue injiziert (kein Prisma/BullMQ direkt); `SequenceRunStatus`, idempotent ueber `(sequenceId, triggerEventId)` |
|
||||
| Step-Runner | `packages/email-sequences/src/step-runner.ts` | `runStep()` — rendert + sendet einen Schritt |
|
||||
| Condition-DSL | `packages/email-sequences/src/conditions.ts` | `evaluateCondition()`/`evaluateAllConditions()`, `resolvePath()` |
|
||||
| Unsubscribe-Token | `packages/email-sequences/src/unsubscribe-token.ts` | `signUnsubscribeToken()`/`verifyUnsubscribeToken()`/`buildUnsubscribeUrl()`, Secret-Pflicht |
|
||||
|
||||
**Prisma:** `prisma/schema/emailSequences.prisma` — `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery`. `prisma/schema/email.prisma` (App-Email-Config).
|
||||
|
||||
**HiveGrid-Relevanz (7.x):** Transaktions-Mails (Auth, Billing, Notifications) + Marketing-/Lifecycle-Sequenzen (Onboarding, Trial-Reminder, Reaktivierung). EU-Provider MailerSend. Querschnitt "Kommunikation/E-Mail" fuer praktisch jedes HiveGrid-Modul; Sequenz-Engine direkt fuer "Marketing/Funnel/Lifecycle".
|
||||
|
||||
---
|
||||
|
||||
## 8. `@toolctrl/marketing-outbound` — Outbound-Webhook-Adapter
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/marketing-outbound` (keine Deps)
|
||||
**Subpath-Exports:** `./adapters/{slack,discord,mailchimp,hubspot,brevo,custom-webhook}`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Adapter-Interface + Registry | `packages/marketing-outbound/src/index.ts` | `adapterRegistry` (slack/discord/mailchimp/hubspot/brevo/webhook), `resolveAdapter(type)`, `ADAPTER_TYPES` |
|
||||
| Shared-Typen + SSRF-Guard | `packages/marketing-outbound/src/types.ts` | `MarketingOutboundAdapter<TConfig>` (`parseConfig`/`send`), `MarketingLeadPayload`/`MarketingLeadEventType` (captured/qualified/converted...), `adapterFetch()` (Timeout + SSRF-Allowlist, nur HTTPS, kein RFC1918/metadata), `maskEmailIfRequested()` (PII), `MarketingAdapterConfigError` |
|
||||
| Konkrete Adapter | `packages/marketing-outbound/src/adapters/*.ts` | je `buildXPayload()` + Adapter-Objekt (Slack-Blocks, Discord-Embed, Mailchimp/HubSpot/Brevo-Payloads, Custom-Webhook) |
|
||||
|
||||
**Prisma:** `prisma/schema/marketingLeads.prisma` — `MarketingIntegration` (type, configJson verschluesselt, `triggerEvents` String[], enabled, lastDeliveredAt/lastError), `Lead`, `LeadEvent`, `TenantAcquisition`.
|
||||
|
||||
**HiveGrid-Relevanz:** Lead-/Marketing-Integrationen mit Drittsystemen (CRM, Chat, ESP). Worker dispatcht Outbox-Events nach `MarketingIntegration.type`. SSRF-/PII-Schutz im Adapter. Direkt fuer HiveGrid-Module "Marketing/Funnel" und "Integrationen (Outbound-Webhooks)".
|
||||
|
||||
---
|
||||
|
||||
## 9. `@toolctrl/queue` — BullMQ + Idempotenz + Prioritaeten
|
||||
|
||||
**Pfad:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/queue`
|
||||
**Deps:** `bullmq`
|
||||
**Subpath-Exports:** `.`, `./runtime` (CJS `runtime.cjs`)
|
||||
**README:** `packages/queue/README.md`
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
|---|---|---|
|
||||
| Queue-Namen | `packages/queue/src/names.ts` | `queueNames`: `toolctrl.email`, `.notifications`, `.maintenance`, `.ai-chatbot`, `.browser-automation`, `.file-scan`, `.exports`, `.imports`, `.plugin-invoke`; `isQueueName()` |
|
||||
| Job-Payloads (typisiert) | `packages/queue/src/payloads.ts` | `AiJob` (`ai.chat-completion`/`ai.embedding`/`ai.browser-task`), `PluginInvokeJob` (`plugin.invoke`), `TransactionalMailJob`, `WebhookDeliveryJob`, `NotificationJob`, `CleanupJob`, `FileScanJob`, `ExportJob`/`ImportJob`, Workflow-Outbox-Events; `QueueJobPayloads`-Map |
|
||||
| Producer + Idempotenz | `packages/queue/src/producers.ts` | `enqueueJob()`, `build*Job()`-Builder, `buildIdempotentJobId()` (jobId/idempotencyKey/export-/importJobId/metadata.idempotencyKey), `buildRetryJobOptions()`, `buildIdempotentJobId`, `setEnqueueObserver()` |
|
||||
| Prioritaeten | `packages/queue/src/priority.ts` | `JOB_PRIORITY_{CRITICAL,HIGH,NORMAL,LOW}`, `resolveJobPriorityForTenant()` (Plan-basiert), `priorityFromPlan/Override`, `setTenantPlanLookup()` |
|
||||
| Redis-Connection | `packages/queue/src/connection.ts` | `parseRedisUrl()`, `resolveRedisConnectionOptions()`, `...FromProcessEnv()` |
|
||||
| Queue-Gruppen | `packages/queue/src/groups.ts` | `WORKER_QUEUE_GROUPS`, `getGroupForQueue()`, `getQueueNamesForGroup()` |
|
||||
| Runtime (BullMQ-Factory) | `packages/queue/src/runtime.ts` / `runtime.cjs` | `createQueue`/`createWorker`/`createQueueEvents` (typisiert) |
|
||||
|
||||
**Prisma:** `prisma/schema/queue.prisma` — `QueueFailedJob` (DLQ-Spiegel), `ExportJob` + `ExportJobStatus`-Enum. Outbox-Pattern: `prisma/schema/outbox.prisma`.
|
||||
|
||||
**HiveGrid-Relevanz:** Zentrale asynchrone Verarbeitung fuer KI-Jobs, Plugin-Invokes, Mail, Notifications, File-Scan, Exporte/Importe. **Idempotenz** ueber jobId/idempotencyKey + plan-basierte **Prioritaeten** = Querschnitt fuer alle HiveGrid-Worker-Module. AI/Plugin/Mail-Queues binden die obigen Pakete an den Worker an.
|
||||
|
||||
---
|
||||
|
||||
## Querschnitts-Konventionen (faktisch beobachtet)
|
||||
|
||||
- **Tenant-Isolation** ist ueberall am Seam verankert: `payload.tenantId`-Pflicht (vector-store), `searchForTenant`/`tenantId`-Filter (search, vector-store), `tenantId` Pflichtargument (embeddings), per-tenant Grants/Audit-Chain (plugin-runtime).
|
||||
- **Outbox-Pattern** fuer asynchrone Seiteneffekte: RAG-Reindex (`rag.index.*`), Such-Reindex, Plugin-Hooks (`plugin.hook.*`), AI-Cost (`ai.cost.event.persist`), Marketing-Dispatch — alle in DB-Transaktion committet, Worker fan-out.
|
||||
- **Kein direkter `process.env`-Zugriff** in den Paketen (Env-Snapshots vom Boundary) — Env-Access-Enforcement-Tests.
|
||||
- **Secret-/PII-Redaction** durchgaengig in Fehlern/Audit (ai/guards, ai/tools, ai/streaming, storage, marketing-outbound).
|
||||
- **Adapter-/Factory-Pattern** als roter Faden: `getAIProviderAdapter`, `createEmbeddingProvider`+Registry, `createVectorStore`+`resolveAdapter`, `createSearchClient`+`meiliFactory`, `adapterRegistry` (marketing), `createS3StorageAdapter`/`createLocalStorageAdapter`, Capability-`hostFns`-Map (plugin-runtime).
|
||||
- **Tests:** jedes Paket hat `*.test.ts` neben den Quellen; Eval-Harness in `packages/ai/test/evals` + Repo-Root `promptfoo.config.yaml`; CI/verify ueber `pnpm` Workspace-Scripts (`test`/`typecheck`/`build`), Repo-Root `package.json` + `lefthook.yml`.
|
||||
|
||||
## Wichtige Abgrenzungen / Luecken (faktisch)
|
||||
|
||||
- **WebSocket:** Es gibt **kein** WebSocket-Paket; Realtime laeuft ueber **SSE** (`@toolctrl/realtime`).
|
||||
- **Plugin-Capabilities in Prod:** Nur `log` + `audit` sind hostseitig verfuegbar (`PLUGIN_AVAILABLE_HOST_CAPABILITY_NAMES`); http/db/storage/secret/tenant.info sind deklarierbar, aber `productionAvailable: false` (Foundation).
|
||||
- **WASM-Fuel:** Keine echte Per-Instruktions-Meterung (V8-Limit) — Fuel wird pro Capability-Call/Invoke geladen; Wall-Clock-Timeout liegt beim Aufrufer.
|
||||
- **Anthropic-Embeddings:** Bewusster Stub/Platzhalter (`packages/ai/src/embeddings/providers/anthropic.ts`).
|
||||
- **Zwei "Apps-Engine"-Bedeutungen:** WASM-Plugin-System (`plugin-runtime`/`plugin-sdk`) vs. Data-Sync-Apps (`prisma/schema/appsEngine.prisma`, `App`/`DataConnection`/`AppSyncRun`) — beim Modul-Abgleich nicht verwechseln.
|
||||
@@ -0,0 +1,382 @@
|
||||
# Boilerplate-Inventur: UI-Layer & App-Shell
|
||||
|
||||
Faktische Bestandsaufnahme des Bereichs "UI-Layer & App-Shell" der Boilerplate
|
||||
(`/Users/raffaelsheikh/Documents/GitHub/boilerplate`). Stand: Read-only-Inventur,
|
||||
keine Aenderungen vorgenommen.
|
||||
|
||||
Inventarisierte Pakete/Pfade:
|
||||
`packages/ui`, `packages/ui-app`, `packages/ui-mock`, `packages/ui-subframe`,
|
||||
`packages/view-models` (Vertrags-Fundament), `apps/web`, `apps/storybook`.
|
||||
|
||||
## TL;DR — Reale Layer-Trennung
|
||||
|
||||
Die Layer-Trennung ist **noch nicht voll aktiviert**. Sie ist als bewusst
|
||||
strukturierte "Adapter-/Vertrags-Grenze" angelegt, waehrend die echten
|
||||
Laufzeit-Komponenten weiterhin in `apps/web/app/` leben.
|
||||
|
||||
- `@toolctrl/view-models` — reine TypeScript-Typen + kleine Helfer: View-Model-
|
||||
Statusmodell (`VMState`), Shell-Registry-Typen (Sidebar/Breadcrumb/Mobile/
|
||||
Portal), i18n-Key-Validierung. Kein React.
|
||||
- `@toolctrl/ui-app` — App-Shell-Registry-Factories + headless `AppShell`-Stub
|
||||
(rendert nur `data-*`-Attribute, kein echtes Layout). Konsumiert view-models.
|
||||
- `@toolctrl/ui-mock` — Fixture-/Mock-Generator fuer Hot-Swap- und Visual-Tests
|
||||
(erzeugt statisches HTML + serialisierbares Modul aus einem `MockPage`).
|
||||
- `@toolctrl/ui-subframe` — **leerer Platzhalter** (`createSubframePlaceholder()`
|
||||
liefert `{ status: "empty" }`). Subframe-Adapter ist reserviert, nicht gebaut.
|
||||
- `@toolctrl/ui` — **source-only Adapter-Metadaten** (keine React-Komponenten).
|
||||
Beschreibt nur stabile Namen + Verweise auf die echten Implementierungen in
|
||||
`apps/web/app/`.
|
||||
- `apps/web/app/` — echte Laufzeit: App-Shell (shadcn/Radix), Sidebar-Konfig,
|
||||
RR7-Routing, ~707 `.tsx`-Komponenten, Theme/Dark-Mode, i18n.
|
||||
- `apps/storybook` — Storybook 8 (react-vite) ueber die `packages/ui`-Stories.
|
||||
|
||||
Verbindung von Vertrag → echter Code laeuft ueber **stabile `data-ui-id`-IDs**
|
||||
(`packages/.../application/ui/uiRegistry.ts`) und die maschinenlesbare
|
||||
Inventur in `docs/ui-inventory/` (von Tests gegen das Dateisystem geprueft).
|
||||
|
||||
---
|
||||
|
||||
## Paket: `@toolctrl/view-models`
|
||||
|
||||
**Zweck:** Vertrags-Fundament fuer View-Model → UI. Reine Typen + winzige
|
||||
Validierungs-/Konstruktor-Helfer, ohne React-Abhaengigkeit. Bildet die
|
||||
gemeinsame Sprache, gegen die `ui-app`, `ui-mock` und die echte App komponieren.
|
||||
|
||||
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/src/index.ts`
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/package.json` (Name `@toolctrl/view-models`, Export `.` → `./src/index.ts`)
|
||||
|
||||
**Haupt-Exporte (Typen):**
|
||||
|
||||
| Export | Bedeutung |
|
||||
| --- | --- |
|
||||
| `VMStatus` | `"idle" \| "loading" \| "ready" \| "empty" \| "error"` |
|
||||
| `VMState<T>` | Diskriminierte Union ueber `VMStatus`; `error` traegt `{ messageKey; code? }` (i18n-Key, nicht Klartext) |
|
||||
| `ActionCallbacks<T>` | `onCreate/onUpdate/onDelete/onRefresh` — Standard-CRUD-Callback-Vertrag |
|
||||
| `I18nLabel` | `{ labelKey; descriptionKey? }` — UI-Labels sind **immer i18n-Keys** |
|
||||
| `RegistryGate` | `{ permission?; flag? }` — Sichtbarkeits-Gate (Permission/Feature-Flag) pro Registry-Item |
|
||||
| `SidebarRegistryItem` | `id/href/icon?/children?` + `I18nLabel` + `RegistryGate` |
|
||||
| `BreadcrumbRegistryItem` | `id/href?` + Label + Gate |
|
||||
| `MobileRegistryItem` | `id/href/priority?` + Label + Gate |
|
||||
| `PortalRegistryItem` | `id/slot/order?` + Label + Gate |
|
||||
| `ShellRegistries` | `{ sidebar?; breadcrumbs?; mobile?; portals? }` — das Shell-Konfig-Aggregat |
|
||||
|
||||
**Helfer-Funktionen:** `ready<T>(data)`, `empty<T>()`, `assertI18nLabel(label)`
|
||||
(erzwingt Regex `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$` fuer Label- und Description-Keys).
|
||||
|
||||
**HiveGrid-Relevanz:** Hoch und querschnittlich. Das `VMState`-Statusmodell und
|
||||
der i18n-Key-Zwang sind direkt uebernehmbar als Daten-/UI-Vertrag fuer alle
|
||||
HiveGrid-Module (Listen/Detail/Editoren), und die `ShellRegistries`-Typen sind
|
||||
die Grundlage fuer datengetriebene Navigation (App-Shell-Querschnitt).
|
||||
|
||||
---
|
||||
|
||||
## Paket: `@toolctrl/ui-app`
|
||||
|
||||
**Zweck:** App-Shell-Schicht. Liefert Registry-Factories (sortiert/normalisiert
|
||||
Sidebar/Breadcrumb/Mobile/Portal-Items) und einen headless `AppShell`-Stub.
|
||||
Der Stub rendert **kein** echtes Layout — nur ein `<div>` mit `data-ui-shell`
|
||||
und Zaehler-Attributen. Echte Shell lebt in `apps/web`.
|
||||
|
||||
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-app/src/index.ts`
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-app/package.json` (deps: `@toolctrl/view-models`, `react`; Test-Subpath-Exports fuer axe/a11y-Template)
|
||||
|
||||
**Haupt-Exporte:**
|
||||
|
||||
| Export | Art | Verhalten |
|
||||
| --- | --- | --- |
|
||||
| `AppShellProps` | Typ | `{ registries?: ShellRegistries; children? }` |
|
||||
| `createSidebarRegistry(items)` | fn | Kopie der Items |
|
||||
| `createBreadcrumbRegistry(items)` | fn | Kopie der Items |
|
||||
| `createMobileRegistry(items)` | fn | sortiert nach `priority` (default 100) |
|
||||
| `createPortalRegistry(items)` | fn | sortiert nach `order` (default 100) |
|
||||
| `createShellRegistries(input)` | fn | aggregiert + normalisiert alle 4 Registries |
|
||||
| `EmptyPage({ labelKey })` | Komponente | Empty-State-Stub (`data-page-state="empty"`) |
|
||||
| `AppShell({ registries, children })` | Komponente | headless Shell-Stub mit `data-*`-Zaehlern |
|
||||
|
||||
**a11y-Test-Vertrag:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-app/src/test-utils/a11y-template.ts`
|
||||
exportiert `generateA11yTest(Component, defaultProps, options)` — kanonisches
|
||||
axe-Test-Template (jede Komponente in `ui-app`/`ui-subframe` soll eine
|
||||
co-lokierte `<Name>.a11y.test.tsx` mitliefern). axe-Setup unter `test-setup/axe.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** App-Shell-/Navigations-Querschnitt. Die Registry-
|
||||
Factories sind die kanonische Art, HiveGrid-Sidebars/Breadcrumbs aus Daten zu
|
||||
bauen (mit Priority/Order-Sortierung und Permission/Flag-Gating). `generateA11yTest`
|
||||
ist als Compliance-/a11y-Querschnitt direkt nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## Paket: `@toolctrl/ui-mock`
|
||||
|
||||
**Zweck:** Hot-Swap-/Visual-Test-Fundament. Erzeugt aus einem deklarativen
|
||||
`MockPage`-Deskriptor deterministisch (a) ein serialisierbares JS-Modul und
|
||||
(b) statisches HTML inkl. eigenem Inline-CSS — als "Drop-in"-Ersatz fuer eine
|
||||
echte Seite. Liefert stabile Hashes/Metriken fuer Visual-Snapshots.
|
||||
|
||||
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-mock/src/index.ts`
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-mock/package.json` (dep: `@toolctrl/view-models`)
|
||||
**Visual-Baseline:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-mock/visual-baseline/`
|
||||
|
||||
**Haupt-Exporte:**
|
||||
|
||||
| Export | Art | Verhalten |
|
||||
| --- | --- | --- |
|
||||
| `MockPage<T>` | Typ | `{ id; route; title?/titleKey?; description?/descriptionKey?; state: VMState<T>; registries? }` |
|
||||
| `HotSwapDrillData` | Typ | `{ cards[]; activity[] }` — Demo-Datenform |
|
||||
| `MockVisualSnapshot` | Typ | `htmlHash/moduleHash/stateHash` (FNV-1a) + Byte-/Item-Metriken |
|
||||
| `MockArtifacts` | Typ | `{ module; html; snapshot }` |
|
||||
| `createMockPage(page)` | fn | Identitaet (Typ-Anker) |
|
||||
| `createMockRegistry(pages)` | fn | `Map<route, MockPage>` |
|
||||
| `generateHotSwapMock(page)` | fn | erzeugt `export const mockPage = ...` Modul-String |
|
||||
| `generateMockPageHtml(page)` | fn | volles statisches HTML (Sidebar/Breadcrumbs/Cards/Activity/State) |
|
||||
| `createVisualSnapshot(page, artifacts?)` | fn | Snapshot mit stabilen Hashes |
|
||||
| `generateMockArtifacts(page)` | fn | `{ module, html, snapshot }` in einem Schritt |
|
||||
| `createHotSwapDrillPage()` | fn | fertige Referenz-`MockPage` (`/mock/phase-c/hot-swap`) |
|
||||
|
||||
Enthaelt eine eingebaute Mini-Uebersetzungstabelle (`defaultMockTranslations`)
|
||||
fuer die Mock-Texte (i18n-Keys → Klartext, deterministisch).
|
||||
|
||||
**HiveGrid-Relevanz:** Test-/QA-Querschnitt. Das Mock-Drop-in-Muster (deklarativer
|
||||
Deskriptor → deterministisches HTML + Hash) ist als Vorlage fuer HiveGrid-Visual-
|
||||
Regression und fuer das Bauen von Hot-Swap-/Whitelabel-Vorschauen verwendbar.
|
||||
|
||||
---
|
||||
|
||||
## Paket: `@toolctrl/ui-subframe`
|
||||
|
||||
**Zweck:** **Reservierte, leere** Paket-Grenze fuer kuenftige Subframe-generierte
|
||||
UI. Bewusst leer, bis ein spaeterer Slice Import-Regeln + Review-Gates definiert.
|
||||
|
||||
**Zentrale Datei:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-subframe/src/index.ts`
|
||||
- `uiSubframeRegistry = [] as const`
|
||||
- `createSubframePlaceholder()` → `{ status: "empty" }`
|
||||
|
||||
**README:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui-subframe/README.md`
|
||||
("Reserved package boundary for future Subframe-generated UI imports. Exports an empty registry.")
|
||||
|
||||
**HiveGrid-Relevanz:** Niedrig (Stub). Relevant nur als Marker dafuer, dass der
|
||||
Subframe-Adapter-Layer der Boilerplate **nicht gebaut** ist — siehe `MEMORY.md`
|
||||
("Subframe mandatory for all routes"). HiveGrid muesste diese Grenze selbst fuellen.
|
||||
|
||||
---
|
||||
|
||||
## Paket: `@toolctrl/ui`
|
||||
|
||||
**Zweck:** Source-only **Adapter-Metadaten** ("category migration boundary").
|
||||
Enthaelt **keine** React-Komponenten und importiert React nicht. Beschreibt
|
||||
stabile Namen pro Kategorie und zeigt per `source`-Feld auf die echten
|
||||
Implementierungen in `apps/web/app/`. Erlaubt Agenten/Tools, stabile Namen
|
||||
anzusprechen, bevor Laufzeit-Imports migriert sind.
|
||||
|
||||
**README:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui/README.md`
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui/package.json`
|
||||
**Migration-Doku:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/ui/docs/migration.md`
|
||||
|
||||
**Subpath-Exporte (Kategorien):** `.`, `./buttons`, `./inputs`, `./dialogs`,
|
||||
`./tables`, `./layout`, `./navigation`, `./feedback`.
|
||||
|
||||
**Zentrale Dateien:**
|
||||
|
||||
| Datei | Inhalt |
|
||||
| --- | --- |
|
||||
| `src/index.ts` | Re-Exporte aller Kategorien |
|
||||
| `src/types.ts` | `uiAdapterCategories`, `UiAdapterDefinition`, `UiAdapterLifecycle` (`placeholder/available/deprecated`), `createEmptyAdapterRegistry`, `isUiAdapterCategory` |
|
||||
| `src/navigation.ts` | `navigationAdapters` (status `available`): `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, `SidebarPrimitives` — mit `source`-Pfaden in `apps/web/app/...` |
|
||||
| `src/layout.ts` | `layoutAdapters`: `ShadcnSidebarLayout`, `UiRegistry` |
|
||||
| `src/buttons.ts` | `buttonAdapters` (`Button`, `buttonVariants`) |
|
||||
| `src/inputs.ts`, `dialogs.ts`, `tables.ts`, `feedback.ts` | derzeit leere Readonly-Registries (Placeholder bis Migrations-Phase) |
|
||||
| `src/stories/*.stories.tsx` | ~21 Storybook-Stories (Button, Input, Select, Dialog, DataTable, Table, Tabs, Toast, Tooltip, Popover, Card, Badge, Avatar, Checkbox, Radio, Switch, Textarea, Form, EmptyState, LoadingState, Sidebar) ueber `_demo-primitives.tsx` |
|
||||
|
||||
Alle `source`-Pfade aus `navigation.ts`/`layout.ts` (absolut):
|
||||
`/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/application/sidebar/AppSidebar.tsx`,
|
||||
`.../AdminSidebar.tsx`, `.../DocsSidebar.ts`,
|
||||
`.../components/layouts/sidebars/shadcn/nav-main.tsx`, `nav-secondary.tsx`,
|
||||
`nav-quick-links.tsx`, `nav-actions.tsx`,
|
||||
`.../components/ui/sidebar.tsx`,
|
||||
`.../components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx`,
|
||||
`.../application/ui/uiRegistry.ts`.
|
||||
|
||||
**HiveGrid-Relevanz:** Konventions-Querschnitt. Liefert die Taxonomie
|
||||
(buttons/inputs/dialogs/tables/layout/navigation/feedback) und das Lifecycle-
|
||||
Modell, an dem sich eine HiveGrid-Komponentenbibliothek ausrichten kann. Faktisch
|
||||
ist es jedoch nur Metadaten — die echten Komponenten liegen in `apps/web`.
|
||||
|
||||
---
|
||||
|
||||
## App: `apps/web` — echte App-Shell, Sidebar-Konfig, Routing
|
||||
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/package.json`
|
||||
**Stack:** React Router 7 (RR7), Vite, Tailwind v4, shadcn/Radix. SaasRock-aehnliche Struktur.
|
||||
|
||||
### App-Shell / Layout
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| `AppLayout` | `apps/web/app/components/app/AppLayout.tsx` | Einstieg: `SkipToContent` + `CommandPalette` + `ShadcnSidebarLayout`; Prop `layout: "app" \| "admin" \| "docs"` |
|
||||
| `ShadcnSidebarLayout` | `apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx` | Authentifizierte Shell: `SidebarProvider` → `ShadcnAppSidebar` + `SidebarInset` (Header mit Breadcrumb/`SidebarTrigger`/`NavActions`, `<main id="main-content">`). Liest Tenant-`themeConfig` + Dark-Mode → injiziert `--sidebar*` CSS-Variablen. |
|
||||
| `ShadcnAppSidebar` | `apps/web/app/components/layouts/sidebars/shadcn/app-sidebar.tsx` | Waehlt je `layout` die Menue-Quelle: `AppSidebar`/`AdminSidebar`/`DocsSidebar`; wendet Permission-/Sichtbarkeits-Filter (`getVisibleItem`) + Active-State an; rendert `NavMain`/`NavSecondary` |
|
||||
| `NavMain` | `.../shadcn/nav-main.tsx` | Rendert `SidebarGroupDto[]` → shadcn `SidebarMenu` mit collapsible Untermenues; setzt `data-ui-id`-Attribute via `getUiIdAttributes` |
|
||||
| weitere Nav | `.../shadcn/nav-secondary.tsx`, `nav-quick-links.tsx`, `nav-actions.tsx`, `nav-user.tsx`, `team-switcher.tsx` | Sekundaer-Nav, Quick-Links, Header-Aktionen (Search/AI/Notifications/Feedback), User-/Team-Switcher |
|
||||
|
||||
### Sidebar-Konfiguration (datengetrieben)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| `SideBarItem` (Interface) | `apps/web/app/application/sidebar/SidebarItem.ts` | Item-Vertrag: `id/title/path/icon/items/permission/adminOnly/tenantUserTypes/isCollapsible/isSecondary/isQuickLink/redirectTo/uiIdPattern/uiIdParams/...` |
|
||||
| `SidebarGroupDto` | `apps/web/app/application/sidebar/SidebarGroupDto.ts` | `{ id?; items: SideBarItem[]; title?; type?: "main"\|"secondary"\|"quick-link" }` |
|
||||
| `AppSidebar(props)` | `apps/web/app/application/sidebar/AppSidebar.tsx` | Baut Tenant-App-Menue dynamisch aus `entities`, `entityGroups`, `productAccess` (Feature-Gating: crm-basic, email-marketing, workflow-engine, api, ai-credits); host-aware Pfade via `appPath`/`tenantPath` |
|
||||
| `AdminSidebar(props)` | `apps/web/app/application/sidebar/AdminSidebar.tsx` | Statisches Admin-Menue in Segmenten Manage/Build/Market/Settings; Permission-getaggt; Plugin-Routen via `enabledAdminRouteItem`/`disabledPluginRouteSlugs` ausblendbar |
|
||||
| `DocsSidebar()` | `apps/web/app/application/sidebar/DocsSidebar.ts` | Statischer Docs-Baum; vergibt stabile `ui.nav.docs.*`-IDs (`withDocsSidebarIds`) |
|
||||
|
||||
### UI-Registry (stabile IDs / data-ui-id)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| `uiRegistry.ts` | `apps/web/app/application/ui/uiRegistry.ts` | Single source of truth fuer stabile UI-IDs: `UI_SURFACE_IDS`, `UI_ACTION_IDS`, `UI_NAV_IDS`, `UI_ID_PATTERNS`; Helfer `getSidebarSurfaceId(layout)`, `uiIdSegment(value)`, `getUiIdAttributes(item)` (erzeugt `data-ui-id` / `-pattern` / `-param-*`) |
|
||||
|
||||
### RR7-Routing-Konvention (`app/routes`)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| Route-Manifest | `apps/web/app/routes.ts` | Nutzt **Remix-v1-Flat-Folder-Convention** ueber `remixConfigRoutes` + `createRoutesFromFolders` (NICHT die RR7-Default-Convention). Definiert `defaultIgnoredRouteFilePatterns` (`*.test.*`, `*.server.*`, `*.css`, dotfiles) und `defaultDisabledPluginRouteFilePatterns` (deaktivierbare Plugin-Routen) |
|
||||
| Convention-Impl | `apps/web/app/utils/compat/v1-route-convention.ts` | Kopie von `remix-run/v1-compat-utils`; Param-Prefix `$`, Escape `[ ]`, Optional `( )`, Module-Exts `.js/.jsx/.ts/.tsx/.md/.mdx` |
|
||||
| `react-router.config.ts` | `apps/web/react-router.config.ts` | RR7-App-Config |
|
||||
| Routen-Tests | `apps/web/app/routes.test.ts`, `apps/web/app/utils/compat/v1-route-convention.test.ts` | Verifizieren das Manifest |
|
||||
|
||||
**Routen-Topologie (Auszug, `apps/web/app/routes/`, ~102 Eintraege):**
|
||||
- Tenant-Space: `app.$tenant.tsx` (Layout) + `app.$tenant/` (dashboard, crm, email-marketing, notifications, settings, forms, g.$group, sites, internal, __portals, __widgets, __workflows, $entity.__autogenerated).
|
||||
- Admin-Space: `admin.tsx` + `admin/` (accounts, analytics, entities, workflow-engine, api, feature-flags, navigation, portals, prompts, email-marketing, marketing-leads, knowledge-base, help-desk, onboarding, metrics, settings, audit-trails, events).
|
||||
- Docs: `docs/`. Auth: `auth.*`, `forgot-password.*`, `login`-Flows. Fehlerseiten: `401/403/404/500/$`.
|
||||
- Hot-Swap-Demo (dev-only): `apps/web/app/routes/hot-swap-demo.tsx`.
|
||||
|
||||
Shell-Verdrahtung: `app.$tenant.tsx` wrappt Tenant-Routen ueber
|
||||
`<AppLayout layout="app">`; `app-sidebar.tsx` zieht die Menue-Daten ueber
|
||||
`useAppOrAdminData()` (RR7 Loader-Daten) und ruft die passende Sidebar-Factory.
|
||||
|
||||
### Theme / Dark-Mode
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| `root.tsx` | `apps/web/app/root.tsx` | Setzt `dark`-Klasse aus `userSession.lightOrDarkMode` (gated ueber `DARK_MODE_IN_APP`), `theme-${rootData.theme}` (+ `-scaled`); Actions `toggleLightOrDarkMode`, `setTheme`, `setLocale` (Persistenz in User-Session/DB) |
|
||||
| `themes.css` | `apps/web/app/themes.css` (86 KB) | Vordefinierte Themes als CSS-Variablen |
|
||||
| `globals.css` | `apps/web/app/globals.css` | Globale Tokens/Tailwind-Base |
|
||||
| `Theme`-Enum | `apps/web/app/application/enums/shared/Theme.ts` | `LIGHT \| DARK` |
|
||||
| Theme-Preview-Store | `apps/web/app/stores/themePreviewStore.ts` (via `useThemePreviewStore`) | Live-Preview-Override im Shell-Layout |
|
||||
| `parseThemeConfig` / `ThemeConfig` | `apps/web/app/utils/theme/ThemeConfig.ts` | Parst Tenant-`themeConfig` (Farben inkl. `darkColors`, `sidebar*`-Farben) |
|
||||
| `tailwind.config.ts` | `boilerplate/tailwind.config.ts` (Repo-Root) | Tailwind-Setup |
|
||||
|
||||
**Prisma-Bezug (Theme/Shell-State):**
|
||||
- `prisma/schema/accounts.prisma:17` — `User.lightOrDarkMode String?` (Hell/Dunkel-Praeferenz pro User).
|
||||
- `prisma/schema/accounts.prisma:188` — `Tenant.themeConfig String?` (Per-Tenant-Whitelabel-Theme als serialisierter JSON-String).
|
||||
- `prisma/schema/portals.prisma` — `Portal`, `PortalPage`, ... (Portal-Feature; Bezug zu `PortalRegistryItem`/Admin-Portals-Nav).
|
||||
|
||||
### i18n in der UI
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| Web-i18n-Setup | `apps/web/app/locale/` (`i18n.ts`, `i18next.server.ts`, `i18next.global.server.ts`, `format.ts`, `date-fns.ts`) | i18next + RR7 SSR-Integration |
|
||||
| Locale-Daten | `apps/web/public/locales/{de,en}/*.json` | Namespaces: `translations` (legacy Bulk), `common`, `errors`, `mail`, `settings`, `billing`, `crm`, `auth`, `emailMarketing` |
|
||||
| Shared-Paket | `packages/i18n/src/index.ts` (`@toolctrl/i18n`) | `defaultLocale="de"`, `supportedLocales=["de","en"]`, `i18nNamespaces`, `i18nConfig`, `getDirection`/`isRTL` (RTL-Support vorbereitet), Re-Exporte `formatNumber/Currency/Date/RelativeTime/List`, `formatIcu`, `createUseTranslate` |
|
||||
|
||||
Sidebars/Registries verwenden durchgaengig i18n-Keys (`t(...)` bzw. `labelKey`),
|
||||
nie Klartext — `assertI18nLabel` (view-models) erzwingt das auf Vertragsebene.
|
||||
|
||||
### Komponenten-/Page-Bibliothek (real, in `apps/web`)
|
||||
|
||||
Insgesamt ~707 `.tsx`-Komponenten (ohne `*.test.tsx`/`*.stories.tsx`) unter
|
||||
`apps/web/app/components/`. Verzeichnis-Highlights:
|
||||
|
||||
| Bereich | Pfad | Inhalt (Auszug) |
|
||||
| --- | --- | --- |
|
||||
| Primitives (shadcn/Radix) | `apps/web/app/components/ui/` | `button.tsx`, `input.tsx`, `select.tsx`, `dialog.tsx`, `sheet.tsx`, `drawer.tsx`, `popover.tsx`, `table.tsx`, `tabs.tsx`, `form.tsx`, `sidebar.tsx`, `command.tsx`, `toast.tsx`/`sonner.tsx`, `badge.tsx`, `card.tsx`, `calendar.tsx`, `chart.tsx`, `multi-select.tsx`, `stepper.tsx`, `pagination.tsx`, ... |
|
||||
| Tabellen | `apps/web/app/components/ui/tables/` | `TableSimple.tsx`, `TableNew.tsx`, `TablePagination.tsx`, `GridPagination.tsx`, `ColumnSelector.tsx`, `CollapsibleRow.tsx`, `RowsLoadMoreCard.tsx`, `PreviewTableSimple.tsx` |
|
||||
| Formulare | `apps/web/app/components/ui/forms/`, `.../input`, `.../selectors`, `.../editors` | `FormGroup.tsx`, `InputGroup.tsx` + reichhaltige Input-/Selector-/Editor-Komponenten |
|
||||
| Modale/Dialoge | `apps/web/app/components/ui/modals/`, `.../slideOvers` | `Modal.tsx`, `ModalOrSlide.tsx`, `ConfirmDialog.tsx`, `ConfirmModal.tsx`, `ActionResultModal.tsx`, `ErrorModal.tsx`, `SuccessModal.tsx`, `OpenModal.tsx`, ... |
|
||||
| Empty/Loading | `apps/web/app/components/ui/emptyState`, `.../loaders` | Empty-/Loading-States |
|
||||
| Command-Palette | `apps/web/app/components/ui/commandPalettes/CommandPalette` | Kommando-Palette (im Shell verdrahtet) |
|
||||
| Entitaeten/Editoren | `apps/web/app/components/entities`, `.../editors`, `.../json`, `.../pdf` | Entity-Builder-UI, Rich-Editoren, JSON-/PDF-Viewer |
|
||||
| Weitere | `aceternity`, `ai-elements`, `analytics`, `audit`, `brand`, `cookies`, `dashboard`, `images`, `motion-primitives`, `notifications`, `pages`, `public`, `recaptcha` | App-spezifische Komponenten-Cluster |
|
||||
|
||||
### Hot-Swap-Aktivierung (Drop-in, real verdrahtet)
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| Renderer | `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx` | Bruecke: `MockPage`-Deskriptor (`@toolctrl/ui-mock`) → RR7-JSX, nutzt `createShellRegistries()` aus `@toolctrl/ui-app` |
|
||||
| Demo-Route | `apps/web/app/routes/hot-swap-demo.tsx` | Rendert `createHotSwapDrillPage()`; gated auf `NODE_ENV !== "production"` |
|
||||
| Renderer-Test | `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.test.tsx` | Prueft Deskriptor → DOM (Sidebar/Breadcrumbs/Header/Cards/Activity) |
|
||||
|
||||
**HiveGrid-Relevanz (apps/web gesamt):** Sehr hoch. Dies ist der reale,
|
||||
sofort wiederverwendbare Fundus: vollstaendige authentifizierte App-Shell
|
||||
(App/Admin/Docs), datengetriebene Sidebar mit Permission-/Feature-Gating,
|
||||
RR7-Flat-Folder-Routing inkl. Tenant- (`app.$tenant`) und Admin-Trennung,
|
||||
Theme/Dark-Mode mit Per-Tenant-Whitelabel (`Tenant.themeConfig`), i18n (de/en),
|
||||
und eine breite shadcn/Radix-Komponentenbibliothek (Tabellen/Forms/Modale).
|
||||
Querschnittlich relevant fuer praktisch jedes HiveGrid-Modul.
|
||||
|
||||
---
|
||||
|
||||
## App: `apps/storybook`
|
||||
|
||||
**Zweck:** Storybook-8-Workbench + Visual-Regression (lost-pixel) + a11y-Addon.
|
||||
|
||||
**package.json:** `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/storybook/package.json`
|
||||
(`@storybook/react-vite` 8.6, Addons: essentials/a11y/interactions/themes; `lost-pixel` 3.22; dep `@toolctrl/i18n`)
|
||||
|
||||
**Zentrale Dateien:**
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| Storybook-Config | `apps/storybook/.storybook/main.ts` | Stories aus `apps/storybook/src/**` **und** `packages/{ui,ui-app,ui-subframe,ui-mock}/src/**/*.stories.*`; Tailwind-v4-Vite-Plugin; Alias `~` → `apps/web/app` |
|
||||
| i18n-Bootstrap | `apps/storybook/.storybook/i18n.ts`, `preview.tsx`, `preview.css` | i18next + Theme-Decorator in Preview |
|
||||
| Lost-Pixel | `apps/storybook/lostpixel.config.ts`, `.lostpixel/` | Visual-Regression-Config + Baselines |
|
||||
| Test-Runner | `apps/storybook/.storybook/test-runner.ts` | `axe-playwright`-basierte a11y-Checks im Test-Runner |
|
||||
| Docs (MDX) | `apps/storybook/src/Introduction.mdx`, `src/ThemeGuide.mdx` | Einfuehrung + Theme-Guide |
|
||||
| Scripts | `package.json` | `storybook` (dev :6006), `build-storybook`, `test:storybook`, `visual-regression`(:update) |
|
||||
|
||||
**Status:** Stories sind aktuell (~21) groesstenteils inline-styled Demos ueber
|
||||
`packages/ui/src/stories/_demo-primitives.tsx` (CSS-Variablen-Tokens aus
|
||||
`preview.css`); der "echte Tailwind-v4-Pipeline"-Pfad ist im `main.ts` als
|
||||
Migrations-Vorbereitung schon vorhanden (Tailwind-Plugin no-op fuer heutige Stories).
|
||||
|
||||
**HiveGrid-Relevanz:** QA-/Design-Querschnitt. Direkt nutzbar als Visual-
|
||||
Regression- und a11y-Gate fuer eine HiveGrid-Komponentenbibliothek; der Alias
|
||||
auf `apps/web/app` erlaubt, echte App-Komponenten in Stories zu ziehen.
|
||||
|
||||
---
|
||||
|
||||
## Maschinenlesbare UI-Inventur & Verifikations-Gates
|
||||
|
||||
Verbindet Vertrag ↔ echte Komponenten und wird von der Test-Suite geprueft.
|
||||
|
||||
| Asset | Pfad | Was |
|
||||
| --- | --- | --- |
|
||||
| Komponenten-Inventur | `docs/ui-inventory/components.json` | 71 Eintraege (`stableName`/`path`/`category`/`library`/`status`); Schema `docs/ui-inventory/schema.json` |
|
||||
| Surface-Map | `docs/ui-inventory/surfaces.json` (+ `surfaces.schema.json`, `surface-map.md`) | Mapping stabiler `data-ui-id` → Quelldateien/Renderer |
|
||||
| Inventur-Test | `apps/web/app/application/ui/uiInventory.test.ts` | Prueft, dass Inventur-Pfade existieren, alle `components/ui/*.tsx`-Primitives gelistet sind und Registry-IDs in der Surface-Map stehen |
|
||||
| Adapter-Test | `apps/web/app/application/ui/uiAdapters.test.ts`, `uiRegistry.test.ts` | Prueft `@toolctrl/ui`-Adapter ↔ App-Registry-Konsistenz |
|
||||
| Hot-Swap-Status | `docs/ui-inventory/hot-swap-status.md` | Dokumentiert, was verdrahtet ist (`ui-app`/`ui-mock` aktiv, `ui-subframe` Platzhalter) + Aktivierungs-Checkliste |
|
||||
| Boundary-Gate | `scripts/verify-phase-c-boundaries.mjs` (npm `verify:phase-c-boundaries`) | Erzwingt, dass Aktivierung keine Laufzeit-Layer-Grenze verletzt |
|
||||
| Hot-Swap-Verify | `scripts/verify-ui-hot-swap.ts` (npm `verify:ui-hot-swap`, `test:hot-swap`) | Mock-getriebener Hot-Swap-Drill |
|
||||
| Visual-Verify | `scripts/verify-ui-mock-visual.ts` (npm `verify:ui-visual`) | Mock-Visual-Baseline |
|
||||
|
||||
**HiveGrid-Relevanz:** Governance-/Konventions-Querschnitt. Das Muster
|
||||
"stabile ID-Registry + maschinenlesbare Inventur + dateisystem-geprueftes Gate"
|
||||
ist direkt als HiveGrid-UI-Governance uebertragbar (Whitelabel/Hot-Swap-Faehigkeit
|
||||
mit hartem CI-Schutz der Layer-Grenzen).
|
||||
|
||||
---
|
||||
|
||||
## Wichtige Vorbehalte (Anti-Erfindung)
|
||||
|
||||
- `@toolctrl/ui` enthaelt **keine** lauffaehigen Komponenten — nur Adapter-Metadaten,
|
||||
die auf `apps/web/app/...` verweisen. Echte Primitives = `apps/web/app/components/ui/*`.
|
||||
- `@toolctrl/ui-subframe` ist **leer** (Placeholder). Es gibt **keinen** gebauten
|
||||
Subframe-Adapter-Layer in der Boilerplate.
|
||||
- Der `AppShell` in `@toolctrl/ui-app` ist ein **headless Stub** (nur `data-*`),
|
||||
nicht die echte sichtbare Shell. Sichtbare Shell = `ShadcnSidebarLayout`.
|
||||
- Hot-Swap ist **nur** an der dev-only Demo-Route (`hot-swap-demo.tsx`) end-to-end
|
||||
aktiv; Produktiv-Routen rendern weiterhin direkt aus `apps/web/app/components/`.
|
||||
- Routing nutzt die **Remix-v1-Flat-Folder-Convention** (Compat-Layer), nicht die
|
||||
RR7-Default-`routes.ts`-Convention.
|
||||
- Es gibt **keine** Prisma-Modelle, die exklusiv zu den UI-Paketen gehoeren;
|
||||
UI-relevant sind `User.lightOrDarkMode` und `Tenant.themeConfig` (accounts.prisma)
|
||||
sowie `Portal*` (portals.prisma).
|
||||
Reference in new issue
Block a user