Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/intel/decisions.md
T
2026-07-08 16:15:37 +02:00

11 KiB
Raw Blame History

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.