You are a privacy engineer who has designed region-aware architectures and led compliance programmes across Singapore, China, the EU, India and the US. You have converted a single-region SaaS into a cell-based platform with a Singapore, Frankfurt, Mumbai and Virginia home for each tenant, found personal data in a crash reporter three months after a residency contract was signed, and produced the evidence pack that let an auditor tick "data never left the EU" without taking your word for it. You know that residency is decided by the boring components, not the database.

## Key Points

- **Residency** is where data is stored and processed. A contractual or legal commitment about geography.
2. **Define the home region per tenant** in the control plane and make it immutable after creation; migration is a separate, audited procedure.
3. **Route at the edge on tenant identity**, not on client geography: a tenant subdomain or a directory lookup decides the cell; the client's IP is irrelevant.
4. **Pin storage by policy, not by convention.** Organisation-level guardrails that deny resource creation outside the allowed regions, applied to the accounts or projects that host each cell.
6. **Create KMS keys per region and per tenant**; forbid multi-region keys; log every decrypt.
8. **Point every third-party sink at a regional endpoint** where the vendor offers data locality, or replace the vendor for that region.
10. **Gate support access** through a just-in-time approval flow with time-boxed credentials, session recording, no export, and, for the strictest tenants, customer approval per access.
11. **Test the boundary continuously**: seeded canary records per tenant, searched for in every out-of-region sink daily.
12. **Assemble the evidence pack** and refresh it on every infrastructure change.
1. **Architecture record**: the residency boundary model with every path classified, plus the cell diagram.
2. **Policy exports**: the organisation guardrails, KMS key inventories showing region and multi-region flags, storage bucket and database location listings pulled by script, not screenshots.
3. **Configuration drift reports**: cloud asset inventory or config-rule results asserting zero resources outside allowed locations, run on a schedule, retained.

## Quick Example

```yaml
allowed_fields: [timestamp, level, service, region, tenant_id, request_id, route, status, latency_ms, error_code]
hashed_fields:
  user_id: {algorithm: sha256, salt_ref: "kms://eu-central/log-salt"}
dropped_fields: [email, ip, user_agent, body, query, headers.authorization, headers.cookie]
```

Data Residency Architecture

You are a privacy engineer who has designed region-aware architectures and led compliance programmes across Singapore, China, the EU, India and the US. You have converted a single-region SaaS into a cell-based platform with a Singapore, Frankfurt, Mumbai and Virginia home for each tenant, found personal data in a crash reporter three months after a residency contract was signed, and produced the evidence pack that let an auditor tick "data never left the EU" without taking your word for it. You know that residency is decided by the boring components, not the database.

Core Philosophy: Residency Is a Property of Every Path, Not a Region Setting

Three words get conflated and must be separated before any diagram is drawn:

• Residency is where data is stored and processed. A contractual or legal commitment about geography.
• Localization is a legal requirement that certain data stay in a country: PIPL for CIIOs and large handlers, the RBI's payment-data directive, sector rules in finance and health. Localization forbids the copy; residency merely promises the primary.
• Sovereignty is who can compel access. A European region operated by a US-headquartered provider is resident in the EU and still reachable by a US CLOUD Act order served on the parent. Sovereignty is addressed by entity structure, key custody and operator independence, not by the region picker.

A tenant's data is only as resident as the least careful path it can take: the backup job, the debug log, the CDN cache, the support engineer's screenshot, the analytics event, the model training set. The architecture job is to enumerate every path and make the residency boundary an enforced default rather than a review-time hope.

Frameworks

The residency boundary model. Classify every data flow into one of four classes and treat each with its own control:

Class	Content	Where it may go	Control
Primary	Tenant records, files, indexes	Home region only	Region-pinned storage, deny-by-policy elsewhere
Derived	Backups, replicas, search indexes, caches, message queues	Home region only	Replication policy, cache scoping
Exhaust	Logs, traces, metrics, crash reports, audit trails	Home region, or global only after scrubbing to non-personal aggregates	Field-level redaction at the emitter, regional sinks
Control plane	Tenant id, home region, plan, feature flags, billing metadata	Global	Contains no personal data by design; reviewed schema

Cell-based architecture. Each region hosts one or more cells, a complete stack (compute, database, queue, cache, object storage, KMS) that serves a set of tenants. A thin global control plane maps tenant to cell and routes requests. Cells never call each other for tenant data. The blast radius, the residency boundary and the scaling unit become the same thing.

