79 lines
11 KiB
Markdown
79 lines
11 KiB
Markdown
# 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.md` und `../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:
|
|
|
|
1. die operative Regel in `AGENTS.md`, falls Agents sie beim Bauen beachten müssen,
|
|
2. dieses Register mit Status und Verweis,
|
|
3. die betroffenen Ticket-Docs/Contracts,
|
|
4. 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.
|