Data Residency
The region a workspace's data lives in, how every storage reference resolves to it, and what a region change moves versus leaves in place.
A workspace chooses a region, and the objects that are its apps' sources of truth live at rest in that region: database files, git repositories, build artifacts, private files, snapshots. This chapter covers the region model, how every storage reference knows where it lives, what is provisioned per region, and what happens when a workspace moves to a new region.
#Regions
A region is a branded slug that maps to an AWS region. The slug, not the AWS region, is what gets stored, so the platform can move a slug's backing region without rewriting a single reference.
| Slug | Location |
|---|---|
us-1 | United States (Oregon) |
eu-1 | European Union (Frankfurt) |
ca-1 | Canada (Central) |
au-1 | Australia (Sydney) |
Each region has its own pair of S3 buckets, its own private-files CloudFront distribution, its own access-log bucket, and its own SNS topic feeding the file-scan pipeline. The Terraform for a region is one module instantiated with a region-pinned provider, mirroring the base region's configuration exactly, so a new region is a stamp.
The residency promise covers data at rest. Compute runs in one region. Processing, including the vector index cache, is not covered by the promise, and the hot working-copy tier described in App Databases is bounded by an hourly checkpoint back to the home region.
#Self-Describing References
Every S3 read and write in the platform goes through one storage accessor operating on a storage reference: a value that names the logical bucket, the region, and the key together. Region resolution happens once, at write time, from the owning workspace; the reference then carries the region, so reads never re-derive it.
Three authorities decide a region, and they are not interchangeable:
- The workspace's current region for creating a resource and for born-here uploads whose reference becomes self-describing.
- The app's pinned region, recorded on its repository row, for every object belonging to an existing app.
- The database's pinned region, recorded on its catalog row, for the one SQLite file. A cloned database inherits its source, and the two migrate independently.
Region-pinned S3 clients are built lazily and cached per region and flavor: a plain regional client, an accelerated client for browser uploads, and a retry-tuned client for high-frequency git backups.
#Changing Region
A workspace can move. The migration runs from a persisted status row, swept by a cron, with every per-resource step idempotent so a partial run resumes cleanly.
Moved: everything read through a region re-derived from a durable record. App databases, the git repository tar and its file mirror and commit diffs, method builds, static bundles, presentation artifacts, diagnostics, and the app's file stores in both buckets.
Left in place: artifacts whose stored reference is self-describing, such as screenshots and CDN data. Their reads carry their own region and keep resolving.
Deleted at the old region: pure caches, which re-render on demand at the new region.
For a git repository the migration stops the app's dev session so nothing writes mid-copy, holds the repository lock so no push races the copy, copies the objects with size verification, flips the repository's region and busts its cache before releasing the lock, then deletes the old objects. A busy lock is not an error; the migration stays in progress and retries on the next sweep.
#Beyond Storage
Region shows up in three more places a reviewer will ask about.
- Public URLs for regional public files carry the slug as a path segment, so an object's public address says where it lives.
- Model routes carry data-boundary facts, so a workspace can see and pin where inference runs. See Models and Routing.
- Dedicated retrieval instances are provisioned per customer resource and rebuilt from that customer's artifacts in S3. See Retrieval.