Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/PROJECT.md
T

12 KiB
Raw Blame History

HiveGrid 2.0

What This Is

HiveGrid 2.0 ist eine Multi-Tenant-SaaS-Plattform für SHK-Handwerksbetriebe (Sanitär, Heizung, Klima). Sie bündelt CRM, Projekt-/Pipeline-Arbeit, Team-Chat, visuelle Automation und die Anbindung an das KWP-ERP in einem EU-gehosteten System. Externe KI-Clients können später über die Remote-MCP-Surfaces andocken; HiveGrid hostet nach AD-26 keine eigene Inferenz.

HiveGrid ist ein Multi-Kunden-SaaS für den gesamten SHK-Markt. Die Geerkens GmbH (Kontakt: Noah) ist erster Kunde und Investor — Validierungspartner, nicht alleiniger Zweck. Das Produkt ersetzt dort HubSpot (CRM + Sales-Pipeline), Quiply (Team-Chat), Zapier/n8n (Automation) sowie mehrere Excel-Prozesse. Die Codebase wird als bespoke HiveGrid-Anwendung weitergeführt: historisches Fundament wird genutzt, produktfremde Altlasten werden entfernt.

🔴 MODELL-PIVOT (2026-06-13): CRM/Pipeline-Modell ist Projekt-zentrisch — ein Projekt-Kern, Pipelines = frei konfigurierbare Views; „Deal"/„Auftrag" sind Pipeline-Typen, keine eigenen Entitäten. Single Source: .planning/ENTITY-MODEL.md. Entity Model, Requirements, Screen-Map und Ticket-Docs wurden gegen diesen Anker neu gefasst.

Core Value

Jeder SHK-Betrieb (Mandant) wickelt die komplette Wertschöpfungskette — Lead → Projekt (frei konfigurierbare Pipelines: Sales/Auftrag/…) → KWP-Sync (ab v2) — inklusive visueller Automation in einem einzigen, DSGVO-konformen EU-System ab. Der initiale KWP-Scope liest KWP-Daten nach HiveGrid; Writeback folgt erst nach belastbarem Providervertrag und erneuter Freigabe gemäß AD-32/CR-003. Wenn diese Kette nicht durchgängig funktioniert, scheitert das Produkt.

Requirements

Vollständige Requirements stehen in .planning/REQUIREMENTS.md. Ausführbare Acceptance-Kriterien und DoD stehen ausschließlich in den self-contained Ticket-Docs unter .planning/ticket-docs/.

Validated

(Noch keine — Big-Bang-Launch ohne phasiertes Produktiv-Go-Live, AD-19. Validierung erfolgt pro Modul über Noah/Geerkens via UAT-Klick-Pfad der Ticket-Doc.)

Active

USP-Säulen (aktuell nach AD-26):

  • Automation-Engine (M17) — visueller Editor, alle Trigger/Aktionen, 24h-Undo, Guards
  • Remote-MCP-Surfaces (VR-MCP/VD-MCP, v2) — permission-aware Produktzugriff für externe KI-Clients; keine eigene Inferenz
  • KWP-Integration (M19) — initial read-only KWP → HiveGrid; Writeback provider-gegatet und nach VEXT-6 geparkt (AD-32/CR-003)

SHK-Kernpfad (AD-11, Projekt-zentrisch nach AD-20):

  • CRM/Kontakt-Kern (M01), Lead-Inbox/LeadInput (M02), Projekt & Pipelines (vormals Sales M03 + Auftrag M04 → ein Projekt-Kern + konfigurierbare Pipeline-Views; Abnahme bleibt v1 als Checklisten-Sub-Area, Rechnung = Sub-Entity v1)

Fundament-Kern:

  • Auth/Multi-Tenancy (M27), Apps-Engine/Adapter (M33a), Audit-Log (M21), Notifications (M22), i18n (M30), Feature-Flags (M32), Plattform-Admin (M37)

Breite (AD-13):

  • HR-Hub (M14), Customer-Portal (M15), Email (M09/M10), Telefonie (M12), Team-Chat (M13), Booking/Forms/Angebot (M05/M06/M07), Files/Suche/Calendar/Tasks (M23/M24/M25/M26), Billing (M28), Onboarding (M29), Branding (M31), Dashboard (M20), Public-API (M34), DSGVO-Export (M35), Mobile-PWA (M36 — PWA-only, kein nativer Client), Help-Center/Desk (M38/M39)

