# Backwards-Compatibility Shims (Region Scoping) > **Purpose:** temporary measures added during the region-scoping rollout to keep > existing clients, stored data, and cache URLs working unchanged. Each item here > should be removed once the condition in its **"Remove when"** column is met. > > Last reviewed: region scoping initial implementation. ## Background Region scoping was added platform-wide. Every user/staff belongs to a region, and almost every table gained a `region_id`. Region **1** is the *legacy region* — it owns all data that existed before regions and is what every already-shipped client implicitly uses. All shims below exist so that: - old clients (which send no region) keep working, and - region 1's cache URLs / KV keys / counters stay **byte-for-byte identical** to what they were before regions existed. The central constant is `DEFAULT_REGION_ID = 1` in `packages/shared/index.ts:14`. --- ## 1. Cache path / KV / version "legacy format" switches These compare `regionId === DEFAULT_REGION_ID` (or `regionId == null`) to choose the **legacy** format (no region segment) versus the **region-scoped** format (`r-/`, `_` suffix). They must stay until all clients read region-scoped URLs, because region 1's files are still written without a prefix. | # | File:line | What it does | Remove when | |---|---|---|---| | 1.1 | `apps/backend/src/lib/cloud_cache.ts:16` | `regionPathPrefix` → `''` for region 1, `r-/` otherwise | No client relies on the un-prefixed (region 1) paths | | 1.2 | `apps/backend/src/lib/cloud_cache.ts:54` | Empty-regions fallback → `[DEFAULT_REGION_ID]` | Can drop if `regions` is guaranteed non-empty (region 1 always exists) | | 1.3 | `apps/backend/src/lib/cloud_cache.ts:63` | `createAllCacheFiles` returns **region 1's** result object | Callers no longer expect region 1's result shape | | 1.4 | `apps/backend/src/lib/cloud_cache.ts:129` | `resolveRegionIds` empty-regions fallback → `[DEFAULT_REGION_ID]` | Same as 1.2 | | 1.5 | `apps/backend/src/lib/cloud_cache.ts:153` | `createAvailabilityCacheFile` no-region call returns **region 1's** version | Standalone availability callers no longer expect region 1's version | | 1.6 | `apps/backend/src/lib/cloud_cache.ts:203` | `createSlotsCacheFile` no-region call returns **region 1's** version | Standalone slots callers no longer expect region 1's version | | 1.7 | `apps/backend/src/lib/gen-store.ts:8` | `regionKvKey` → legacy `essential_consts` key for region 1, `essential_consts_` otherwise | No client reads the legacy `essential_consts` KV key | | 1.8 | `apps/backend/src/lib/gen-store.ts:33` | `refreshGenKv` also writes the legacy `essential_consts` key when region is 1/null | Same as 1.7 | | 1.9 | `apps/backend/src/trpc/apis/common-apis/common-trpc-index.ts:33` | `scaffoldEssentialConsts.cachePathPrefix` → `''` for region 1, `r-/` otherwise | Clients stop needing the legacy (empty) prefix | | 1.10 | `packages/db_helper_sqlite/src/admin-apis/const.ts:9` | `versionKey` → legacy counters (`cache_version`, …) for region 1, `_` otherwise | No client reads the legacy un-suffixed counters | **How to remove the whole section:** once every client is region-aware, drop the `regionId === DEFAULT_REGION_ID` legacy branches and always emit the region-scoped format (and migrate/rename region 1's existing counters + KV key, or keep region 1 as a normal region). --- ## 2. Region-1 data assumptions (kept during migration) | # | File:line | What it does | Remove when | |---|---|---|---| | 2.1 | `packages/db_helper_sqlite/src/admin-apis/product.ts:1089` | `backfillMarketStatsForRegion` copies default prices from **region 1's** market-stats row | Backfill no longer needs a seed source (or a different seed region is chosen) | | 2.2 | `packages/db_helper_sqlite/drizzle/0007_region_scoping.sql` (`DEFAULT 1` on all `region_id` columns) | Migration backfills every existing row to region 1 | Keep permanently as history (do **not** edit an applied migration) — informational only | --- ## 3. Optional `regionId` on user-facing APIs (default to 1) The user-facing request handlers and db helpers keep `regionId` **optional** and default to `DEFAULT_REGION_ID` when absent, so old app builds (which send no region) keep working. Admin paths were made **required** already. ### 3a. User-facing db helpers — `regionId: number = DEFAULT_REGION_ID` | File | Occurrences | |---|---| | `packages/db_helper_sqlite/src/stores/store-helpers.ts` | 9 (lines 41, 95, 142, 163, 198, 219, 273, 290, 329) | | `packages/db_helper_sqlite/src/user-apis/product.ts` | 5 (lines 21, 157, 236, 295, 339) | | `packages/db_helper_sqlite/src/user-apis/stores.ts` | 3 (lines 20, 71, 146) | | `packages/db_helper_sqlite/src/user-apis/slots.ts` | 2 (lines 22, 34) | | `packages/db_helper_sqlite/src/user-apis/banners.ts` | 1 (line 24) | | `packages/db_helper_sqlite/src/user-apis/order.ts` | 1 (line 190) | | `apps/backend/src/stores/product-tag-store.ts:89` | `getTagsByStoreId(storeId, regionId = DEFAULT_REGION_ID)` | **Remove when:** the user app sends its region on every request → make these params required and drop the defaults (mirror the admin helpers). ### 3b. Address add/update — defaults to 1 | # | File:line | What it does | Remove when | |---|---|---|---| | 3.1 | `packages/db_helper_sqlite/src/user-apis/address.ts:88` | `createUserAddress` → `regionId: input.regionId ?? DEFAULT_REGION_ID` | User app always sends `regionId` on address create | | 3.2 | `apps/backend/src/trpc/apis/user-apis/apis/address.ts` (create/update zod) | `regionId` is `.optional()` | Same as 3.1 | ### 3c. Public procedure still pinned to region 1 | # | File:line | What it does | Remove when | |---|---|---|---| | 3.3 | `apps/backend/src/trpc/apis/admin-apis/apis/vendor-snippets.ts:268` | Public `getUpcomingSlots` passes `DEFAULT_REGION_ID` to `getSlotsAfterDate` | The vendor/public page can pass a real region | --- ## 4. Hardcoded client region | # | File:line | What it does | Remove when | |---|---|---|---| | 4.1 | `apps/user-ui/src/constants.ts:3` | `export const REGION_ID = 1` — the user app is pinned to region 1 | User app gains real region selection (derive from the user's address/default region) | | 4.2 | `apps/user-ui/src/hooks/prominent-api-hooks.ts:72,86,100,225` | Reads `essentialConsts.cachePathPrefix ?? ''` and prepends it to cache URLs | Keep the prefix logic permanently; only the `?? ''` fallback can go once all responses include the field | > Note: `4.2` is not purely temporary — the `cachePathPrefix` mechanism is the > permanent way clients build region-scoped URLs. Only the empty-string fallback is > a compat crutch. --- ## 5. Out of scope but related - **`db_helper_postgres`** was not updated for regions (only `db_helper_sqlite` is used by the deployed backend). If Postgres is ever reactivated, it needs the same `region_id` work — no compat shims were added there. - **User-app region *selection*** is deferred; hence §4.1. --- ## Quick removal checklist (when all clients are region-aware) 1. Delete `DEFAULT_REGION_ID` from `packages/shared/index.ts`. 2. Remove the legacy branches in §1 (and migrate region 1's counters/KV key/paths). 3. Make `regionId` **required** in §3a/§3b helpers + address zod. 4. Remove §3c's pinned `DEFAULT_REGION_ID`. 5. Remove `REGION_ID` from user-ui once it selects a region (§4.1). 6. Drop the `?? ''` fallback in user-ui (§4.2) once `cachePathPrefix` is always present. 7. Keep §2.2 (applied migration) untouched.