# 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./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()`; 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_`. | | Connection | `apps/worker/src/connection.ts` | `createWorkerConnection(group)` — ioredis-Verbindung getaggt `worker--`. | | 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`.