Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/archive/handoffs/HANDOFF-2026-05-24.md
T

14 KiB

Handoff — Stand 2026-05-24

Historical snapshot only (2026-05-25 cleanup). This file is preserved for audit/history. Do not treat its "start", "push", "deploy" or operator instructions as current work. Use PROGRESS.md, OPERATOR-CHECKLIST.md and the latest session notes for live status.

Vorgänger-Agent: Claude Opus 4.7 (1M context) Letzte aktive Session: Bucket-1-Abbau + komplett-neue zentrale Observability/Sentry/Meilisearch/Loki-Infrastruktur. Viele Änderungen in der toolctrl-labs/infra-Repo (separates Gitea-Repo, NICHT der Boilerplate). Ziel des Handoffs: Nachfolger weiß in 5 Minuten wo wir stehen und was als Nächstes kommt.


0. Start hier (5-Minuten-Onboarding)

Lies in dieser Reihenfolge:

  1. Dieses Dokument komplett.
  2. HANDOFF-2026-05-21.md für den davor liegenden archivierten Stand (#72-i18n + Lighthouse-CI-Rebuild + Worker-Crash-Fix).
  3. Wichtig: das toolctrl-labs/infra-Repo auf Gitea. Die ganze zentrale Infra (Observability, Sentry, Meilisearch, Loki, WireGuard-Mesh) ist DORT dokumentiert, nicht im Boilerplate. Clone via git clone https://git.tool-ctrl.de/toolctrl-labs/infra und lies README.md + STANDARDS.md.
  4. .claude/CLAUDE.md — React-Router-v7-Konventionen, strikt enforced.

Sofort-Sanity-Check:

git log --oneline -6                 # HEAD = fa8b0e70, dahinter 1-2 lokale doc-commits dieser session
git status -s                        # erwartet: packages/db/generated/** churn + ggf. neue handoff/progress edits
git pull --rebase --autostash        # andere Agenten arbeiten ggf. parallel

Lokale unpushed Commits beachten: Schon zu Session-Start lagen 2 Commits vor (a3885ed5 Namespace-Split, fa8b0e70 E2E-Locale-Switch für #72) die noch nicht auf origin/main sind. Plus die Doc-Edits dieser Session (PROGRESS.md + neues Handoff). Wenn du pushst, deployt Coolify automatisch — bei Doc-Only-Edits unkritisch, aber bewusst entscheiden.


1. Was diese Session bewegt hat

1.1 Bucket-1-Abbau (Operator-Pending-Items)

Item Vorher Jetzt
#41 Read-Replica „replica-deploy-pending" als bewusst zurückgestellt dokumentiert (Single-DB-Fallback aktiv, kein Funktionsverlust)
#78 Turnstile nicht aufgesetzt live aufgesetzt + per Negativ-Test verifiziert. Sicherheits-Fazit: aktuell nicht zwingend nötig weil keine öffentlichen Landingpages, aber Backend ist live
#51 CDN historical rollout parked backlogged — Origin in Nürnberg + DACH-Audience + Cloudflare-Proxy reicht. Reaktivieren wenn internationale Kunden / große Media / Traffic-Spitzen
#56 Stripe-Meter „stripe-account-setup-pending" deferred — noch keine zahlenden Overage-Kunden
B3 (bcrypt-rehash) nie live getestet verifiziert — Login als staging-admin@saas-ctrl.com hat den Hash sauber von bcrypt auf argon2 umgesprungen. Dual-Mode-Code aus #28 funktioniert
B5 Disk-Alert „operator-config-pending" erledigt — Coolify-Discord-Webhook aktiviert, Disk-Trigger an
#23 Plugin Phase 3 (Cure53) „operator-audit-pending" deferred — Budget aktuell nicht da. Konsequenz im PROGRESS-Row notiert: Plugin-System geht NICHT in Produktion bis Audit + Sign-off durch sind

1.2 Zentrale Infrastruktur neu aufgebaut

Was es vorher gab: je Projekt eigener Side-Stack (Grafana+Prometheus auf Staging, Sentry auf Staging, Meilisearch auf Staging). Skalierte nicht für mehrere SaaS.

Was jetzt steht:

  • WireGuard-Mesh 10.42.0.0/24 mit control als Hub, Peers homeserver (10.42.0.2), boilerplate-staging (10.42.0.3), node1/EX44 (10.42.0.4). IP-Forwarding und FORWARD-Chain auf control eingerichtet. ADR 008 im infra-Repo.
  • Zentrales Grafana + Prometheus auf control unter https://grafana.saas-ctrl.com. Scrapt jede Host-Node-Exporter + Docker-Stats-Exporter über das Mesh. Vier Project-Dashboards (Boilerplate, saas-ctrl.com, Homeserver, Hetzner Dedicated EX44). Admin-Pass auf control:~/.cli-tokens/central-grafana-admin.
  • Zentrales Sentry auf node1/EX44 unter https://sentry.saas-ctrl.com. Self-hosted Sentry-Stack hinter Caddy (TLS via Let's Encrypt). Org sentry, Team boilerplate mit Projekten api/worker/web. Boilerplate-Coolify-Envs zeigen auf neue DSNs + OTEL-Endpoint. SENTRY_AUTH_TOKEN rotiert in Coolify + Gitea-Secrets. Admin-Pass auf control:~/.cli-tokens/central-sentry-admin, DSNs unter central-sentry-dsns, Auth-Token unter central-sentry-auth-token. Altes Sentry auf Staging läuft noch — bewusst stehen gelassen, kann jetzt aber abgebaut werden, frisst ~4 GB RAM.
  • Zentrales Meilisearch auf node1/EX44 auf 10.42.0.4:7700. Boilerplate-Apps zeigen via Coolify-Env auf den neuen. Alter Container auf Staging gestoppt + entfernt, Volume zur Sicherheit behalten. Master-Key auf control:~/.cli-tokens/central-meilisearch-master-key. Beide Instanzen waren leer beim Switch — niemand hatte auf Staging je Daten geschrieben die in Meili landen würden.
  • Zentrales Loki + Promtail auf jedem Host. Loki auf EX44 10.42.0.4:3100, Promtail auf allen vier Hosts schickt Container-Logs hin. Als Grafana-Datasource registriert. In Grafana → Explore → Loki auswählen → {server="..."}-Queries möglich.

Wichtige Lesson learned: Docker port-publishing (-p 10.42.0.4:7700:7700) mit UFW + Docker-iptables auf EX44 funktioniert NICHT für Traffic von wg-Peers. Mittel zur Wahl auf EX44 ist --net=host plus explizites Binding auf die Mesh-IP. Pattern in infra-Repo dokumentiert.

1.3 Infra-Repo toolctrl-labs/infra massiv erweitert

Pushes: 69636e7, 6d26a84, dcf8ca1, 174b9a9 auf main.

  • README.md — neue Sektionen: Central observability, WireGuard mesh, Central Sentry, Central Meilisearch, Central logs (Loki). Hosts-Übersicht aktualisiert (node1 hat jetzt Sentry, boilerplate-staging hinzugefügt, control hat zentrale Stacks). DNS-Records für grafana.saas-ctrl.com + sentry.saas-ctrl.com.
  • STANDARDS.md (neu) — verpflichtende Regeln für jeden SaaS im Estate. 11 Sections: zentrale Sentry-Nutzung, Host-Pflicht (Metrics+Logs), Per-Project-Dashboard, zentrale Meilisearch, Admin-SSO über Authentik, Repos in Gitea, Coolify-Konventionen, Cloudflare, Secrets, Backups, ADR-Norm.
  • decisions/008-central-observability-and-sentry.md (neu ADR) — begründet zentrale Architektur + WireGuard-Mesh (revisiert ADR 004).
  • runbooks/add-host-to-central-observability.md (neu) — Schritt-für-Schritt für neuen Host ans Mesh + Exporters + Prometheus-Targets.

2. Was JETZT als Nächstes zu tun ist

Sofort sinnvoll, Bucket-1-Restposten:

B7 — Tenant-Snapshot-Verify ist der einzige Bucket-1-Punkt der noch echt offen ist und den ein Agent ausführen kann. ABER hat zwei Hürden die vorher gelöst werden müssen:

  1. Die toolctrl-cli ist nicht im Production-Image — auf Staging müsste der Repo geklont und Dependencies installiert werden, oder ein dediziertes CLI-Image gebaut werden.
  2. S3/MinIO ist auf Staging nicht installiert. Entweder ein MinIO-Container dazustellen oder ein lokales Filesystem-Backend für die CLI nutzen (falls supportet).

Empfehlung: MinIO auf Staging hinzufügen ist ein 20-Minuten-Job (analog zum Meilisearch-Pattern auf EX44, Host-Network mit Mesh-IP-Bind), dann CLI aus den Repo-Sources laufen lassen, snapshot+restore round-trippen, Row-Counts vergleichen.

Worker-Groups-Side-Finding (superseded) — historical 2026-05-24 note: at that point staging only ran the general worker group. This was closed by the 2026-05-25 persistent worker-group provisioning; the current staging topology is five separate Coolify worker services (general, mail, import, webhook, plugin). See docs/ops/worker-queues.md and docs/improvement-plan/archive/STAGING-ACCESS.md.

Bucket 2 — Code fertig, nur Live-Verifikation

# Task Was zu tun
#19 Magic-Link-Reset Core flow + MailerSend smoke live-grün: token issued, queued, temporary mail worker completed provider send, consumed, replay rejected. 2026-05-25 addendum: persistent Coolify worker-group provisioning landed; B-014 resolved and #19 closed.
#26 TOTP-MFA Erledigt 2026-05-24: MFA-Enroll + TOTP-Challenge + Recovery-Code-Challenge + Cleanup auf Staging grün.

Bucket 3 — wartet auf Externe

# Task Was hängt
#23 Plugin Phase 3 Cure53-Audit budget-deferred (siehe oben). Wenn Geld frei wird: scripts/build-plugin-audit-package.sh + Versand an Cure53 (oder Alternativvendor)
#65 Capacitor Mobile Native Builds brauchen Mac+Xcode+Android-Studio. App-Store + Play-Store Submission. Apple Dev Account ($99/Jahr) + Google Play Console ($25 einmalig)

Bucket 4 — echte Code-Arbeit, die großen Tracks

Kleine deferrte Follow-ups (je < 1 Tag):

  • #20 Magic-Link-Invitation — User.passwordHash-nullable-Migration
  • #27 Password-Policy — Login-Soft-Banner
  • #39 Pub/Sub Cache — Reconnect-Flush + Testcontainers-Integrationstest

Großtracks (ein Track pro fokussierter Session):

  • #38 Shared-Store: Session-Store sync→async — 2-3 Tage, höchstes Risiko, eigene saubere Session zwingend
  • #42 Outbox completion — ~1 Woche, Call-Site-Migrationen + Admin-UI + CLI re-queue + E2E
  • #53 Feature-Flag-Builder — Visual Rule-Builder-UI + Affected-Count-Endpoint + Kill-Switch + 4 v1-Callsites
  • #55 AI-Cost Phase 2 — Admin- + Tenant-Web-UIs (Engine fertig)
  • #59 Realtime-Collab — Snapshot/Cleanup-Cron + Presence-Bar-UI + Permission-Helper + Rows-/Workflow-Editor-Integration
  • #21 + #22 Plugin Phase 1+2 — Hot-reload, Marketplace, sandboxed iframe, weitere 13 Hook-Points (NICHT prod-rollen ohne Cure53-Audit)
  • #62 Storybook — Lost-Pixel Visual-Regression, Toolbar-Globals, Tailwind-v4-Pipeline
  • #73 WCAG P2 — no-autofocus (88) per Einzelfall-Urteil; verify-a11y-baseline.mjs muss vorher repariert/erstellt werden
  • #76 Test-Coverage — Per-Modul-Gates auf 85-95% kritische Pfade hochziehen
  • #17 FileObject-Scan-Columns — von Bucket 1 reklassifiziert als echtes Code-Work: Scan-Spalten am FileObject-Model fehlen komplett, plus Scan-Result-Persistenz + User-Notification + Audit-Events sind nicht gebaut. Detail-MD 01-tech-debt-foundation/av-scanner-layer-2.md ist Wahrheit, der Status-String im PROGRESS war irreführend

Housekeeping (lose Enden dieser Session)

  • Altes Sentry auf Staging stoppen — boilerplate-staging:/opt/sentry-stack/ läuft weiter und frisst ~4 GB RAM, obwohl alle Apps schon zum neuen umgelenkt sind. Wenn Verifizierung gesehen wurde dass das neue stabil ist, alten Stack mit docker compose down runterfahren. Volume bewusst behalten falls Rollback nötig.
  • 2 unpushed #72-Commits auf Boilerplate (a3885ed5, fa8b0e70). Beide sind sauber, wurden aber nie gepusht. Wenn du sie weghaben willst, einfach git push.
  • PROGRESS.md hat in dieser Session 3 Doc-Edits bekommen (#41/#51/#23 Status-Deferrals). Auch noch nicht committed/gepusht. Ich committe sie zusammen mit diesem Handoff.
  • Coolify-Env-Duplikate — Coolify's API erzeugt mit PATCH neue Einträge statt zu updaten. Auf den 3 Boilerplate-Apps liegen ein paar duplizierte Envs (z.B. SEED_ADMIN_EMAIL/SEED_ADMIN_PASSWORD). Funktional fängt Coolify den letzten Wert ab, kosmetisch unsauber. Bei Gelegenheit über die Coolify-API per DELETE aufräumen.
  • Marketing-VM ist noch nicht im zentralen Monitoring. Kein SSH-Key registriert. Wenn das in den Mesh soll: Runbook in der infra-Repo unter runbooks/add-host-to-central-observability.md.

3. Konventionen (unverändert, aber wichtig)

  • Alle Commits direkt auf main. git pull --rebase --autostash vor Workflow-Start.
  • Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full pnpm typecheck, ~50s) sind hart.
  • React Router v7: Route-Type-Imports IMMER ./+types/<name>, nie relativ.
  • Niemals git add -A — explizite Paths. packages/db/generated/** niemals mitcommitten.
  • pnpm, nicht npm. Tests via npx vitest run <path>.
  • Co-Author-Trailer: Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
  • Push deployt auto via Coolify auf Staging.
  • NEU: Wenn etwas Infra-mäßig ist, gehört es ins separate toolctrl-labs/infra-Repo, nicht ins Boilerplate. Boilerplate-Repo ist nur für die SaaS-Codebase.

4. Operator-Profil-Notiz

  • B2B-SaaS, SEO irrelevant (alte Note bleibt gültig)
  • Antwortstil: kurz, plain, keine Tabellen-Wände, keine Emojis, keine inline-Code-Formatierung für Dinge die nicht Code sind (Pfade, URLs, Env-Var-Namen als Fließtext). Ein Item nach dem anderen abarbeiten, nicht alle Buckets gleichzeitig dumpen.

Ende des Handoffs. Bei Unklarheit fragen, nicht raten.