Skip to content

GCP Migration — End-to-End Flows

This section captures runtime + data-flow views of Curaway in production today, prepared for the GCP migration planning effort.

The team already has the service inventory + GCP-equivalents map as a working document. The pages below complement it with the perspectives that a static service list can't show: who-calls-who at runtime, where PHI lives and travels, and the ordered set of external services each user-visible action actually depends on.

What's here

Page Audience Purpose
Sequence — Patient happy path Eng team Case creation → intake → matching → consultation. The flow that produces Curaway's primary revenue path.
Sequence — Auth + tenant resolution Eng + security review Clerk JWT → RBAC middleware → tenant_org_mappings → endpoint. Critical for IAM design on GCP.
Sequence — Async pipelines + webhooks Eng team Scheduled crons, FHIR sweep, Clerk webhook. Asynchronous side of the platform; consolidates onto Cloud Tasks + Cloud Scheduler on GCP.
Data flow map Eng + compliance Every PHI-bearing table, RLS/redaction policies, cross-tenant boundaries, external egress. Foundation for HIPAA / BAA review.
Runtime trace example Eng team One real production case pulled from Langfuse, annotated. Empirical floor for migration cost + cold-start budget.
Codebase coupling report Eng team graphify-generated knowledge graph of app/ + docs/ + alembic/. Surfaces tightly-coupled modules that should migrate as units. Includes interactive HTML graph (4MB), queryable JSON (5.8MB), and labelled community hubs.

How to use these together

  1. Start with the service inventory (already with the team) — what exists.
  2. Read the three sequence diagrams — what runs and in what order.
  3. Read the data flow map — what data crosses which boundary.
  4. Reference the runtime trace — empirical timings + token cost for the patient happy path.
  5. (Optional) Run /graphify . from a Claude Code session to validate the migration units the team picks against actual code coupling. Commit the output to docs/migration/graphify-report/.

Conventions used in these diagrams

  • Teal #008B8B boxes: Curaway-owned services (FastAPI app, agents, services).
  • Coral #FF7F50 boxes: external SaaS / managed dependencies that survive the migration unchanged or with a swap.
  • Solid arrows: synchronous calls.
  • Dashed arrows: asynchronous (event bus, callback, webhook).
  • Annotations on arrows: the env var or auth header used.

PHI-bearing data crossings are called out explicitly in each diagram and rolled up in the data flow map.

Status

Document Status
Sequence — Patient happy path ✅ Drafted 2026-04-29
Sequence — Auth + tenant resolution 🟡 Drafted 2026-04-29
Sequence — Async pipelines + webhooks 🟡 Drafted 2026-04-29
Data flow map 🟡 Drafted 2026-04-29
Runtime trace example ✅ Populated 2026-04-29 (case 147f70ac…, 78 LLM spans)
Codebase coupling report (graphify) ✅ Generated 2026-04-29 (3,920 nodes, 10,717 edges, 101 communities, 19.3× token reduction vs raw)