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.mdand 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:
- Dieses Dokument komplett.
HANDOFF-2026-05-21.mdfür den davor liegenden archivierten Stand (#72-i18n + Lighthouse-CI-Rebuild + Worker-Crash-Fix).- 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 viagit clone https://git.tool-ctrl.de/toolctrl-labs/infraund lies README.md + STANDARDS.md. .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/24mitcontrolals Hub, Peershomeserver(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
controlunterhttps://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 aufcontrol:~/.cli-tokens/central-grafana-admin. - Zentrales Sentry auf
node1/EX44 unterhttps://sentry.saas-ctrl.com. Self-hosted Sentry-Stack hinter Caddy (TLS via Let's Encrypt). Orgsentry, Teamboilerplatemit Projektenapi/worker/web. Boilerplate-Coolify-Envs zeigen auf neue DSNs + OTEL-Endpoint. SENTRY_AUTH_TOKEN rotiert in Coolify + Gitea-Secrets. Admin-Pass aufcontrol:~/.cli-tokens/central-sentry-admin, DSNs untercentral-sentry-dsns, Auth-Token untercentral-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 auf10.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 aufcontrol:~/.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:
- Die
toolctrl-cliist nicht im Production-Image — auf Staging müsste der Repo geklont und Dependencies installiert werden, oder ein dediziertes CLI-Image gebaut werden. - 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.mjsmuss 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-MD01-tech-debt-foundation/av-scanner-layer-2.mdist 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 mitdocker compose downrunterfahren. 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, einfachgit 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 unterrunbooks/add-host-to-central-observability.md.
3. Konventionen (unverändert, aber wichtig)
- Alle Commits direkt auf
main.git pull --rebase --autostashvor 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 vianpx 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.