# HiveGrid Intel — Architecture Decisions (ADR Extraction) source: docs/ARCHITECTURE-DECISIONS.md locked: true (AD-1 through AD-5, AD-8 through AD-19 are Accepted/binding; AD-6 and AD-7 are 🅿️ Backlog — NOT locked) extracted: 2026-06-07 --- ## AD-1 — Mandanten-Trennung: echtes Postgres-RLS status: Accepted (locked) scope: tenant isolation, alle tenant-scoped Module source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Row-Level-Security in Postgres als bauliche Vorgabe (nicht nur App-Level-Scoping). - RLS-Policies (USING/WITH CHECK) als Forward-Migration mit Inverse-SQL-Kommentar - Request-Middleware setzt `SET LOCAL app.tenant_id` - App-DB-Rolle ohne `BYPASSRLS` - Worker-/Job-Tenant-Context-Wrapper - Cache-Präfix `tenant:{id}:`, S3-Pfad `tenants/{id}/` - Ausnahmen ohne RLS: `users`, `subscription_*`, `feature_flags`, Branchen-Templates Betrifft: M019 + jedes tenant-scoped Modul (M01–M39 außer Plattform-Admin-Tabellen) --- ## AD-2 — Daten-Modell: typisierte Tabellen, Entity-Builder raus status: Accepted (locked) scope: CRM-Datenmodell, Fachentitäten source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: HiveGrid-Fachentitäten (CRM, Deals, Aufträge, Tasks, …) als dedizierte, typisierte First-Class-Prisma-Tabellen. Das Entity-Builder-CRM der Boilerplate (`Entity`+`Row`+`RowValue`, `apps/web/app/modules/crm`) wird entfernt, nicht angepasst. Custom-Felder über purpose-built `CustomFieldDefinition` + `CustomFieldValue` (JSONB-Wert), nicht über die polymorphe Row-Engine. Betrifft: M01, M02, M03, M04, M26 + alle Fachmodule --- ## AD-3 — Plattform-Admin-Identität: getrennt, Email+PW+TOTP, optional Authentik-SSO status: Accepted (locked) scope: AdminUser, AdminSession, admin.hivegrid.de source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Vollständig getrennte Admin-Welt — eigene `AdminUser`-Tabelle (eigenes `passwordHash`/`totpSecret`/`status`), eigene `AdminSession` (server-side, IP-gebunden), eigene `AdminRole`/`AdminPermission`-RBAC. Primärer Login: Email + Passwort + TOTP (Magic-Link verboten). Zusätzlich optionaler Authentik-OIDC/SSO-Login, gemappt auf dieselbe getrennte Admin-Identität. Kein Generalschlüssel zwischen Plattform und Mandanten. - `AdminAuditLog` nutzt vorhandenen `AuditEvent` (Hash-Kette, `tenantId=null` = plattformweit) Betrifft: M034–M041 (M37) --- ## AD-4 — Sessions: Postgres als Source-of-Truth + Redis-Cache status: Accepted (locked) scope: Session-Management, alle Auth-Flows source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Server-side Session-Tabelle in Postgres (Geräte-Liste mit Browser/IP/Standort/letzter Aktivität, Revoke, „von allen Geräten abmelden", 4h-Inaktivität, 30-Tage-Sliding-Window, Auto-Logout bei Passwort-/2FA-/Email-Änderung) als Quelle der Wahrheit; Redis-Cache für schnelle Pro-Request-Validierung. Cookie hält nur die Session-ID-Referenz. Betrifft: M021 (Mandanten-User), M034 (AdminSession), M141/M15 (Customer-Portal) --- ## AD-5 — Such-Engine: Meilisearch (self-hosted) + pgvector-Hybrid status: Accepted (locked) scope: Globale Suche, Search-Infrastruktur source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Keyword-Suche über selbst gehostetes Meilisearch (BP-`@hivegrid/search` weitgehend 1:1), semantische Suche über pgvector + EU-Embeddings (Scaleway 1024-dim, BP 1:1), kombiniert via RRF-Fusion. Embedding-Pipeline + Outbox + Indexer-Worker aus der BP übernehmen. Hinweis: Weicht bewusst von M056 "Postgres-FTS, kein Extra-Service" ab → Change-Request gegen M056 nötig. Betrifft: M24 / M056–M058 --- ## AD-6 — EU-Email-Provider status: BACKLOG — NICHT LOCKED (🅿️ Entscheidung später) scope: Transaktions- und Marketing-Email source: docs/ARCHITECTURE-DECISIONS.md Tendenz: Mailjet (EU/FR). MailerSend (BP-Default) ist vertretbar (EU ISO 27001 + GDPR-DPA), Caveat: US-Entität. Alternativen: Mailjet/Brevo, Scaleway TEM. Betrifft: M09, M10, M22 --- ## AD-7 — Captcha / Bot-Schutz status: BACKLOG — NICHT LOCKED (🅿️ Entscheidung später) scope: Login, Public-Forms, Booking source: docs/ARCHITECTURE-DECISIONS.md Tendenz: EU — Friendly Captcha (DE) oder self-hosted mCaptcha. Turnstile (BP) und hCaptcha (Spec) sind beide US-Firmen. Betrifft: Login (M020), Public-Forms (M05/M125), Booking (M06) --- ## AD-8 — Verschlüsselung: Per-Tenant-DEK + Envelope status: Accepted (locked) scope: Verschlüsselung, HR-Passwort-Safe, OAuth-Tokens, DSGVO-Löschung source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Pro Mandant ein Data-Encryption-Key (DEK), verschlüsselt mit einem Master-Key (Scaleway Key Manager) — Envelope-Encryption. Crypto-Shredding bei Mandanten-Löschung (Tenant-Key wegwerfen → alle verschlüsselten Daten unlesbar). Betrifft: M14/M134 (HR-Passwort-Safe), OAuth-Tokens (M09/M25/M12), M35/M165 (DSGVO-Löschung) --- ## AD-9 — Realtime: WebSocket für Chat + SSE für Read-Updates status: Accepted (locked) scope: Realtime-Infrastruktur, Team-Chat, Kanban, Notifications source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Generischer WebSocket-Room-Layer für bidirektionale Echtzeit (Team-Chat M13: Rooms, Presence, Typing, Read-Receipts). SSE bleibt für einseitige Live-Updates (Kanban M03, Notifications M22). `hocuspocus` bleibt CRDT-only (Kollab-Dokumente). Betrifft: M13 (bidirektional WebSocket); SSE-Pfad: M03, M22 --- ## AD-10 — Naming-Konvention: HiveGrid-Scope ohne Alt-Aliase status: Accepted (locked) scope: Paket-Naming, Mono-Repo-Struktur, alle Module source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Alle Workspace-Pakete und technischen Produkt-Contracts nutzen HiveGrid-Namen: `@hivegrid/*`, `hivegrid-cli`, `HIVEGRID_*`, `hivegrid_*`-Cookies, `x-hivegrid-*`-Header und `hivegrid.*`-Queue-Namen. Es gibt keine Alt-Aliase. - `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock` behalten ihre realen Pfade - Estate-Slugs bleiben externe Infrastruktur (`git.tool-ctrl.de`, `toolctrl-labs`, `toolctrl-ci`, Plane-Workspace `toolctrl`) - Docs: wo "ui-hivegrid", Alt-Scopes oder alte Sidebar-Pfade stehen, ist das Doku-Drift Betrifft: Querschnitt (alle Module), Phase 0 --- ## AD-11 — Bau-Strategie: Hybrid (Fundament-Kern, dann Geerkens-Kernpfad) status: Accepted (locked) scope: Delivery-Sequenzierung source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Nach Phase 0 zuerst Fundament-Kern (M27 Auth + M33a Apps-Engine + M01 CRM-Datenmodell), dann sofort Geerkens-Wertschöpfungskette Lead → Sales → Auftrag → KWP, danach Breite (HR, Portal, Marketing, Mobile, Billing). --- ## AD-12 — SHK-Domänen-Defaults: aus Spec als Seed, Noah validiert status: Accepted (locked) scope: SHK-Branchen-Templates, Seeding source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: SHK-Inhalte (6 Standard-Rollen + Permission-Bundles, SHK-Sales-Pipeline-Stufen, Standard-Custom-Felder + Tags, Provisionierungs-Daten) werden als deklaratives, leicht änderbares Seed umgesetzt. Noah/Geerkens validieren iterativ. Blockiert den Bau nicht. --- ## AD-13 — Go-Live-Scope: breiter Launch status: Accepted (locked) scope: Delivery-Scope source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Erster Geerkens-Go-Live umfasst nicht nur die Vertriebskette, sondern auch HR-Hub, Customer-Portal, Marketing und Mobile. Scope ≈ Großteil der 35 Module. Sequenzierung trotzdem nach AD-11. --- ## AD-14 — Migration: sauberer Start + KWP-Sync füllt nach status: Accepted (locked) scope: Datenmigration, KWP-Sync source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Geerkens startet weitgehend leer; KWP-Sync bringt Auftrags-/Stammdaten automatisch. HubSpot/Quiply-Altdaten bleiben extern als Read-only-Archiv; nur punktuelle CSV-Importe. Keine vollen Migrations-Pipelines pro Quelle zum Launch. --- ## AD-15 — Pricing/Billing: Engine bauen, Preise geparkt status: Accepted (locked) scope: Legacy-Provider, Billing-Engine, Pricing source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Legacy-Provider-Integration + Seat-/Plan-Engine + Verbrauchs-Metering werden technisch gebaut, die konkreten Preis-Stufen bleiben geparkt. Geerkens läuft auf manueller Sonderkondition/Trial. Self-Service-Checkout-Preise = eigene spätere Pricing-Runde. --- ## AD-16 — USP-Säulen (Automation + KI): volle Tiefe zum Launch status: Accepted (locked) scope: Automation-Engine M17, KI-Layer M18 source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Kompletter visueller Automation-Editor (alle Trigger/Aktionen, 24h-Undo, Guards) und voller KI-Layer (EU-Provider, RAG, Sprach-zu-Automation, Pay-as-you-go) sind day-1 dabei — nicht nur Fundament. --- ## AD-17 — Mobile-Offline: voller Offline-Betrieb status: Accepted (locked) scope: Mobile-App M36, Offline-Sync source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Monteur kann auf der Baustelle offline Aufträge bearbeiten, Abnahmen erfassen, Plantafel sehen; alles wird gequeued + bei Sync mit „KWP gewinnt" aufgelöst. --- ## AD-18 — Customer-Portal: voll inkl. Skalierungs-Sicht status: Accepted (locked) scope: Customer-Portal M15 source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Komplettes Portal day-1: Projekt-Sicht + Upload + Reklamation + Subunternehmer-Zugang + Skalierungs-Sicht (Service-Inbox + Routing + Pro-Kunden-Lebensdauer). --- ## AD-19 — Go-Live-Modus: Big-Bang status: Accepted (locked) scope: Go-Live-Strategie source: docs/ARCHITECTURE-DECISIONS.md Entscheidung: Geerkens geht erst live, wenn das vollständige Phase-1-Produkt steht — ein großer Launch, kein phasiertes Produktiv-Go-Live. Interne Bau-Reihenfolge bleibt AD-11. Bewusst akzeptiert: längste Zeit bis zum ersten echten Nutzer-Feedback, höchstes Risiko. Gegenmaßnahme: Noah/Geerkens-Validierung pro Modul über PROGRESS-TRACKER-Klick-Pfad als Feedback-Ersatz. --- ## Phase-0-Pflichten (Voraussetzungen, keine ADR-Entscheidungen) source: docs/ARCHITECTURE-DECISIONS.md 1. Codebase lauffähig halten 2. Naming-Drift beheben: HiveGrid-Contracts in Code und Docs, Sidebar-Konvention korrigieren 3. EU-Sterilisation: GitHub/Google-OAuth-Reste + `User.githubId/googleId` entfernen 4. M00 aktivieren + 4 echte Neubauten: `logActivity()`/Activity-Stream, Search-Registry, Subframe-Adapter-Code, Mass-Action-Schutz 5. Fehlende Dependencies ergänzen: `signature_pad`, `browser-image-compression`, `react-grid-layout`, `@dnd-kit`, `libphonenumber`, `ics`/`ical-generator`, `btree_gist`/`EXCLUDE`-Constraint u.a. ## KWP-API-Entscheidung (separater Strang) source: docs/ARCHITECTURE-DECISIONS.md KWP bekommt eine offizielle API-Anbindung → M089 (Windows-Sync-Programm) entfällt, M090/M091/M092/M094/M095 vereinfachen sich, M093 bleibt. KWP als `DataConnection type='rest-api'` ins Apps-Engine-Muster (M33a). M089–M095 vor Umsetzung neu schneiden.