Out of Scope

  • Phase-2-Module (z.B. M11 WhatsApp) — nicht spec'd, späterer Release; von M13 referenziert, aber nicht im Ingest-Set
  • Konkrete Pricing-Stufen — grundsätzlich weiter geparkt (AD-15). Ausnahme AD-30/CR-001: Starter/Team zahlen 19,99 EUR netto/Monat für das Customer-Portal; Business und Enterprise enthalten es. Die Custom-Portal-Domain kostet Starter/Team/Business 299,99 EUR netto je Einrichtung; Enterprise enthält eine Domain. Ein Domainwechsel ist eine neue Einrichtung, sofern keine individuelle Enterprise-Regel greift.
  • Volle Migrations-Pipelines pro Altsystem — sauberer Start, KWP-Sync füllt nach; HubSpot/Quiply als Read-only-Archiv, nur punktuelle CSV-Importe (AD-14)
  • KWP-Writeback im initialen Phase-32-Scope — keine fachlichen KWP-Mutationen; M091, M094-outbound, M074-outbound und Project-/Auftrag-Create bleiben bis VEXT-6 + erneuter Produktfreigabe geparkt (AD-32/CR-003)
  • EU-Email-Provider (AD-6) / Captcha (AD-7) — entschieden 11.06.: Mailjet + mCaptcha (Boilerplate-verdrahtet)
  • KWP Windows-Sync-Programm (M089, alte M19-Variante) — entfällt durch offizielle KWP-API; M089–M095 vor Umsetzung neu schneiden

