247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# 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.
|