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

27 KiB

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.