367 lines
27 KiB
Markdown
367 lines
27 KiB
Markdown
# 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`)
|
|
</content>
|