11 KiB
11 KiB
HiveGrid 2.0 — Entscheidungsregister
Stand: 2026-08-02
Diese Datei sichert die Architekturentscheidungen und ihre IDs. Sie ist bewusst kein zweites Agenten-Handbuch:
- Operative, repo-weite Regeln stehen in
AGENTS.md. - Das Datenmodell steht in
.planning/ENTITY-MODEL.md. - Scope, Abhängigkeiten und DoD stehen in der jeweiligen Ticket-Doc.
- Genehmigte Produktänderungen stehen in
docs/CHANGE-REQUESTS.md. - Infrastrukturentscheidungen folgen
../infra/STANDARDS.mdund../infra/decisions/.
Die ausführliche Fassung vor diesem Recut bleibt über die Git-Historie erhalten. Dieses Register hält stattdessen pro ID nur den aktuellen Entscheid, den Grund und den maßgeblichen Anker fest.
Status: aktiv = bindende Zielarchitektur · historisch = Kontext, keine operative Regel ·
abgelöst = durch eine neuere Entscheidung ersetzt.
Aktive Kernentscheidungen
| ID | Entscheidung | Grund und Anker |
|---|---|---|
| AD-1 | Mandantendaten werden durch Postgres-RLS mit FORCE ROW LEVEL SECURITY, kontextgebundene App-/Worker-Rollen ohne BYPASSRLS und tenant-sichere Nebenpfade geschützt. Neue Tabellen benötigen Policy und Contract-Gate. |
Defense-in-depth gegen vergessene App-Filter. Operativer Vertrag: AGENTS.md §Row-Level-Security. |
| AD-2 | Fachmodelle sind typisierte Prisma-Tabellen. Der generische Entity/Row/RowValue-Builder erhält keine neuen Konsumenten und wird bei Berührung seiner Altmodule typisiert abgelöst. |
Typen, Indizes, Constraints, Permissions und RLS bleiben fachlich prüfbar. Migration: AGENTS.md §Entity-Builder und .planning/ticket-docs/R-P6B.md. |
| AD-3 | Die Plattform-Admin-Welt nutzt eigene AdminUser-, Session-, RBAC- und MFA-Grenzen. Produktiv ist Authentik-OIDC der einzige Admin-Login; der lokale Passwort-Fallback bleibt development-only und fail-closed. |
Kein Generalschlüssel zwischen Plattform und Mandanten. Anker: AGENTS.md §Kanonische lokale Login-Daten und Estate-Infrastruktur. |
| AD-4 | Sessions sind serverseitig; Postgres ist Source of Truth, Redis nur der schnelle Validierungs-Cache. Cookies enthalten ausschließlich die Sessionreferenz. | Dauerhaftes Revoke, Geräteliste und verlässliches Revoke-all. |
| AD-8 | Sensible Tenant-Daten und Provider-Credentials nutzen per-Tenant-DEKs mit Envelope-Encryption. Der aktuelle Wrapper nutzt getrennte Environment-Secrets (CRYPTO_SECRET), bleibt aber gegen einen externen Key-Wrapper austauschbar; Tenant-Löschung zerstört den DEK. |
Begrenzter Blast-Radius und Crypto-Shredding. Anker: packages/db/src/crypto/tenant-envelope.server.ts, docs/env-vars.md. |
| AD-20 | CRM und Pipelines sind projekt-zentrisch: ein typisierter Projekt-Kern, Pipelines als konfigurierbare Views, Lead → Projekt; Deal/Auftrag sind keine eigenen Kernentitäten. |
Ein konsistentes Domänenmodell statt paralleler Objektwelten. Source of Truth: .planning/ENTITY-MODEL.md. |
| AD-21 | Prisma bleibt ein Schema-Ordner. Neue Domänenmodelle erhalten eine eigene Datei; core.prisma/accounts.prisma bleiben minimale gemeinsame Kerne. Feature-Branches nutzen db push, die lineare Forward-only-Migration entsteht beim Merge. |
Vermeidet Schema- und Migrationskonflikte bei paralleler Arbeit. Operativer Vertrag: AGENTS.md §Prisma-Schema & Migrationen. |
| AD-22 | GeoIP wird lokal aus einer MMDB aufgelöst. Persistiert werden HMAC-pseudonymisierte IPs und höchstens das Land, keine präzisen Geodaten. | Keine Übermittlung von Endnutzer-IPs an einen Geo-SaaS; Datenminimierung. Anker: apps/web/app/modules/ipAddress/. |
| AD-23 | Uploads liegen privat. Zugriff erfolgt über authentifizierte, tenant- und permission-geprüfte App-Routen oder eng begrenzte signierte URLs. DSGVO-Exporte werden wegen SSE-C ausschließlich durch die geprüfte App-Route gestreamt. | Kundendokumente dürfen nie durch erratbare oder dauerhafte Public-URLs erreichbar sein. |
| AD-29 | Jeder neue Workspace erhält fünf versionierte, editierbare SHK-Rollen; der Owner erhält nur die globale Rolle Admin. Bestehende Tenants werden nicht automatisch umgeschrieben. |
Reproduzierbares produktionsgleiches Bootstrap ohne SEED_*-Runtime-Schalter. Anker: apps/web/app/domain/tenant-bootstrap/. |
Aktive Plattform- und Produktentscheidungen
| ID | Entscheidung | Grund und Anker |
|---|---|---|
| AD-5 | Suche ist selbst gehostetes Meilisearch mit hivegrid-*-Indizes, Tenant-Filter, Outbox-Indexer und SQL-Revalidierung. v1/v2 bleiben keyword-only; pgvector, Embeddings und RRF entfallen. Staging nutzt den Estate-Dienst, Produktion die dedizierte HiveGrid-Instanz aus AD-24. |
Gute Keyword-Suche ohne eigene KI-/RAG-Infrastruktur. Anker: docs/deploy/meilisearch.md. |
| AD-6 | Mailjet ist Provider für transaktionale und Marketing-Mails. MailerSend ist keine Zielarchitektur. | EU-Anbieter und ein gemeinsamer Mailpfad. |
| AD-7 | Captcha ist self-hosted. mCaptcha bleibt der kompatible Default; Cap ist der eingecheckte Ersatzpfad. Google-, Cloudflare- und hCaptcha-Abhängigkeiten sind keine Zielarchitektur. |
Kein externer US-Captcha-Subprozessor. Anker: packages/captcha/, infra/mcaptcha/, infra/cap/. |
| AD-9 | Bidirektionaler Chat nutzt WebSockets; einseitige Live-Updates nutzen SSE. Hocuspocus bleibt auf CRDT-Kollaboration begrenzt. | Passendes Transportmodell je Interaktion statt eines Universal-Realtime-Layers. |
| AD-10 | Produktcode und interne Contracts heißen ausschließlich @hivegrid/*, HIVEGRID_*, hivegrid_*, x-hivegrid-* und hivegrid.*. Externe Estate-Namen wie toolctrl-labs bleiben unverändert. |
Keine parallelen Alt-Aliase oder fiktiven Paketpfade. Operativer Vertrag: AGENTS.md §Naming-Konvention. |
| AD-17 | Mobile ist in v1/v2 ausschließlich responsive Web/PWA mit Service Worker, IndexedDB/Offline-Queue und Web Push. Keine native App, kein Expo/Capacitor, kein App-Store-Scope vor v3. | Eine auslieferbare mobile Oberfläche ohne zweiten Client-Stack. |
| AD-24 | HiveGrid-Produktion läuft als Ausnahme zum Estate-Default in einem eigenen Hetzner-Account mit eigenem Coolify und fünf VMs. Gitea Registry, Sentry und Cloudflare bleiben geteilte, authentifizierte Dienste; Meilisearch, ClamAV und Captcha laufen innerhalb des Prod-Accounts. | Harte Blast-Radius- und Spin-off-Grenze. Autoritative Infra-Entscheidung: ../infra/decisions/016-hivegrid-prod-dedicated-account-and-coolify.md; Runbook: docs/ops/prod-rollout-hivegrid.md. |
| AD-25 | Die Standard-E-Signatur ist eine gehärtete, selbst betriebene SES mit Intent, OTP, PDF-Versiegelung, Zeitstempel und Audit-Trail. PandaDoc bleibt optionales Tenant-BYOK; QES ist ein späteres DE-QTSP-Add-on. Vor Produktivfreigabe bleibt juristische Bestätigung Pflicht. | Souveräner Standardpfad bei erhaltener Provider-Option. Anker: packages/integrations/src/adapters/ses-selfhosted.ts, .planning/ticket-docs/AK-P16d.md. |
| AD-26 | HiveGrid hostet in v1/v2 kein LLM, RAG, Whisper oder HiveMind. KI-Clients bringen die Inferenz mit und greifen über den separaten MCP-Service auf permission- und tenant-gescopte Tools zu. | Kein eigener KI-Provider-, Modell- oder Tokenabrechnungs-Stack. Anker: apps/mcp, .planning/ticket-docs/VR-MCP.md. |
| AD-27 | Billing ist dreigeteilt: HiveGrid hält Produktrechte, Lago self-hosted hält Billing/Invoices, Mollie verarbeitet Zahlungen. Kein Usage-Billing in v1; Fachdaten werden nicht an Billing-/Payment-Provider übertragen. | Klare Source-of-Truth-Grenzen ohne Legacy-Provider-Default. Anker: BILL-*-Ticket-Docs und docs/ops/lago-*.md. |
| AD-28 | Fehlende finale Screens blockieren Dev-Tickets nicht. Der Dev baut eine getestete Interim-UI aus ~/ui gegen stabile View-Models; die finale Subframe-Optik bleibt als design-nachzug getrackt. |
Backend- und Integrationsarbeit bleibt lieferbar, ohne den Designer-Workflow zu umgehen. Operativer Vertrag: AGENTS.md und .planning/INTERIM-UI-PLAYBOOK.md. |
| AD-30 | Das Customer-Portal läuft auf einem eigenen Host und in der getrennten Runtime hivegrid-portal, zunächst aus demselben unveränderlichen Web-Image. Eigene Sessions, minimale DB-Rechte, Entitlement-Gates und verifizierte Custom-Domains sind Pflicht. |
Öffentliche Endkunden-Surface braucht eine eigene Trust Boundary. Kommerzieller und Domain-Vertrag: docs/CHANGE-REQUESTS.md CR-001; Routen: docs/INTEGRATION-CONTRACTS.md. |
| AD-31 | Plattform-Leads gehören tenantlos in die Admin-Domäne von HiveGrid. Der separate lead-inbox-Dienst wird erst nach gesichertem Backfill, Cutover und Drain stillgelegt. |
Kein zweites CRM und keine künstliche Tenant-Zuordnung für HiveGrids eigenen Vertrieb. Anker: .planning/ticket-docs/R-LEADS.md, .planning/ticket-docs/VA-P28b.md. |
| AD-32 | Der initiale KWP-Scope ist fachlich read-only: OAuth-Lifecycle und die feste Read-Allowlist sind erlaubt, KWP-Mutationen sind vor HTTP fail-closed gesperrt. Writeback braucht zuerst VEXT-6 und eine neue ausdrückliche Produktfreigabe. |
Kein spekulativer oder nicht auslieferbarer Schreibpfad. Vollvertrag: .planning/KWP-API-CONTRACT.md, CR-003/CR-005 und VR-P32*. |
Historische oder abgelöste Entscheidungen
| ID | Status | Gesicherter Kontext |
|---|---|---|
| AD-11 | historisch | Der ursprüngliche Baupfad „Fundament, Kernkette, Breite“ erklärt die frühe Reihenfolge. Operativ gelten heute Plane, Ticket-Docs und Roadmaps. |
| AD-12 | abgelöst durch AD-29 | Frühere SHK-Rollen-Seeds mit zehn beziehungsweise sechs Rollen wurden entfernt. Das deklarative Bootstrap-Prinzip lebt in AD-29 weiter. |
| AD-13 | historisch | Der frühe Produktentscheid war ein breiter Geerkens-Launch. Aktueller Lieferumfang und Termine werden ausschließlich über Requirements, Ticket-Docs und Plane gesteuert. |
| AD-14 | teilweise abgelöst durch AD-32 | Der saubere Start ohne vollständige HubSpot-/Quiply-Migrationspipelines bleibt Kontext. Die Annahme, KWP fülle den Bestand direkt per Vollsync, ist nicht mehr der aktuelle Vertrag. |
| AD-15 | abgelöst durch AD-27/AD-30 | Die alte Billing- und Preisparker-Entscheidung wurde durch Lago/Mollie und die ausdrücklich genehmigten Portalpreise ersetzt. Weitere Preise bleiben ohne CR unentschieden. |
| AD-16 | teilweise abgelöst durch AD-26 | Die Automation-Säule bleibt im Requirement-Scope. Der eigene KI-Layer ist vollständig gestrichen. |
| AD-18 | abgelöst durch AD-30 und P26-Tickets | Der alte „vollständiges Portal day-1“-Text ist kein Liefervertrag mehr. Runtime, Features und Rollout liegen in CR-001 und VA-P26*. |
| AD-19 | historisch | „Big Bang“ war eine frühe Go-live-Strategie. Aktuelle Release-, Pilot- und Sign-off-Entscheidungen liegen in Plane, Ticket-Docs und Runbooks. |
Pflegevertrag
Eine neue oder geänderte Entscheidung aktualisiert in derselben Änderung:
- die operative Regel in
AGENTS.md, falls Agents sie beim Bauen beachten müssen, - dieses Register mit Status und Verweis,
- die betroffenen Ticket-Docs/Contracts,
- bei Scope- oder Produktänderungen
docs/CHANGE-REQUESTS.md.
Neue Langform-ADRs werden nur angelegt, wenn Trade-offs oder Rollback nicht sinnvoll in einem Ticket oder Infra-ADR dokumentiert werden können. Das Register darf nicht erneut zu einem parallelen Planungsarchiv anwachsen.