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 inapps/web/app/modules/*und Worker-Jobs.Konvention im gesamten Repo: Pakete heissen
@toolctrl/<name>, sindprivate: true,type: module, ESM-only,exportszeigen direkt auf./src/*.ts(kein Build-Output); Build =pnpm run typecheck. Tests viavitest run src. Prisma-Schema ist per-Domain aufgesplittet unterprisma/schema/*.prisma. DB-spezifische Service-Logik liegt in*.db.server.ts/*.server.tsDateien 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 (versioniertesdefinitionJSON,theme,targetType,targetEntityId,fieldMapping,allowedOrigins[],notifyEmails[],webhookUrl,config,keyfuer<script data-form-key>).FormSubmission— Inbox fuer Payloads (payloadJSON,sourceOrigin,ipHash= SHA-256, kein Raw-IP,status: received/processed/failed/spam,resultJSON).
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 (statusenumImportJobStatus: 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 mituserIdviaUSER_FK_MAP(packages/db/src/dsgvo/user-fk-map.ts), serialisiert als JSON-Bundle, streamt zu S3, mintet Signed-URL, schreibtAuditEventaction=EXPORT_PERSONAL_DATA (regulatoryScope gdpr, dataSensitivity pii). Prisma: Export-Jobs-Migrationprisma/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 ausBRAND_*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, TypenToolctrlClient/ClientConfig/AuthConfig/RetryConfig/IdempotencyConfig,PaginatedResponse,PaginateOptions(src/client.ts).verifyWebhookSignature,signWebhookPayload,VerifyWebhookOptions,SignWebhookOptions(src/webhooks.ts).- Subpfade:
./client,./webhooks,./types(generiertetypes.gen.ts),./generated. - OpenAPI-Spec:
packages/api-client-ts/openapi.json; Spec-Generator-Scriptsscripts/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-Version2025-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 nurcrm-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 defaultopen, priority defaultnormal, subject, message, fromEmail, fromUrl,inboundMessageIdunique 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 +ownerKeydefaultglobal, basePath, slug, multi-languagelanguages, layout, color, enabled, SEO).KnowledgeBaseCategory->KnowledgeBaseCategorySection— Hierarchie.KnowledgeBaseArticle— Draft + Published Content (contentDraft,contentPublished,contentPublishedAsTextfuer 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); DTOsdtos/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),statusenumLeadStatus(new/contacted/qualified/trial/customer/churned/disqualified),score,notesJSON,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,configJsonmit 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. TypenMarketingOutboundAdapter,MarketingLeadPayload,MarketingLeadEventType(src/types.ts).
Service-/Worker-Layer:
apps/web/app/utils/leads/...(Capture-/Admin-Logik), public Endpoint/api/leads/capture+marketing.jsSDK (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}undapps/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)