Context

  • SHK-Domäne: Geerkens = Heizungsanlagen/Wartung/Reparatur. Entitäten: B2C/B2B-Kunden mit Anlagen-Zustand (Custom-Felder), mehrstufige Anlagen-Verkäufe, Wartungsverträge, Reparatur-Aufträge. Monteure arbeiten offline auf Baustellen (AD-17).
  • SHK-Defaults beim Tenant-Anlegen: fünf editierbare Tenant-Rollen + Permission-Bundles und ausschließlich die globale Rolle Admin für den Owner, SHK-Sales-Pipelines, Custom-Felder für Heizungsanlagen, Projekt-Pipelines, Automation-Templates, Onboarding-Branchen-Zweig — deklarativ, von Noah iterativ validiert (AD-12/AD-29).
  • Workspace-Naming: Alle Runtime-, UI-, Config-, DB-, Mail-, Queue- und View-Model-Pakete laufen unter @hivegrid/*; CLI = hivegrid-cli; technische Produkt-Contracts nutzen HIVEGRID_*, hivegrid_*, x-hivegrid-* und hivegrid.*.
  • Phase-0-Pflichten (vor jedem Fachmodul): (1) Codebase lauffähig halten, (2) Naming-Drift beheben (AD-10), (3) EU-Sterilisation (GitHub/Google-OAuth-Reste raus), (4) M00 + 4 Querschnitts-Neubauten (logActivity, Search-Registry, Subframe-Adapter, Mass-Action-Schutz), (5) fehlende Dependencies ergänzen.
  • Bau-Spec-Stil: Ticket-Docs sind self-contained und enthalten Was, Screens, DoD, technische Bausteine, Abhängigkeiten und aktuelle Quellen.

Constraints

  • Mandanten-Trennung: Echtes Postgres-RLS als bauliche Vorgabe (USING/WITH CHECK, SET LOCAL app.tenant_id, App-Rolle ohne BYPASSRLS) — AD-1
  • Datenmodell: Typisierte First-Class-Prisma-Tabellen; Boilerplate-Entity-Builder (Entity/Row/RowValue) wird entfernt; Custom-Felder über CustomFieldDefinition+CustomFieldValue — AD-2
  • EU-Stack (keine US-Kern-Abhängigkeit): Meilisearch Keyword-only (zentral auf node1, scoped Key — Infra-ADR-008/013) mit SQL-Fallback; kein pgvector/RRF/Embedding in v1/v2 nach AD-26. Per-Tenant-DEK/Envelope-Encryption app-seitig (AD-8 revidiert 12.06.: Hetzner-Stack hat kein Cloud-KMS — Master-Key im Coolify-Secret-Store, Rotations-Runbook; bei P1-Ist-Stand-Check bestätigen), Mailjet (AD-6 ✓), mCaptcha zentral captcha.saas-ctrl.com (AD-7 ✓)
  • Infra-Stack (Infra-Repo ~/Documents/GitHub/infra, ADR-009/010, ersetzt Scaleway seit 30.05.): Hetzner Cloud, ein Projekt pro SaaS (HiveGrid: hivegrid-db/app/worker/lb + S3-kompatibles Object Storage + Storage Box); Staging konsolidiert auf staging-1; Deploys via zentrale Coolify-Control-Plane; Registry = Gitea (build-once/promote); DNS = Cloudflare (hivegrid.de-Zone existiert); zentrale Dienste: Meilisearch/Sentry/Loki (node1), ClamAV, mCaptcha. fly.toml entfernt (Infra = Hetzner/Coolify); docs/deployment-region-provider-pinning.md stale → P1-Ist-Stand-Check
  • Sessions: Postgres als Source-of-Truth + Redis-Cache; Cookie hält nur Session-ID (AD-4)
  • Realtime: WebSocket für Chat (M13), SSE für Read-Updates (M03/M22) — AD-9
  • Tech-Stack: React Router 7, Node 22.12.x (dev/test) / node:20 (runtime), Prisma/Postgres, Redis; Subframe-UI ist Pflicht für jede Route
  • Repo/Naming: Bespoke HiveGrid-Codebase; @hivegrid/* ohne Alt-Aliase, Estate-Slugs bleiben externe Infrastruktur (AD-10)
  • Go-Live: Big-Bang — erst live mit vollständigem Phase-1-Produkt (AD-19); interne Bau-Reihenfolge nach AD-11

Key Decisions

Operative Architekturregeln stehen in AGENTS.md; IDs, Gründe und Status im kompakten Register docs/ARCHITECTURE-DECISIONS.md.

Decision Kern Status
AD-1 Mandanten-Trennung via echtes Postgres-RLS ✓ locked
AD-2 Typisierte Tabellen, Entity-Builder raus — revidiert 13.06.: Projekt = EINE typisierte Tabelle + CustomFields + Pipeline-Feld-Config-Layer; generischer Entity-Builder bleibt entfernt ✓ revidiert (13.06.)
AD-3 Plattform-Admin getrennt (Email+PW+TOTP, opt. Authentik-SSO) ✓ locked
AD-4 Sessions: Postgres Source-of-Truth + Redis-Cache ✓ locked
AD-5 Such-Engine: Meilisearch Keyword-only + SQL-Fallback; pgvector/RRF durch AD-26 aufgehoben ✓ revidiert (AD-26)
AD-6 EU-Email-Provider: Mailjet (Boilerplate-verdrahtet) ✓ locked (11.06.)
AD-7 Captcha: mCaptcha self-hosted (infra/ vorhanden) ✓ locked (11.06.)
AD-8 Verschlüsselung: Per-Tenant-DEK + Envelope, Crypto-Shredding ✓ locked
AD-9 Realtime: WebSocket (Chat) + SSE (Read-Updates) ✓ locked
AD-10 Naming: @hivegrid/* behalten, Docs anpassen ✓ locked
AD-11 Bau-Strategie: Hybrid (Fundament-Kern → SHK-Kernpfad → Breite) ✓ locked
AD-12 SHK-Defaults als deklaratives Seed, Noah validiert ✓ locked
AD-13 Go-Live-Scope: breiter Launch (Großteil der 36 Module) ✓ locked
AD-14 Migration: sauberer Start + KWP-Sync füllt nach ✓ locked
AD-15 Billing-Engine bauen, Preise geparkt ✓ locked
AD-16 Historischer KI-USP-Plan überholt durch AD-26
AD-17 Mobile: PWA-only (v1 + v2) — Offline via PWA/Web (P9), Web-Push in v2; kein Expo/native/App-Store (native → frühestens v3) ✓ revidiert (16.06.)
AD-18 Customer-Portal → komplett v2 ✓ revidiert (11.06.)
AD-19 Go-Live-Modus: Big-Bang ✓ locked
AD-20 Projekt-zentrisches Modell (NEU 13.06.): ein Projekt-Kern; Pipelines = konfigurierbare Views; „Deal"/„Auftrag" = Pipeline-Typen, keine eigenen Entitäten; Lead → Projekt (Weiterverarbeitungsfreigabe); Abnahme v1 als Checklisten-Sub-Area, Rechnung v1-Sub-Entity, KWP-Felder v1-Halter/v2-Sync ✓ locked (13.06.)
AD-26 Kein eigener KI-Layer/LLM/RAG/Whisper in v1/v2; stattdessen Remote-MCP (VR-MCP/VD-MCP) ✓ locked
AD-30 Customer-Portal auf portal.hivegrid.de/<tenant>; separater hivegrid-portal-Container aus dem Web-Image mit eigenem DB-Login; Starter/Team als Add-on, Business/Enterprise inklusive; Self-Service-Custom-Domain über DNS-Proof + CNAME + automatisches TLS ✓ locked (15.07.; Paket-/Rollout-Nachtrag 16.07.)
AD-31 Plattform-Leads nativ in der operatorweiten Admin-Welt; lead-inbox nach Backfill, Cutover und Drain stilllegen; M040a als R-LEADS vorziehen ✓ locked (16.07.)
AD-32 Initialer KWP-Scope in v2-P5/Phase 32 ist read-only; keine fachlichen KWP-Mutationen. Writeback inklusive M091, M094-outbound, M074-outbound und Project-Create bleibt hinter VEXT-6 + erneuter Freigabe geparkt. ✓ locked (22.07., CR-003)
KWP-Recut (historischer Stand 12.07.) Offizielle KWP-API → M089 entfällt, M090–M095 vereinfacht; M093 bleibt; KWP als App(key='kwp', connectionType='oauth2') mit tenant-spezifischer DataConnection und dynamischem Tenant-Relay (M33a). Tenant-OpenAPI/Redirects verifiziert; Runtime-Scopes + Auftrag-Create waren zu diesem Stand extern offen. durch AD-32 superseded; Runtime-Dauerbetrieb bewiesen

Erstellt: 2026-06-07 · aktive Quellen zuletzt bereinigt: 2026-08-02.