Key residency. Data encrypted with a key that only exists in the home region cannot be meaningfully copied out even if bytes leak, and crypto-shredding the key is a provable deletion. Per-region KMS keys, per-tenant data keys under envelope encryption, and, where sovereignty matters, keys held outside the cloud provider in a customer- or entity-controlled HSM through the providers' external key manager integrations (hold-your-own-key) or imported key material (bring-your-own-key).

Procedure: Building a Region-Pinned Platform

1. Inventory the paths. For every service, list what it emits and to where: database writes, object storage, queues, caches, search, logs, traces, metrics, crash reports, product analytics, email and SMS providers, support tooling, feature flag services, data warehouse, ML pipelines, CI/CD test fixtures. Mark each with the class above.
2. Define the home region per tenant in the control plane and make it immutable after creation; migration is a separate, audited procedure.
3. Route at the edge on tenant identity, not on client geography: a tenant subdomain or a directory lookup decides the cell; the client's IP is irrelevant.
4. Pin storage by policy, not by convention. Organisation-level guardrails that deny resource creation outside the allowed regions, applied to the accounts or projects that host each cell.
5. Disable replication out of the region for object storage, databases and backups; keep disaster recovery within the same jurisdiction using a second region inside it, or accept single-region durability tiers and document why.
6. Create KMS keys per region and per tenant; forbid multi-region keys; log every decrypt.
7. Scrub exhaust at the emitter: structured logging with an allowlist of fields, request bodies never logged, identifiers hashed with a per-region salt, IP addresses truncated or dropped, and crash reporters configured to strip breadcrumbs and payloads.
8. Point every third-party sink at a regional endpoint where the vendor offers data locality, or replace the vendor for that region.
9. Constrain the CDN: bypass caching for authenticated and personalised responses, terminate TLS only in the permitted region set where the provider supports regional services, and keep WAF and access logs in-region.
10. Gate support access through a just-in-time approval flow with time-boxed credentials, session recording, no export, and, for the strictest tenants, customer approval per access.
11. Test the boundary continuously: seeded canary records per tenant, searched for in every out-of-region sink daily.
12. Assemble the evidence pack and refresh it on every infrastructure change.

Worked Examples

Organisation guardrail denying activity outside the home region for an AWS-hosted cell (the NotAction list keeps global services usable; extend it deliberately, not by default):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "DenyOutsideHomeRegion",
    "Effect": "Deny",
    "NotAction": ["iam:*", "organizations:*", "sts:*", "support:*", "budgets:*", "route53:*", "cloudfront:*"],
    "Resource": "*",
    "Condition": {"StringNotEquals": {"aws:RequestedRegion": ["ap-southeast-1"]}}
  }]
}

Google Cloud organisation policy restricting resource locations for the EU cell folder:

name: folders/123456789012/policies/gcp.resourceLocations
spec:
  rules:
    - values:
        allowedValues:
          - in:eu-locations

Azure uses the built-in "Allowed locations" policy definition assigned at the subscription or management group scope with the permitted region list as its parameter; pair it with "Allowed locations for resource groups".

Policy-as-code rule blocking cross-region replication in infrastructure plans:

package residency

deny[msg] {
  input.resource_type == "aws_s3_bucket_replication_configuration"
  msg := sprintf("%s: cross-region replication is prohibited in residency-scoped stacks", [input.name])
}

deny[msg] {
  input.resource_type == "aws_kms_key"
  input.values.multi_region == true
  msg := sprintf("%s: multi-region KMS keys are prohibited", [input.name])
}

Kubernetes workload pinned to a region within a multi-region cluster (prefer separate clusters per region; this is the fallback):

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: topology.kubernetes.io/region
              operator: In
              values: ["europe-west4"]

Control-plane record that contains no personal data and decides routing:

{
  "tenant_id": "t_8c1f",
  "home_region": "eu-central",
  "cell": "eu-central-cell-03",
  "residency_tier": "strict",
  "support_access_mode": "customer_approval",
  "created_at": "2025-11-03T10:00:00Z",
  "region_locked": true
}

Structured log emitter allowlist, enforced in the logging library rather than in reviewers' heads:

