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

27 KiB

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)