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 ohneOTEL_EXPORTER_OTLP_ENDPOINT) undsrc/sentry.ts(self-disable ohne DSN). - Build via
node scripts/build.mjspro App; OTel-Datei steht inpackage.jsonsideEffects.
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 inapp.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 mitSTRIPE_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*(Gruppemail),email-sequence-*(Gruppemail,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*(Gruppeplugin, WASM-Sandbox, prod-gatedPLUGIN_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.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 diverseverify:*-docs(-baseline)undverify:*-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 unterprisma/schema/und gehoeren zum@toolctrl/db-Paket (anderer Inventur-Bereich). apps/webundapps/storybooksind hier bewusst nicht inventarisiert (gehoeren zu Web-/UI-Bereichen), werden aber referenziert: Mobile laedtapps/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-Listingapps/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 wurdeverify-phase-c-boundaries.mjs.