freshyo/docs/region-backwards-compat.md
2026-10-05 11:46:47 +05:30

7.4 KiB

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-<id>/, _<id> 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-<id>/ 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_<id> 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-<id>/ 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, <counter>_<id> 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.


  • 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.