123 lines
9.3 KiB
Markdown
123 lines
9.3 KiB
Markdown
# Phase 03 — Skalierungs-Infrastruktur
|
|
|
|
> **Historical phase-plan status:** this README preserves the original Phase
|
|
> 03 dependency map and done definition. Current runtime/operator truth lives
|
|
> in `docs/improvement-plan/PROGRESS.md`,
|
|
> `docs/improvement-plan/OPERATOR-CHECKLIST.md`,
|
|
> `docs/ops/worker-queues.md`, `docs/architecture/outbox-pattern.md`, and
|
|
> `docs/ops/asset-cdn.md`. In particular, #51/A7/B2 CDN rollout is currently
|
|
> parked in backlog, not an active Phase 03 closeout item.
|
|
|
|
**Dauer:** 4-5 Wochen
|
|
**Tasks:** 12 (dieses README dokumentiert alle 12; die State-/DB-Teilmenge 37-42 ist hier ausführlich, Worker/Backup/CDN 43-47/51 in separaten Detail-MDs vom Parallel-Subagent)
|
|
**Ziel:** Boilerplate von „Single-Process-MVP" auf horizontal skalierbare Production-Architektur bringen. Alle In-Process-State-Stores raus, DB-Stack härten (PgBouncer + Read-Replica + Outbox), Worker-Queues sauber trennen, Backups + Tenant-Snapshots automatisieren, statische Assets über CDN ausliefern.
|
|
|
|
## Warum diese Phase
|
|
|
|
Aktueller Zustand: Mehrere kritische Code-Pfade halten Zustand im Prozess-RAM (`apps/api/src/auth/login-rate-limit.ts`, `apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts`, `apps/api/src/idempotency/store.ts`, `apps/web/app/utils/services/.server/subscriptionService.ts` mit `cachified`-Wrapping, `apps/api/src/auth/session/session-store.ts`, `apps/web/app/modules/mcp/mcp.server.ts`). Sobald eine zweite Replica läuft, sind Rate-Limits umgehbar, Idempotency-Keys werden inkonsistent, Stripe-Webhook-Cache-Invalidations erreichen nur eine Instanz und Sessions ghosten.
|
|
|
|
DB-seitig hängen 100+ Prisma-Calls direkt am Primary, ohne Connection-Pooler. Bei 200 gleichzeitigen Web-Requests reicht ein Tab voll schwerer Dashboard-Loaders, um Postgres-`max_connections` auszuschöpfen. Außerdem laufen alle Reads gegen den Writer, und Stripe-Webhook-Side-Effects (Mail, Webhook, Audit-Log) sind nicht transaktional mit dem DB-Write gekoppelt — bei Crash zwischen Commit und Side-Effect verlieren wir Outbound-Events.
|
|
|
|
Phase 03 baut die fehlende Plumbing für Multi-Replica-Betrieb. Ohne diese Phase blockieren wir Phase 04 (Search braucht Outbox für async-Indexing) und Phase 05 (Feature-Flags brauchen einen Shared-Cache mit Pub/Sub-Invalidation).
|
|
|
|
## Task-Reihenfolge
|
|
|
|
| Reihenfolge | Task-ID | Datei | Parallelisierbar mit | Subagent-Slot |
|
|
|---|---|---|---|---|
|
|
| 1 | #37 | `shared-store-package.md` | — (Foundation für alles andere) | State-Subagent |
|
|
| 2 | #38 | `shared-store-migration.md` | #40, #43, #51 | State-Subagent |
|
|
| 3 | #39 | `pubsub-cache-invalidation.md` | #41, #44, #45 | State-Subagent |
|
|
| 4 | #40 | `pgbouncer.md` | #38, #43, #45 | State-Subagent (DB-Teil) |
|
|
| 5 | #41 | `read-write-split.md` | #39, #44, #46, #51 | State-Subagent (DB-Teil) |
|
|
| 6 | #42 | `outbox-pattern.md` | #45, #47 | State-Subagent (DB-Teil) |
|
|
| 7 | #45 | `worker-queues.md` | #39, #40, #41 | Worker-Subagent |
|
|
| 8 | #46 | `streaming-exports.md` | #41 | Worker-Subagent |
|
|
| 9 | #47 | `job-priority.md` | #42 | Worker-Subagent |
|
|
| 10 | #43 | `backup-cli.md` | #38, #40 | Worker-Subagent |
|
|
| 11 | #44 | `tenant-snapshot.md` | #39, #41, #43 | Worker-Subagent |
|
|
| 12 | #51 | `asset-cdn.md` | #38, #41 | Worker-Subagent; currently backlog/operator-deferred |
|
|
|
|
## Dependency-Graph (intern)
|
|
|
|
```
|
|
#37 shared-store-package ──► #38 shared-store-migration ──► #39 pubsub-cache-invalidation ─┐
|
|
│ │
|
|
└─────────────────► (nutzt Redis-Connection auch für BullMQ-Queues) │
|
|
│
|
|
#40 pgbouncer ──► #41 read-write-split ──► #42 outbox-pattern ──────────────────────────────┤
|
|
│ │
|
|
▼ │
|
|
#47 job-priority │
|
|
│
|
|
#45 worker-queues ──► #46 streaming-exports │
|
|
│
|
|
#43 backup-cli ──► #44 tenant-snapshot │
|
|
│
|
|
#51 asset-cdn (parked/backlog) ──────────────────────────────────────────────────────────────┤
|
|
│
|
|
▼
|
|
Phase 04 (Search/RAG)
|
|
```
|
|
|
|
**Wichtige Reihenfolge-Regeln:**
|
|
- `#37 shared-store-package` ist **hartes Fundament**: liefert das Adapter-Interface, die Redis-/Memory-Implementations und die Higher-Level-Helpers (Rate-Limit, Cache, Session, Idempotency). Ohne dieses Package kann weder #38 noch #39 starten, und die Worker-Tasks (BullMQ teilt sich die Redis-Connection) werden auch davon abhängen.
|
|
- `#38 shared-store-migration` migriert die 6 In-Process-Stores. Muss nach #37, parallel zu #40 möglich.
|
|
- `#39 pubsub-cache-invalidation` ist die logische Fortsetzung der Migration für Caches mit nicht-trivialer Konsistenz (Stripe-Subscription-Cache, Tenant-Cache, Feature-Flag-Cache). Setzt #38 voraus, weil dort der Pub/Sub-Adapter etabliert wird.
|
|
- `#40 pgbouncer` ist unabhängig von Shared-Store, muss aber vor `#41 read-write-split` stehen, weil R/W-Split die `DIRECT_URL`-Konvention für Migrations braucht, die in #40 etabliert wird.
|
|
- `#42 outbox-pattern` braucht `#41` (publishOutboxEvent läuft innerhalb einer Transaction auf prismaWrite), und liefert die Foundation für `#47 job-priority` (priorisierte Dispatcher-Queue) sowie Phase 04 (async-Indexing).
|
|
- `#45 worker-queues` und `#43 backup-cli` sind weitgehend orthogonal und können parallel laufen, sobald #37 fertig ist. `#51 asset-cdn` war ebenfalls orthogonal, ist aber seit der Operator-Entscheidung 2026-05-24 in A7/B2/#51 geparkt; nicht als aktiven Phase-03-Blocker zählen.
|
|
|
|
## Sub-Phasen-Verteilung
|
|
|
|
**State-Subagent (dieses README behandelt 37-42 ausführlich):**
|
|
- #37 Shared-Store Package
|
|
- #38 Shared-Store Migration
|
|
- #39 Pub/Sub Cache-Invalidation
|
|
- #40 PgBouncer Setup
|
|
- #41 R/W-Split via Prisma $extends
|
|
- #42 Outbox-Pattern + Dispatcher
|
|
|
|
**Worker-Subagent (separate Detail-MDs, eigene Verantwortung):**
|
|
- #45 Worker-Queue-Trennung
|
|
- #46 Streaming-Exports + Row-Cap
|
|
- #47 BullMQ Job-Priority
|
|
- #43 Backup-CLI
|
|
- #44 Tenant-Snapshot-Tool
|
|
- #51 Asset-CDN (historisch geplant; aktueller Status: backlog/operator-deferred)
|
|
|
|
Beide Subagents synchronisieren auf der Redis-Connection-Konvention aus #37 (gleiche ioredis-Instanz, unterschiedliche logical-DB-Indizes; BullMQ-Queues auf Index 0, Shared-Store auf Index 1, Pub/Sub auf Index 2).
|
|
|
|
## Phase Done-Definition
|
|
|
|
Diese Phase ist `completed` wenn:
|
|
|
|
- [ ] Alle 12 Tasks `completed` in `PROGRESS.md`
|
|
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` global grün; testcontainers-basierte Integration-Tests laufen in CI gegen Redis + Postgres + PgBouncer
|
|
- [ ] Staging deployed mit 2x Web-Replicas + 1x API + 2x Worker hinter Caddy-Reverse-Proxy; Last-Test (k6 mit 500 RPS auf 5min) zeigt: keine Login-Rate-Limit-Bypasses, keine Stripe-Cache-Inconsistencies, kein Connection-Exhaustion auf Postgres
|
|
- [ ] Stripe-Webhook → Subscription-Cache-Invalidation < 2s end-to-end (vorher: bis zu 1h stale)
|
|
- [ ] PgBouncer-`SHOW STATS` zeigt `cl_active < default_pool_size` unter normaler Last; Connection-Reuse-Ratio > 90 %
|
|
- [ ] Read-Replica führt > 60 % der Dashboard-Reads aus (gemessen via Prisma-Middleware-Counter)
|
|
- [ ] Outbox-Dispatcher hat 0 unverarbeitete Events > 60s alt im 24h-Monitor-Fenster
|
|
- [ ] `.env.example` + `.env.production.example` enthalten alle neuen Keys (`REDIS_URL`, `REDIS_SHARED_STORE_DB`, `REDIS_PUBSUB_DB`, `DATABASE_URL`, `DATABASE_READ_URL`, `DIRECT_URL`) sauber dokumentiert
|
|
- [ ] Doku-Files angelegt: `docs/observability/redis-stores.md`, `docs/database/connection-pooling.md`, `docs/database/read-replicas.md`, `docs/database/outbox-pattern.md`
|
|
- [ ] `gsd-code-reviewer`-Subagent hat alle 12 Tasks-Commits reviewed; Findings adressiert
|
|
- [ ] Phase-Summary in dieser README.md ergänzt (siehe unten)
|
|
- [ ] Rollback-Drill durchgeführt: PgBouncer-Container down → Web läuft via DIRECT_URL-Fallback weiter; Redis down → Memory-Adapter-Fallback aktiv (Single-Instance-Mode)
|
|
|
|
## Phase Summary
|
|
|
|
_(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_
|
|
|
|
### Lessons Learned
|
|
|
|
_(Wird nach Abschluss ergänzt.)_
|
|
|
|
## Verweise
|
|
|
|
- Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md`
|
|
- Agent-Workflow: `../AGENT-INSTRUCTIONS.md`
|
|
- Execution-Order: `../00-execution-order.md`
|
|
- Live-Status: `../PROGRESS.md`
|
|
- Vorgänger-Phase (Observability): `../02-observability/README.md`
|
|
- Nachfolge-Phase (Search + RAG): `../04-search-rag/README.md`
|