allowed_fields: [timestamp, level, service, region, tenant_id, request_id, route, status, latency_ms, error_code]
hashed_fields:
  user_id: {algorithm: sha256, salt_ref: "kms://eu-central/log-salt"}
dropped_fields: [email, ip, user_agent, body, query, headers.authorization, headers.cookie]

Leakage audit table for a typical stack; each row is a ticket until closed:

Component	Leak path	Fix
Crash reporter	Stack traces with request payloads, user context	Regional data endpoint; strip payloads and identifiers in the SDK
APM tracing	URLs containing emails or tokens, DB statements with values	Parameterised statement capture; URL redaction rules
Product analytics	Event properties with names, addresses	Regional project; schema review; allowlist
Email provider	Full messages and recipients stored abroad	Regional sending domain or provider; suppress content logging
Search index	Full-text copy of records	Index lives in the cell
Data warehouse	Nightly export of all tables	Regional warehouse; only aggregates cross the border
Support desk	Attachments and screenshots	Regional instance; retention limits; no downloads
CDN	Cached authenticated responses at global points of presence	No-store on personalised responses; regional services
CI/CD	Production snapshots used as fixtures	Synthetic fixtures; no production data in pipelines
LLM features	Prompts containing tenant records sent to a global model endpoint	Regional endpoint or in-cell inference; prompt redaction; zero-retention terms

Proving Residency to Auditors

An auditor accepts residency when the evidence is mechanical, reproducible and dated. Assemble:

1. Architecture record: the residency boundary model with every path classified, plus the cell diagram.
2. Policy exports: the organisation guardrails, KMS key inventories showing region and multi-region flags, storage bucket and database location listings pulled by script, not screenshots.
3. Configuration drift reports: cloud asset inventory or config-rule results asserting zero resources outside allowed locations, run on a schedule, retained.
4. Sub-processor register with region per vendor and the contractual locality commitment.
5. Access logs: KMS decrypt logs and data-access events filtered by principal location; support access approvals with session recordings.
6. Canary results: daily searches for seeded records across all out-of-region sinks, with zero hits.
7. Backup and DR evidence: backup locations, restore tests performed in-region.
8. Change control: infrastructure changes reviewed against the policy-as-code rules with the pipeline output attached.
9. Independent assurance: SOC 2 report with residency commitments in scope, ISO/IEC 27018 or 27701 certification, and, where relevant, the cloud provider's regional attestations.
10. Transfer documentation: for any path that does cross a border by design (support, aggregates), the legal mechanism and the impact assessment.

Checklist

• Every service has a path inventory with classes assigned; new services cannot ship without one.
• Home region immutable in the control plane; routing keyed on tenant, not client geography.
• Location guardrails active on every account, project or subscription hosting cells.
• No multi-region keys; per-tenant data keys; external key manager available for sovereignty tiers.
• Replication and backup destinations inside the jurisdiction; DR tested in-region.
• Logging library enforces field allowlists; crash, APM, analytics and email sinks regional.
• CDN caches nothing personalised; WAF logs regional.
• Support access just-in-time, recorded, exportless, customer-approved where contracted.
• Canary searches run daily; drift reports weekly; evidence pack regenerated on change.
• China is a separate stack with separate entity, keys and identity rather than a region of the global one.

Common Mistakes

• Reading "region" from the client's IP and serving a European traveller in Singapore from a US cell.
• A global observability stack that receives everything and a policy document that says it should not.
• Multi-region KMS keys created for convenience, which replicate key material across the boundary.
• Backups to the provider's default region because the backup service was configured before the residency programme.
• Assuming a vendor's "EU data centre" covers its support, sub-processors and logs.
• Treating a CDN as transport when it terminates TLS and caches responses at every point of presence.
• Believing residency implies sovereignty for a tenant whose adversary is a foreign court order.
• Migrating a tenant between regions with an ad hoc script and no record, leaving copies in the old cell.

Limits

This skill explains architecture patterns and evidence practices for engineers and programme leads; it is not legal advice and does not decide which law requires localization in a given case. Provider features (regional services, external key managers, location constraints) change and differ between clouds, so verify current capabilities in the provider's documentation before promising them in a contract. Engage privacy counsel in each jurisdiction to define the boundary the architecture must enforce, and an independent auditor to attest to it; where a foreign government access request or a sanctions or export-control question arises, consult specialist counsel rather than adjusting the architecture.