# HiveGrid 2.0 — Architektur-Entscheidungen > Entscheidungen aus dem Boilerplate-Abgleich, den späteren HiveGrid-Pivots und > der Bespoke-Planung. Diese ADR-Liste ergänzt `AGENTS.md` und ist verbindlich > für die Umsetzung. Die historischen Boilerplate-Mapping-Ordner wurden im > Bespoke-Cleanup entfernt; aktuelle Quellen sind `.planning/ENTITY-MODEL.md`, > `.planning/PHASE-SOURCES.md`, die Ticket-Docs und `docs/milestones/`. > Legende: ✅ entschieden · 🅿️ Backlog (Entscheidung später). --- ## AD-1 — Mandanten-Trennung: echtes Postgres-RLS ✅ **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 **Warum:** Spec A.4 + M019-Erfolgskriterium (Pen-Test). Defense-in-depth — ein vergessener Query-Filter kann keine Fremddaten mehr leaken. Boilerplate hat **nur** App-Level-Scoping. **Betrifft:** M019 (+ jedes tenant-scoped Modul). ## AD-2 — Daten-Modell: typisierte Tabellen, Entity-Builder raus ✅ **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. **Warum:** Spec M01 verlangt typisierte Tabellen mit Constraints, Indizes (`pg_trgm`, `tenant_id, archived_at, last_activity_at`), `ContactEmail`/`ContactPhone`, M:N-Relationen, zentrale `Activity`-Tabelle. Polymorphes `RowValue` ist damit unvereinbar (Performance bei 10k+, Indizes, Permissions, RLS). Zwei Architekturen parallel = Fremd-Architektur sickert ein. **Betrifft:** M01, M02, M03, M04, M26 (+ alle Fachmodule). > **🔄 REVIDIERT 2026-06-13 (Modell-Pivot, siehe AD-20):** Deal + Project verschmelzen zu EINER > typisierten `Projekt`-Tabelle (Superset der Felder) + `CustomFieldDefinition/Value` + einem > neuen **Pipeline-Feld-Config-Layer** (welche Felder pro Pipeline+Status sichtbar/pflichtig sind; > nicht sichtbare Felder bleiben im Hintergrund erhalten). Die Konfigurierbarkeit ist **Metadaten > über typisierten Spalten** — der generische Entity-Builder (Entity/Row/RowValue) bleibt entfernt. > AD-2-Prinzip („typisiert, kein Generikum") bleibt gewahrt. Anker: `.planning/ENTITY-MODEL.md`. > **🔴 PRÄZISIERUNG & VERBINDLICHE REGEL 2026-06-29 (R-P6 / R-P6B):** Das „✅" oben gilt bislang **nur für den CRM-Pfad** (R-P6 typisierte Kontakte + R-P6B-α + R-P6C). Der **generische Entity-Builder läuft noch** und wird weiter genutzt von EmailMarketing, Form-Submission (`apps/worker`/`apps/api`), WorkflowEngine, formulas und ~49 `EntitiesSingleton`-Konsumenten (Konsumenten-Matrix + Reihenfolge/Ownership: `.planning/ticket-docs/R-P6B.md`). > > **Regel (ab jetzt verbindlich): KEINE neuen Entity-Builder-Konsumenten.** Jedes neue Fachmodul/Feature nutzt **typisierte** Prisma-Tabellen (wie CRM), niemals `Entity`/`Row`/`RowValue`, `modules/rows`, `utils/db/entities`, `EntitiesSingleton`, die `*Api.server`-Entity-Layer oder den `CrmService`-Legacy. Ein PR, der einen **neuen** Builder-Konsumenten einführt, wird abgelehnt (wie ein Anti-Listen-Verstoß). > > **Ablöse-Pflicht: Der generische Entity-Builder MUSS vollständig abgelöst werden** (R-P6B-β; kein „optional"). Vorgehen **organisch**: jedes Builder-nutzende Modul wird **typisiert, sobald es ohnehin angefasst wird** (Migration durch Neubau < Refactor); neue Module sowieso typisiert. Ist der letzte Konsument weg, fällt `entityBuilder.prisma` (+ Tenant-Daten-Entscheidung). **Spätlimit:** vor produktivem Masseneinsatz von `Row`-Daten (sonst wird die Schema-Löschung zur Daten-Migration). ## AD-3 — Plattform-Admin-Identität: getrennt, Email+PW+TOTP, optional Authentik-SSO ✅ **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` braucht **kein** neues Schema: vorhandener `AuditEvent` (Hash-Kette, `tenantId=null` = plattformweit) deckt das ab. - Boilerplate-Admin-Auth (Login-Flow, MFA-Step-up-Gate, Rate-Limit, Session-Cookie-Policy) dient als **Vorlage**, nicht 1:1 (BP hat AdminUser nur als `User`-Extension). **Warum:** Spec 37.1 / M034 verbietet den geteilten Identity-/RBAC-Pfad explizit. **Betrifft:** M034–M041 (M37). ## AD-4 — Sessions: Postgres als Source-of-Truth + Redis-Cache ✅ **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. **Warum:** Spec B.5 braucht dauerhafte, abfragbare Geräte-Liste + verlässliches Revoke-all; reine Cookies (BP-Default) können nicht serverseitig widerrufen werden; reines Redis verliert Geräte-Historie bei Flush. **Betrifft:** M021 (Mandanten-User), M034 (`AdminSession`), M141 (Customer-Portal). ## AD-5 — Such-Engine: Meilisearch (self-hosted) + pgvector-Hybrid ✅ **Entscheidung:** Keyword-Suche über das **selbst gehostete 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. **Warum:** Meilisearch wird ohnehin selbst gehostet (EU-Datenhoheit + Ops bereits gelöst) → bessere Tippfehler-Toleranz/Relevanz + maximaler Reuse. **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 ✅ **Entscheidung (2026-06-16, EXT-02):** **Mailjet** (EU/FR) als EU-Email-Provider für transaktionale **und** Marketing-Mails. MailerSend (BP-Default) wird **verworfen** — MailerSend, Inc. ist US-Entität (Transfers via EU-US Data Privacy Framework), unter strikter LP-13-Lesart („keine US-Gesellschaft im Boot", wie bei OpenAI/Anthropic) problematisch. **Warum:** EU-Datenhoheit ohne US-Gesellschaft im Boot; feature-reich (transaktional + Marketing + A/B in P14). Boilerplate ist bereits auf `MAILJET_*` verdrahtet. **Verifikationsstand (EXT-02):** Sende-Domain `hivegrid.de` bei Mailjet verifiziert — SPF (`include:spf.mailjet.com`) + DKIM (Selector `mailjet`) Auto-Probe **grün**, Sender `*@hivegrid.de` aktiv; DMARC `p=none` (Monitoring während Warm-up). **Cleanup-Follow-ups:** (a) `include:_spf.mailersend.net` aus dem SPF-Record entfernen, sobald die Migration vollständig ist; (b) DMARC nach Warm-up von `p=none` auf `p=quarantine` ziehen. **Betrifft:** M09, M10, M22, M102. ## AD-7 — Captcha / Bot-Schutz 🅿️ (Backlog) **Status:** Entscheidung später. **Tendenz: EU** — Friendly Captcha (DE, GDPR-first) oder self-hosted mCaptcha (passt zum Meilisearch-Self-Host-Ansatz). - Turnstile (BP) und hCaptcha (Spec) sind beide US-Firmen → bei strikter Linie Change-Request. **Betrifft:** Login (M020), Public-Forms (M05/M125), Booking (M06). ## AD-8 — Verschlüsselung: Per-Tenant-DEK + Envelope ✅ **Entscheidung:** Pro Mandant ein Data-Encryption-Key (DEK), verschlüsselt mit einem Master-Key (Scaleway Key Manager o.ä.) — Envelope-Encryption. Crypto-Shredding bei Mandanten-Löschung (M165: Tenant-Key wegwerfen → alle verschlüsselten Daten unlesbar). **Warum:** Spec verlangt Per-Tenant für Passwort-Safe (M134) + OAuth-Tokens; globaler Key (BP-Default) exponiert bei Kompromiss alle Mandanten und erlaubt kein Crypto-Shredding. **Betrifft:** M134 (HR-Passwort-Safe), OAuth-Tokens (M09/M25/M12), M165 (DSGVO-Löschung). ## AD-9 — Realtime: WebSocket für Chat + SSE für Read-Updates ✅ **Entscheidung:** Generischer WebSocket-Room-Layer für bidirektionale Echtzeit (Team-Chat M13: Rooms, Presence, Typing, Read-Receipts). SSE (BP-Default) bleibt für einseitige Live-Updates (Kanban M03, Notifications M22). `hocuspocus` bleibt CRDT-only (Kollab-Dokumente). **Warum:** SSE ist einseitig → für Chat ungeeignet; hocuspocus ist CRDT, kein Chat-Broadcast. **Betrifft:** M13 (M110–M114); SSE-Pfad: M03, M22. ## AD-10 — Naming-Konvention: HiveGrid-Scope ohne Alt-Aliase ✅ **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-Scope-Package-Aliase und keine parallel gepflegten Alt-Binaries. - `packages/ui-app`, `packages/ui-subframe` und `packages/ui-mock` behalten ihre realen Pfade. Ein fiktives `packages/ui-hivegrid` wird nicht eingeführt. - Estate-Slugs bleiben dort erhalten, wo sie externe Infrastruktur beschreiben (`git.tool-ctrl.de`, `toolctrl-labs`, `toolctrl-ci`, Plane-Workspace `toolctrl`). - HiveGrid-Doku (`AGENTS.md`, `docs/INTEGRATION-CONTRACTS.md`, PLANs, Reports) wird auf diese Realität gezogen; ältere `ui-hivegrid`- oder Alt-Scope-Erwähnungen sind Doku-Drift. **Warum:** HiveGrid wird bespoke weitergeführt. Einheitliche Produktnamen reduzieren kognitive Last, vermeiden falsche Imports und verhindern, dass neue Arbeit versehentlich alte Contracts weiterträgt. **Betrifft:** Querschnitt (alle Module), Phase 0. --- # Delivery- & Scope-Entscheidungen ## AD-11 — Bau-Strategie: Hybrid (Fundament-Kern, dann Geerkens-Kernpfad) ✅ **Entscheidung:** Nach Phase 0 zuerst der Fundament-Kern (M27 Auth + M33a Apps-Engine + M01 CRM-Datenmodell), dann sofort die Geerkens-Wertschöpfungskette **Lead → Projekt (konfigurierbare Pipelines) → KWP**, danach die Breite (HR, Portal, Marketing, Mobile, Billing-Feinheiten). Balance aus sauberem Fundament und früh sichtbarem Nutzen. > **🔄 REVIDIERT 2026-06-13 (Modell-Pivot, AD-20):** Kette ist nicht mehr „Lead → Sales(Deal) → Auftrag(Project)", > sondern **Lead → Projekt → KWP**. Sales und Auftrag sind konfigurierbare Pipeline-Views auf denselben `Projekt`-Kern. ## AD-12 — SHK-Domänen-Defaults: aus Spec als Seed, Noah validiert ✅ **Entscheidung:** Die SHK-Inhalte (10 Standard-Rollen + Permission-Bundles [27.7/N1], SHK-Sales-Pipeline-Stufen [M59], Standard-Custom-Felder + Tags [M44], Provisionierungs-Daten [M158]) werden aus Spec/Pflichtenheft als **deklaratives, leicht änderbares Seed** umgesetzt; Noah/Geerkens validieren iterativ im Klick-Pfad. Blockiert den Bau nicht. > **🔄 AMENDMENT 2026-06-19 (Owner-Entscheidung Raffael, Partner-validiert):** Die spekulativen „10 Standard-Rollen" > aus 27.7/N1 sind auf die **6 vom Partner gelieferten Rollen** festgelegt: **Geschäftsführer, Projektleiter, > Verwaltung, Vertriebler, Kundensupporter, Monteur** (Seed `apps/web/app/utils/services/shkRoles.server.ts`, > idempotent, `is_demo_data`). Das deklarative-Seed-Prinzip bleibt unverändert; nur die Anzahl/Liste ist fixiert. > R-P2b-DoD + Planungs-Docs (.planning/, Milestone-Layer) entsprechend von 10 auf 6 nachgezogen. ## AD-13 — Go-Live-Scope: breiter Launch ✅ **Entscheidung:** Der erste 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 ✅ **Entscheidung:** Geerkens startet weitgehend leer; KWP-Sync (M089ff) bringt Auftrags-/Stammdaten automatisch. HubSpot/Quiply-Altdaten bleiben **extern als Read-only-Archiv**; nur punktuelle CSV-Importe via `packages/imports`. Keine vollen Migrations-Pipelines pro Quelle zum Launch. ## AD-15 — Pricing/Billing: Engine bauen, Preise geparkt ✅ **Entscheidung (revidiert 2026-07-04, siehe AD-27):** Legacy-Provider wird nicht mehr als Billing-/Payment-Default gebaut. HiveGrid nutzt eine selbst gehostete Billing-Engine und einen EU-Payment-Processor. Für v1 sind nur **Plans + Seats** im Scope; **kein Usage-Billing** und keine konkreten öffentlichen Preisstufen. Geerkens läuft weiter auf manueller Sonderkondition/Trial. Self-Service-Checkout-Preise bleiben eine eigene spätere Pricing-Runde. ## AD-16 — USP-Säulen (Automation + KI): volle Tiefe zum Launch ✅ (⚠ KI-Hälfte abgelöst von AD-26, 2026-06-22) **Entscheidung:** Kompletter visueller Automation-Editor (M075–M082, alle Trigger/Aktionen, 24h-Undo, Guards) **und** voller KI-Layer (M083–M088, EU-Provider, RAG, Sprach-zu-Automation, Pay-as-you-go) sind day-1 dabei — nicht nur Fundament. > **⚠ KI-Hälfte abgelöst durch [AD-26] (2026-06-22):** Kein selbst-gehostetes LLM/RAG/HiveMind mehr — KI kommt via **MCP-Server** (externe Clients), M083–M088 gestrichen. Die **Automation-Säule bleibt** unverändert day-1. ## AD-17 — Mobile: PWA-only (v1 + v2), kein nativer Client ✅ (revidiert 16.06.) **Entscheidung (revidiert 2026-06-16):** Mobile läuft **ausschließlich als installierbare PWA / responsive Web** — in v1 **und** v2. Monteur kann auf der Baustelle offline Aufträge bearbeiten, Abnahmen erfassen, Plantafel sehen; alles wird über Service-Worker + IndexedDB-Offline-Queue + Background-Sync gequeued und bei Sync mit „KWP gewinnt" aufgelöst (KWP-Sync = v2). **Kein Expo, kein Capacitor, keine native iOS/Android-App, keine App-Store-Einreichung.** Push = **Web-Push (VAPID)** — aktiviert in v2 den in P1 ruhenden `notify()`-Push-Kanal. Native-App + App-Store → frühestens **v3** (Backlog, nicht beauftragt). **Historie:** 10.05. voller Offline-Betrieb (Capacitor, M167–M171) · 11.06. Capacitor→Expo + native Hülle nach v2 · **16.06. komplett auf PWA-only reduziert** (kein nativer Client in v1/v2; M167–M171 entfallen, „Mobile-App"-Arbeit = PWA-Ausbau: Installierbarkeit, Service-Worker, Offline-Härtung, Web-Push). ## AD-18 — Customer-Portal: voll inkl. Skalierungs-Sicht ✅ **Entscheidung:** Komplettes Portal day-1: Projekt-Sicht + Upload + Reklamation + Subunternehmer-Zugang + Skalierungs-Sicht (Service-Inbox + Routing + Pro-Kunden-Lebensdauer), M141–M146 inkl. [N19]. > **Scope-Muster (historisch):** AD-13/16 wählen den maximalen Umfang → der erste Go-Live ist faktisch > das **vollständige Phase-1-Produkt** in großer Tiefe. Sequenzierung nach AD-11. **AD-17 (Mobile) und > AD-18 (Portal) wurden später revidiert** (AD-18 → v2; AD-17 → PWA-only v1/v2) und folgen diesem Maximal-Muster > nicht mehr. Dies bleibt eine bewusst große Scope-Wahl (siehe Scope-Check in der Session + SCOPE-V1-CUTS.md). ## AD-19 — Go-Live-Modus: Big-Bang ✅ **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 (Fundament → Kernpfad → Breite), aber es gibt kein inkrementelles Produktiv-Schalten einzelner Module für Geerkens. **Bewusst akzeptiert:** längste Zeit bis zum ersten echten Nutzer-Feedback, höchstes „am-Alltag-vorbei"-Risiko. **Gegenmaßnahme empfohlen:** Noah/Geerkens-Validierung pro Modul über den PROGRESS-TRACKER-Klick-Pfad (READY-TO-VERIFY → Sign-Off) als Feedback-Ersatz vor dem Big-Bang. ## AD-20 — Projekt-zentrisches CRM/Pipeline-Modell ✅ (NEU 2026-06-13) **Entscheidung:** Das CRM/Pipeline-Modell wird **Projekt-zentrisch** (auf Basis von Davids UX-Briefing, voll adoptiert). Statt getrennter Deal- und Project-Entitäten gibt es **EINEN `Projekt`-Kern**, auf den **frei konfigurierbare Pipelines als Views** schauen. „Deal" und „Auftrag" sind nur Pipeline-Namen/-Typen, keine eigenen Objektarten. - **Pipeline = View:** Admin legt Pipelines an/benennt sie, steuert Zugriff (wer sieht), Feld-Sichtbarkeit, Pflichtfelder pro Pipeline/Status und die Statuswerte. Ein Projekt ist genau **einer** Pipeline zugeordnet; `Status` ist pipeline-intern (kein globaler Projektstatus). Nicht sichtbare Felder bleiben im Hintergrund erhalten. - **Lead-Flow:** Lead/LeadInput ist Vorstufe mit Datenpunkt `Weiterverarbeitungsfreigabe` (Ja/Nein/Unklar); bei Freigabe → Vererbung ins Projekt. **Lead → Projekt** (das frühere Lead→Contact-Promotions-Modal entfällt; Kontakt wird separat verknüpft). - **Kontaktmodell:** `Kontakt` ist Oberbegriff mit `Kontakttyp` (Privatperson/Organisation), `Kontaktstatus` (Kontakt/Kunde/Bestandskunde) und `Kontaktart` (Haupt-/Sekundärkontakt als Rolle/Relation). - **Scope-Calls (13.06.):** Abnahme bleibt **v1** als Checklisten/Protokoll-Sub-Area am Projekt (Mängel = Checkliste); Material/Zeiterfassung/Leistungspositionen/Baustelle/Support → v2-Backlog. **Rechnung** = einfaches Sub-Entity am Projekt in v1. KWP-Felder bleiben v2-Sync, v1 nur Feld-Halter. **Warum:** Davids konsolidiertes UX-Modell wird zur Bau-Grundlage gemacht; Raffael richtet die Planung daran aus (statt David einzunormen). Höhere Konfigurierbarkeit (SHK-Betriebe brauchen frei benennbare Pipelines) bei erhaltenem typisiertem Kern. **Betrifft:** AD-2 (revidiert), AD-11 (Kette revidiert), M01–M04, ENTITY-MODEL, ROADMAP P6–P9, REQUIREMENTS, SCREEN-MAP. **Anker:** `.planning/ENTITY-MODEL.md`. ## AD-21 — Prisma: Schema-Folder + Migrations-Disziplin für parallele Branches ✅ (NEU 2026-06-16) **Kontext:** 2 Devs (Raffael + Akeshan) bauen Modul-Phasen parallel in eigenen Branches. Risiko: Kollisionen im Datenmodell und in der Migrations-Historie. **Befund (16.06.):** Prisma **7.8.0**; das Schema ist **bereits als Ordner** organisiert (`prisma/schema/` mit 29 Domänen-Dateien: `core`, `accounts`, `permissions`, `appsEngine`, `email`, `workflows`, `notifications`, `marketingLeads`, `ai` …). Die **Datei-Ebene ist damit gelöst** — Module in verschiedenen Domänen-Dateien kollidieren nicht. Es existieren bereits 153 Migrations (lineare Timestamp-Historie). Connection-URLs in `prisma.config.ts` (Prisma 7): `DIRECT_URL` für Migrate, `DATABASE_URL` via PgBouncer zur Laufzeit. **Verbleibende Risiken:** (1) `core.prisma`/`accounts.prisma` sind der geteilte Kern (Tenant/User/Audit/File/ApiKey/Credential) — gleichzeitige Relations-Edits kollidieren *in dieser Datei*. (2) Zwei Branches mit je `migrate dev` erzeugen divergierende Migrations-Ordner → „applied out of order" beim Merge. **Entscheidung — drei verbindliche Konventionen:** 1. **Ein Modul = eine eigene `prisma/schema/.prisma`.** Neue Modelle **nie** in `core.prisma`/`accounts.prisma`. Diese nur für Relationen zu `Tenant`/`User` anfassen, Rück-Relationsfelder dort minimal halten. 2. **Migrationen erst beim Merge.** Auf dem Feature-Branch mit `prisma db push` iterieren (kein Migrations-File). Die **eine** Migration pro Phase erzeugt der Dev, der zuerst auf `main` merged — Forward-only mit Inverse-SQL als Kommentar (AGENTS.md DoD 28). Tägliche Integration hält Diffs klein. 3. **CI-Gate vor Merge:** `prisma validate` + `prisma migrate status` grün (pre-push-Hook schärfen). **Warum:** Schema-Splittung erledigt die Datei-Konflikte bereits; was bleibt (core-Hotspot + lineare Migrations-Historie) löst Konvention/Disziplin, nicht neue Technik. **Betrifft:** alle parallel gebauten Modul-Phasen (P2–P21, v2), `AGENTS.md` §Prisma-Schema, lefthook pre-push. **Anker:** `prisma/schema/`, `AGENTS.md`. ## AD-22 — GeoIP lokal + IP-Anonymisierung (EXT-12) ✅ **Entscheidung:** Geo-Auflösung von Login-/Session-IPs über eine **lokale GeoIP-Datenbank** (DB-IP Lite Country, CC-BY-4.0, MMDB-Format) statt eines externen Dienstes. Die gespeicherte IP wird **pseudonymisiert** (HMAC-SHA256 mit geheimem Pepper); persistiert wird nur das **Land** (`countryCode`/`countryName`). **Kein** EU-SaaS-Geo-Dienst, **kein** ipstack (US/apilayer, LP-13). **Warum:** - Ein externer Geo-Dienst — auch ein EU-gehosteter — bekäme die Endnutzer-IP (personenbezogen) übermittelt → DPA + Subprozessor (M166) + Latenz + Abhängigkeit. Der **Transfer selbst** ist das Risiko. - Lokale MMDB: Lookup passiert auf unserem Server, **die IP verlässt unsere Infra nie**. Kein DPA, kein Subprozessor. Passt zur Self-Host-Linie (Meilisearch/mCaptcha). **Wofür Geo-IP (Zweck):** „Login aus Land X" + Anomalie „Login aus neuem Land" in der Session-/ Security-Sicht (P2); optionale Analytics-Anreicherung nach Land (Default aus); Feature-Flag-Targeting nach Land. Der HIBP-Breach-Check (EXT-12, `password-policy.server.ts`) ist davon unabhängig und bereits aktiv. **Speicher-/Minimierungs-Regeln:** - IP nie im Klartext: `IpAddress.ip`/`IpAddressLog.ip` speichern `HMAC-SHA256(IP, IP_HASH_PEPPER)`. Der Pepper liegt in den Coolify-Secrets, **nicht** in der DB → ein DB-Leak allein ist wertlos; der Gleichheits-Vergleich („gleicher Client?") bleibt möglich (Pseudonymisierung statt Anonymisierung). - Geo nur Land: `regionCode`/`city`/`zipCode`/`latitude`/`longitude` bleiben leer/null. - Der Blacklist-Abgleich nutzt die Roh-IP nur zur Laufzeit (Security-Liste), persistiert sie nicht im Log. **Provisionierung:** Die MMDB ist ein **Deploy-Artefakt** (nicht im Git), Pfad via `GEOIP_DB_PATH` (Default `./data/geoip/dbip-country-lite.mmdb`); `scripts/update-geoip-db.sh` lädt die Monatsversion. Fehlt die Datei, ist die Land-Auflösung ein No-op (Stub) ohne Fehler. Reader: npm `maxmind` (MIT). **Env:** `IP_HASH_PEPPER` (Secret), `GEOIP_DB_PATH` (optional). **Folge-Arbeit (offen):** monatlicher Worker-Cron (BullMQ) statt Shell-Skript; `IpAddress`/`IpAddressLog` perspektivisch auf Land + Hash-IP eindampfen (Spalten entfernen, sobald Session-Filter/Feature-Flag- Konsumenten umgestellt sind); UI, die bisher die Roh-IP zeigte, auf Land umstellen. **Betrifft:** EXT-12, P2 (Sessions/Security), P21 (DSGVO/Retention), `modules/ipAddress`, `services/auth/password-policy`. **Anker:** `apps/web/app/modules/ipAddress/`, `docs/ARCHITECTURE-DECISIONS.md`. ## AD-23 — Media-Auslieferung: privater Bucket + authentifizierter App-Proxy (kein public-read) ✅ **Entscheidung (2026-06-17):** Hochgeladene Medien werden **nicht** über public-read S3 ausgeliefert. Der Bucket bleibt **privat**; die App liefert Medien über eine **authentifizierte Proxy-Route** aus (Session + Tenant-Scope + Permission), die das Objekt aus dem privaten Bucket streamt bzw. auf eine kurzlebige signierte Download-URL weiterleitet. `STORAGE_PUBLIC_BASE_URL` bleibt leer; der `publicUrl`- Pfad (`RowHelper`/`MediaHelper`/`ApiHelper`, `publicUrl ?? file`) zeigt auf die Proxy-Route. **Warum:** CRM-Medien enthalten Kundendaten/Dokumente — world-readable Buckets sind DSGVO-untragbar (jeder mit der URL käme ohne Auth/Tenant-Check ran). Weg A (public-read) ist damit verworfen. **Für P4 (Files, `AK-P4a/b`) umzusetzen:** - Proxy-Route (z.B. `/media/…` bzw. `/storage/…`) mit Auth + `withTenantScope()` + `withPermission()`, streamt aus dem privaten Bucket oder redirected auf signierte Download-URL (kurze TTL). - `publicUrl` in den Media-Helpern auf die Proxy-Route verdrahten (statt null/rohem Key). - **Genuin öffentliche Assets** (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten, Branding-Logos) können keinen Auth-Proxy nutzen → signierte URLs mit TTL **oder** ein separater `public/`-Prefix mit eng begrenztem public-read. Pro Asset-Typ entscheiden. - DSGVO-Export-Artefakte nutzen bereits signierte URLs (unverändert). **Betrifft:** P4 (Files), EXT-06 (nur Bucket/Infra), `packages/storage`, `apps/web` Media-Helper. **Anker:** AD-8 (Verschlüsselung), `packages/storage`, `apps/web/app/utils/helpers/MediaHelper.ts`. --- ## Phase-0-Pflichten (kein „Entscheid", sondern Voraussetzung — siehe `_SUMMARY.md`) Diese Punkte sind vor der ersten Fachmodul-Umsetzung abzuarbeiten: 1. **Codebase lauffähig halten** (pnpm-Workspace, Apps, Packages, Prisma). 2. **Naming-Drift beheben:** `@hivegrid/*`, `hivegrid-cli`, `HIVEGRID_*`, `hivegrid_*`, `x-hivegrid-*`, `hivegrid.*`, Sidebar-Konvention, falsche AGENTS.md-Pfade (`indexed-entities.ts`, `sidebar.config.ts`). 3. **EU-Sterilisation:** GitHub/Google-OAuth-Reste + `User.githubId/googleId` entfernen. 4. **M00 aktivieren** + 4 echte Neubauten: `logActivity()`/Activity-Stream, Search-`indexed-entities`-Registry, **Subframe-Adapter-Code** (Quer-Voraussetzung für jede UI-Route), Mass-Action-Schutz. 5. **Fehlende Dependencies** ergänzen (PLAN.md teils falsch): `signature_pad`, `browser-image-compression`, `react-grid-layout`, `@dnd-kit` (statt react-beautiful-dnd), `libphonenumber`, `ics`/`ical-generator`, `btree_gist`/`EXCLUDE`-Constraint u.a. ## AD-24 — Prod unter eigenem Hetzner-Account (dediziert, self-contained) ✅ **Entscheidung (2026-06-19, Owner Raffael):** Produktion läuft in einem **eigenen, dedizierten Hetzner-Cloud-Account**, vollständig getrennt von Staging/dev. Topologie — **5 VMs** (fsn1, x86 cx-Linie): - **control** — eigenes **Coolify** + Orchestrierung/Bastion (cx33: 4 vCPU/8 GB) - **web**, **api** (je cx33) - **worker + services** — 5 Worker-Queue-Gruppen + **self-hosted Meilisearch + ClamAV + mCaptcha** (cx43: 8 vCPU/16 GB) - **db** — Postgres + PgBouncer + Redis + Daten-Volume (cx33 + Volume) mCaptcha nutzt die Postgres/Redis der db-VM (eigene DB), keine separate VM. Self-contained: eigene Zentral-Dienste (kein Zugriff aufs Staging-Privatnetz), eigener **DEK-Master-Key** (AD-8) + eigener **S3-Bucket** (`hivegrid-prod`, fsn1), eigenes Coolify. **Ingress (Variante „Cloudflare-Proxy"):** Cloudflare **proxied** vor `app./api./captcha.` (Edge-TLS, DDoS/WAF, Origin-IP versteckt) → **Coolify/Traefik pro Host** (Let's-Encrypt am Origin). `admin.` restriktiv (dns-only + Firewall bzw. Cloudflare Access). **Kein Hetzner-Load-Balancer** bis zur horizontalen Skalierung — die App ist über serverseitige Sessions in Postgres+Redis (AD-4) dafür bereit; LB + 2+ web/api-Instanzen kommen nach Anhebung des VPS-Limits. **Netzwerk:** privates Hetzner-Network + Firewall — `db`/`services` nur privat erreichbar, öffentlich nur 80/443 (web/api/control), SSH eingeschränkt. **Warum:** Blast-Radius/Isolation (getrennte Tokens/Billing, kein Cross-Deploy-Unfall Staging↔Prod), saubere DSGVO-/Audit-Grenze, Crypto-Shredding-Grenze pro Account. Revidiert/erweitert die Infra-ADR-009 (Hetzner+Coolify) um die Account-Trennung. **Grenzen:** Hetzner-Default-Limit 5 VPS/Projekt → echtes HA (web1/web2 + api1/api2 hinter LB) erst nach Limit-Anhebung (Support). Provisionierungs-Schritte + Go-Gates: `docs/ops/prod-rollout-hivegrid.md`. **Betrifft:** Prod-Deploy, Ops, alle Module. ## AD-25 — E-Signatur: gehärtete SES-Eigenbau, kein externer Provider (v1); QES-Add-on via DE-QTSP (v2) ✅ (NEU 2026-06-21) **Entscheidung (2026-06-21, Owner Raffael):** HiveGrid baut die elektronische Signatur (Angebote/Aufträge/Abnahmen) für v1 **selbst als gehärtete SES** und macht das zum **Default für alle Tenants** — **kein externer Provider als Zwang**. **PandaDoc bleibt als optionale BYOK-Anbindung** erhalten: Tenants mit eigenem PandaDoc-Account tragen ihren **eigenen API-Key** ein und signieren über *ihren* Account (Opt-in). Damit ist die Annahme „PandaDoc ist der *zentrale/erzwungene* Provider" abgelöst (Abweichung vom Pflichtenheft V.4.4), PandaDoc selbst aber **nicht** — es wird vom Default zum **Opt-in-Adapter**. Betrifft AK-P16d, EXT-09, EXT-17, VR-P16. **BYOK-Vorteil (CLOUD Act):** Bei BYOK nutzt der Tenant bewusst seinen *eigenen* PandaDoc — die CLOUD-Act-/Drittland- Verantwortung liegt damit beim Tenant (dessen Account, dessen Entscheidung), nicht bei HiveGrid. Das „100 % EU"- Default (SES-Eigenbau) bleibt unangetastet; PandaDoc ist eine transparente Opt-in-Wahl (Subprozessor-Liste/AVV). **Begründung (dreifach belegt):** - **Rechtlich:** SHK-Dokumente sind formfrei oder Textform (§§ 631, 650i Abs. 2, 640 BGB) → **SES genügt** (auch beim Verbraucherbauvertrag, der nur Textform verlangt — keine QES). Einziger zwingender QES-Fall im ganzen SHK: **Kündigung eines Bauvertrags (§ 650h BGB)** — kein Tagesgeschäft, selten. - **Praxis:** Marktstandard im DE-Handwerk ist die **SES-Touch-Unterschrift vor Ort** (+ Fern-Link). Alle etablierten Tools (HERO, plancraft, Craftnote, ToolTime …) bieten SES; AES/QES spielt im Tagesgeschäft keine Rolle, **kein Marktdruck**. Wettbewerbsfaktor ist der Prozess (papierlos → schneller zur Rechnung), nicht die Stufe. - **Souveränität:** PandaDoc/DocuSign = US-Firmen → **CLOUD Act §2713**, bricht das „100 % EU"-Versprechen (A.12.4). EU-Provider geprüft (Yousign FR am besten; Skribble CH hat US-Subprozessoren/kein echtes Embedding/per-Seat). OSS geprüft (Documenso = nur SES + AGPL). **Eigenbau ist souveränster + günstigster + rechtlich ausreichend.** **Umsetzung v1 (P16 / AK-P16d) — „gehärtete SES" (praktisch auf AES-Beweisniveau, ohne PKI-pro-Person/QTSP):** 1. **Touch-Signatur vor Ort** (Canvas → PDF) + **Fern-Link-Signatur** (Angebot remote annehmen) 2. **OTP-Identifizierung** (E-Mail; SMS als stärkere Zwei-Kanal-Variante) 3. **PDF-Versiegelung** (PAdES mit HiveGrid-Organisations-Zertifikat → jede Änderung bricht die Signatur) 4. **Zeitstempel** (TSA, RFC 3161; nicht-qualifiziert genügt für SES/AES) 5. **Audit-Trail** über M001 (Link/Öffnen/OTP/Signatur: wer, wann, IP, Gerät, Geo, PDF-Hash; append-only) 6. **Completion-Certificate** als PDF-Anhang (sichtbare Beweis-Doku) 7. **Einmal-Link** (personengebunden) + expliziter **„Intent to sign"** > Beweiskraft: gehärtete SES wie AES unter freier Beweiswürdigung (§ 286 ZPO) — der Audit-Trail trägt, nicht das Stufen-Etikett. Anscheinsbeweis (§ 371a) hat nur QES. **Architektur:** Signatur über `defineAdapter` (Apps-Engine, provider-agnostisch). Adapter: - **`ses-selfhosted`** — Default (v1), die gehärtete Eigenbau-SES. - **`pandadoc-byok`** — optional (v1), Tenant bringt eigenen PandaDoc-API-Key (DEK-verschlüsselt im Credential-Store); Mandanten-Trennung via eigener Account + Webhook-Routing (pro-Tenant-URL + `metadata.hivegrid_tenant_id`). Anbindungs-Spec: [[EXT-17]]. - Spätere Optionen ohne Fachcode-Umbau: **AES** (Yousign managed oder EU-DSS-Library self-hosted, Java-Sidecar), **QES** (DE-QTSP **D-Trust sign-me**, Hash-only — Dokument bleibt im Perimeter) für § 650h-Bauvertragskündigung. **Betrifft:** P16 (AK-P16d), EXT-09 (SES-Eigenbau-Default), EXT-17 (PandaDoc-BYOK-Adapter), VR-P16. PandaDoc bleibt als BYOK-Opt-in. Vor Produktivschaltung der Signatur: anwaltliche Bestätigung der Form-/Beweis-Einordnung (SES genügt, § 650h→QES). **Pflichtenheft-Status (Pivot-Vorrang):** Abweichung von **V.4.4** (PandaDoc als zentraler/erzwungener Signatur-Provider) sowie von den Phase-1-App-Listen in Block 4 (33a.1.1 / 33a.1.4 / 33a.2.3). **Change-Request gegen das Pflichtenheft nötig (M176)**; bis dieser eingepflegt ist, gilt **AD-25 vor dem Pflichtenheft** (Pivot-Vorrang, analog AD-20/AD-26). PandaDoc bleibt in den Listen, wechselt aber vom *Default* zum *Opt-in-Adapter*. **Offen (mit M176):** Pivot-Hinweis an der V.4.4-/PandaDoc-Stelle im Pflichtenheft + Aufnahme in die CR-Liste. ## AD-26 — KI-Pivot: MCP-only, kein selbst-gehostetes LLM/RAG (löst die KI-Hälfte von AD-16 ab) ✅ (NEU 2026-06-22) **Entscheidung (2026-06-22, Owner Raffael):** HiveGrid hostet **kein** eigenes LLM/RAG/HiveMind mehr. Statt eine KI-App zu sein, wird HiveGrid **KI-anschließbar** über einen **MCP-Server** (Model Context Protocol): externe KI-Clients (Claude Desktop/Cursor/ChatGPT) docken an, **Inferenz liegt beim Client**. Damit entfällt der EU-LLM-Provider-/DSGVO- Zwang für HiveGrid selbst (kein Mistral/Scaleway/AlephAlpha-Hosting mehr). Löst die **KI-Hälfte von AD-16** ab — die **Automation-Säule bleibt**. **Begründung:** Kleines Team; der teure/harte Teil (LLM-Hosting, RAG-Infra, Promptfoo-Eval, AiCredits-Abrechnung, EU-Provider-Compliance) fällt weg. MCP nutzt **dieselbe mandanten-gescopte Daten-/Aktions-Fläche** wie die geplante Public-API ([[VR-P22a]]/[[VR-P22b]]) → keine Doppelarbeit. **v1 (KI komplett gestrichen):** R-P13 (KI-Layer/Mistral-Gateway) + D-P13 entfernt, EXT-11 + Mistral-Key gelöscht, Milestones **M083–M088 gelöscht**, R-P12b verliert den Sprach→Automation-Teil (bleibt reiner visueller Flow-Editor). Neues letztes v1-Glied = R-P12b (~1 Tag Puffer → Härtung). Freeze/Launch **09./10.07.** bleiben fix. **v2:** VR-P25/VD-P25 (HiveMind/RAG/Whisper) **gestrichen** (Plane: Cancelled) → neu **VR-MCP + VD-MCP** im Slot **18.–20.07.**, `blocked-by` VR-P22a/b (Public-API, fertig 17.07. → kein Konflikt). **Public-API-/MCP-Surface (2026-07-03, verbindlich):** Public API läuft ausschließlich auf `api.hivegrid.de` (staging: `staging-api.hivegrid.de`) mit Versionierungs-Prefix `/v1/...`; es gibt keine Public-API-Routen unter `app.hivegrid.de/api`. MCP läuft ausschließlich auf `mcp.hivegrid.de` (staging: `staging-mcp.hivegrid.de`) als eigener Coolify-Service/Container `hivegrid-mcp` mit eigener Runtime (`apps/mcp`), ohne zusätzlichen `/mcp`-Pfad. Auth/Scopes/Rate-Limit werden aus der Public-API-Schicht wiederverwendet, aber die Runtime-/Host-Surface bleibt getrennt. **MCP-Design (Best-Practice, MCP-Spec-Rev 2025-11-25):** Remote-Server über **Streamable HTTP** (stateless Start), SDK **`@modelcontextprotocol/sdk`**. **Auth v1 = OAuth 2.1 Authorization Code + PKCE** mit Protected-Resource-Metadata (RFC 9728), Authorization-Server-Metadata (RFC 8414), Resource-/Audience-Bindung und Consent. API-Key-Bearer aus VR-P22 bleibt nur als Operator-/Fallback-Pfad, nicht als primärer User-Connect-Flow. **Tenant aus dem Token** (nie aus Tool-Argumenten) → `withTenantScope()` + RLS. **Read-Tools + Write-Tools** (`withPermission()` + Client-Confirmation + `auditEvent`/`logActivity`). Annotations (`readOnlyHint`/`destructiveHint`) nur als Hint — echte Guards serverseitig. Rate-Limit + Output-Limits + Pagination; Tenant-Daten sind **Daten, nie Instruktionen** (Prompt-Injection). **Code-Rip-out (Variante a):** raus = `packages/ai`, `packages/vector-store`, Module ai/ai-gen/ai-cost/chatbot/ ai-elements, AI-Routen, Worker-AI-Jobs, `ai.prisma` — UND die Legacy-PromptFlow-Engine (promptBuilder/admin/prompts/ `promptFlows.prisma`). **Bleiben:** `@modelcontextprotocol/sdk`, `modules/mcp/`, der EU-Sterilisations-Guard. **Pflichtenheft:** A.12.3 (EU-LLM-Provider) und V.2.2 („KI als Bedienoberfläche der Automation") widersprechen jetzt → **Change-Request (M176) nötig**; bis dahin gilt diese AD vor dem Pflichtenheft (Pivot-Vorrang). Anti-Liste V.3.2.7 (HiveMind autonom) bleibt erfüllt (wird gar nicht gebaut). **Betrifft:** R-P13/D-P13/EXT-11/M083–M088 (entfernt), R-P12b (Trim), VR-P25/VD-P25 (gestrichen), VR-MCP/VD-MCP (neu), R-P11a/R-P11b/D-P3/R-P5/D-P5/D-P20 (KI-Andock umdeuten/trimmen), VA-P24b/VA-P29/VR-P31/VR-P33 (KI-Teile entfallen). ## AD-27 — Billing-Recut: Lago self-hosted + Mollie Payments, kein Legacy-Provider-Default ✅ (NEU 2026-07-04) **Entscheidung (2026-07-04, Owner Raffael):** HiveGrid nutzt **kein Legacy-Provider** als Billing- oder Payment-Default, weil kein relevantes CLOUD-Act-Risiko in der zentralen Billing-Abhängigkeit akzeptiert wird. Billing wird in drei Schichten getrennt: 1. **HiveGrid** bleibt Produkt- und Zugriffsschicht: Tenants, Seats, Plan-Status, Feature-Gates, Read-only/Frozen-State. 2. **Lago self-hosted** wird Billing-Engine: Plans, Seats, Subscriptions, Invoices und Billing-Status. 3. **Mollie** wird v1-Payment-Processor: Checkout/Zahlung, Payment-Status, Refund-/Failure-Events. Mollie wird **nicht** zur Billing-Source-of-Truth und nicht fuer Invoicing genutzt. **v1-Scope:** nur **Plans + Seats**. Kein Usage-Billing, keine Credits, keine Add-on-Metering-Logik, keine oeffentlichen Preisversprechen im Code. Bestehende Usage-/Quota-Felder duerfen als technische Altlast bleiben, werden aber nicht als neuer Billing-Scope erweitert. **Invoicing:** Lago erzeugt die fachliche Rechnung/Invoice-Records. Rechnungssteller und finale Rechnungs-/Steuerlogik werden entschieden, wenn die rechtliche/gesellschaftliche Struktur feststeht. Bis dahin bleibt die Umsetzung auf technisches Invoicing + Testdaten begrenzt. **Infrastruktur:** - **Staging:** eine geteilte `lago-staging`-Instanz im Estate-Coolify auf `node1-estate`, aktuell intern erreichbar. Mehrere Staging-Services koennen dieselbe Instanz nutzen, solange Testkunden/Plans sauber ueber Codes/Metadata getrennt werden. - **Production:** bekommt spaeter eine eigene `lago-production`-Instanz im HiveGrid-Prod-Setup. Staging und Prod werden **nicht** in derselben Lago-Instanz gemischt. - Lago bleibt als separater Service angebunden. Keine Lago-Core-Patches im HiveGrid-Repo. Falls Lago-Code angepasst werden muesste, ist wegen AGPL-3.0 vorher Legal-/Lizenz-Entscheidung oder Commercial-License-Pfad erforderlich. **Payment-Minimierung:** Mollie erhaelt nur Billing-/Payment-Minimum: Customer-Referenz, Invoice-Referenz, Betrag, Zahlungsmethode und noetige Kontaktdaten. HiveGrid-Fachdaten, CRM-Inhalte, Projektinhalte und MCP-Daten werden niemals an Mollie oder Lago gesendet. **Abgeloeste Annahmen:** Die aktiven Billing-Ticketdocs wurden in `BILL-00` auf Lago/Mollie recuttet. Alte Legacy-Provider-Erwaehnungen in historischen Umsetzungsnotizen, Roadmap-/Milestone-Alttexten oder Legacy-Code sind Migrationsinventar und duerfen nicht als Zielarchitektur gelesen werden. **Betrifft:** AK-P20, D-P20, VA-P24a/b, VD-P24, AK-P19, AK-P21, EXT-07, EXT-16, H-PAYLINK, R-P1b/Feature-Gates. ## AD-28 — Interim-UI: Dev baut Vorschau-Screens aus `~/ui`, finale Optik wird getrackter Nachzug ✅ (NEU 2026-07-04) **Entscheidung (2026-07-04, Owner Akeshan + Raffael):** UI-lastige Dev-Tickets bleiben **nicht** bis zu Davids finalem Screen-Delta auf „On Hold". Stattdessen baut der Dev eine **Interim-UI** (Vorschau-Screen) aus den bereits im Repo gesyncten Subframe-Components (`apps/web/app/ui/`, Alias `~/ui/*`) und stellt das Ticket damit fertig. Präzisierung der Done-Definition für solche Tickets: Ein Ticket ist **Done-fähig**, sobald **Dev-DoD 100 % + Interim-Screen aus `~/ui` (VM als Prop, kein handgeschriebenes Tailwind) + Tests grün** sind. Die **finale Subframe-Optik** ist dann **kein Done-Blocker** mehr, sondern ein **getrackter Nachzug** (Plane-Label `design-nachzug` + „Dev-Nachzug"-Sektion der Ticket-Doc + Interim-Visual-Baseline, die beim Nachzug neu gezogen wird). **Goldene Regel:** Interim-Screens werden aus `~/ui`-Components + `~/ui/layouts/*` komponiert und beziehen ihre Daten aus dem bestehenden View-Model (`packages/view-models/**`). Handgeschriebenes Tailwind statt `~/ui` ist ein PR-Block — nur die `~/ui`-Komposition hält den späteren Tausch gegen Davids Screen billig (Component-Swap hinter stabiler VM/Loader-Grenze, Hot-Swap-Gedanke M015/M017). Die drei Anti-Patterns und die Layer-Trennung (Abschnitt „Drei Anti-Patterns") bleiben unangetastet. **Warum:** Davids Screens dauern noch lange, während die Component-Basis (79 `~/ui`-Components + Layouts, gesynct via `.subframe/sync.json`) und die View-Models bereits stehen. Die Designer-first-Reihenfolge bleibt erhalten — David überschreibt/finalisiert weiterhin —, aber Backend-Tickets werden nicht länger formal von leeren `D-*`-Deltas blockiert. Begriff „Interim-UI" ist bewusst von `packages/ui-mock` (M017-Hot-Swap-Drop-in) abgegrenzt. **Betrifft:** alle UI-lastigen Dev-Tickets v1+v2 (Akeshan + Raffael), u. a. R-P2/P8/P9/P11/P12, AK-P3/P4/P14/P16/P17/P19/P20/P21, VR-P22b, VR-MCP; sowie den `plan-ticket`-Command und die Designer-first- Regel in `.planning/ticket-docs/README.md`. **Anker:** `.planning/INTERIM-UI-PLAYBOOK.md` (ausführliches Wie) · `.planning/INTERIM-UI-DESIGN-STANDARDS.md` (Davids Layout-/Komponenten-/State-Werte als In-Repo-Spiegel von `../HiveGrid-Wireframes/`, damit die Interim-UI nah an Davids finalen Screens landet) · `.claude/commands/plan-ticket.md` (§4/§5/§8) · `AGENTS.md` (Ein Ticket bauen + DoD) · `docs/INTEGRATION-CONTRACTS.md` (§12) · `.planning/ticket-docs/README.md` (Konvention „Dev-Nachzug"/Interim-UI-Vermerk). ## AD-29 — Rollen-Seed: Produktion startet admin-only, SHK-Seeds nur Staging/Dev ✅ (NEU 2026-07-07) **Entscheidung (2026-07-07, Owner Akeshan):** Auf **Produktion** startet ein frischer Tenant nur mit der **Admin-Systemrolle** — die 6 SHK-Standard-Rollen (Geschäftsführer, Projektleiter, Verwaltung, Vertriebler, Kundensupporter, Monteur; Partner-Liste 2026-06-19) werden dort **nicht** mehr automatisch geseedet. Auf **Staging/Dev** bleiben die SHK-Seeds als Test-Komfort aktiv. Damit ist der Widerspruch zwischen dem R-P2b-Seed (Owner-Entscheidung Raffael) und Davids validierter D-P2-Design-Entscheidung („zum Start nur die Systemrolle Admin, keine vorgebauten Seed-Rollen") zugunsten des Designs aufgelöst; die SHK-Liste bleibt als Definition erhalten (perspektivisch Rollen-**Vorlagen**, Davids WIP-Konzept in M04A). **Mechanik:** Gate `shouldSeedShkRoles()` in `apps/web/app/utils/services/shkRoles.server.ts` — `SENTRY_ENVIRONMENT=production` ⇒ kein Seed. Bewusst die **deploy-scoped** Variable (Estate-Standard §1), weil `NODE_ENV` auf Staging-Containern ebenfalls `production` ist; lokal (ohne `SENTRY_ENVIRONMENT`) entscheidet `nodeEnv`. Override in beide Richtungen per `SEED_SHK_ROLES=true|false`, falls der Partner die Seeds produktiv doch will. Die übrige Auto-SHK-Provisionierung (AK-P20: Pipelines, Custom-Felder, Form-/Projekt-Templates, Checkliste) ist **nicht** betroffen — nur der Rollen-Seed. **Betrifft:** R-P2b (DoD „6 SHK-Rollen geseedet" gilt Staging/Dev), AK-P20 (`provisionShkTenantDefaults` ruft den Rollen-Seed weiter auf, er no-opt auf Prod), D-P2/S02 (Rollen-Liste zeigt auf Prod initial nur Systemrollen), `REQUIREMENTS.md` REQ-auth-rbac, `ROADMAP.md` Phase-2-SC 4. ## KWP (separater Strang — siehe `_bmad-output/specs/M19-kwp-integration.md` und `docs/milestones/M19-KWP-API-RECUT.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.