For Stakeholders

Why this matters

Dentolize currently runs every clinic worldwide on one shared database. That's a growing liability on two fronts as the company expands into new markets: data residency (Saudi Arabia and other markets increasingly expect or require in-country hosting of clinic/patient data) and blast radius (a bad migration, a slow query, or an outage in the shared database affects every clinic on the platform at once, everywhere). This PR is the architectural fix: independent regional databases, a lightweight global routing layer, and a purpose-built tool to migrate existing clinics onto the new structure without disrupting them.

This is a prerequisite for entering the Saudi Arabia market with a credible data-residency story, not a customer-visible feature. Scope: 437 files, ~59,500 lines added — a genuinely large, structural change, though it's confined to backend/infrastructure code with only a thin login/admin surface visible to users.

Risk profile

• This code has not run in production. The PR's own planning document (scripts/MULTI_REGION_PLAN.md) states this explicitly and lays out a staged validation plan (local Docker, then a real cloud test environment) before any production cutover is attempted.
• The rollout is intentionally staged and reversible up to a point. scripts/GO_LIVE_RUNBOOK.md defines a specific maintenance window with an explicit pre-open rollback procedure; existing customers stay on the current architecture (framed as EU-1) initially, and the new region (ME-1) only accepts new Saudi registrations at first — no wholesale migration of the existing customer base on day one.
• The migration tool that eventually moves existing clinics is high-stakes but carefully guarded: it requires an explicit typed confirmation string containing the exact company id and region codes, refuses to run while the clinic has active financial/import work in flight, and never deletes the source region's data automatically — the old copy stays as a disabled backup until an operator explicitly removes it. See Moving a Company Between Regions.
• Test coverage is unusually heavy for infrastructure work of this kind: a 36-file end-to-end smoke-test suite exercises the full two-region stack (auth, routing, storage, WhatsApp, payments, cron, Redis isolation, and the migration tool itself), plus eight dedicated verify-* scripts run during the actual cutover.
• Two multi-account storage systems currently coexist in the frontend (packages/clinic-web's regionAccountsStorage.js and the newer, more portable packages/common/src/auth/accountStore.ts) with different storage keys. Not a functional bug today, but worth a follow-up consolidation before it becomes tech debt.

What to watch for

• Whether the go-live runbook's phased approach (EU-1 stays as-is initially, ME-1 takes only new registrations) holds, or whether pressure emerges to migrate existing customers faster than the validated, dry-run-first migration process supports.
• Operational readiness for running two deployment models simultaneously (PM2 for EU-1, Docker for ME-1) — this is more moving parts for the ops team to hold in their heads than a single, uniform deployment story.