# Plan — Part 2/2: user-ui (consume the per-bound flat JSON) Part 2 of 2. Adapts **`apps/user-ui`** to request the precomputed flat JSON by `boundId` and read the flat shape. Backend + admin UIs are Part 1 (`consts-three-tables-part1-backend-admin.md`) and must land first (the client depends on `{ boundId }` input, `listRegions.effectiveBoundId`, and the flat payload). ## 0. Decisions - user-ui **sends `boundId`** (persisted client-side) and reads the flat JSON. - Scope: `apps/user-ui` only. `apps/web-ui` stays on the old contract (breaks; see §4). - AGENTS.md: no test runs, no migrations, no git; log planned diffs to `change-log.txt` before editing non-`.md`/`.txt` files. ## 1. Flat JSON contract (from Part 1) `common.essentialConsts({ boundId })` returns the union of global + region + bound rows plus identity/env: ```jsonc { "versionNum": "1.1.0", "playStoreUrl": "...", "appStoreUrl": "...", "internalAppVersion": 1, "products_version_num": 2, "availability_version_num": 2, "slots_version_num": 2, "popularItems": "[]", "allItemsOrder": "[]", "isFlashDeliveryEnabled": true, "supportMobile": "...", "supportEmail": "...", "welcomeMessage": "...", "minRegularOrderValue": 300, "freeDeliveryThreshold": 300, "deliveryCharge": 20, "flashFreeDeliveryThreshold": 500, "flashDeliveryCharge": 69, "assetsDomain": "...", "apiCacheKey": "...", "regionId": 1, "boundId": 7, "webviewHtml": null, "isWebviewClosable": true } ``` - `allItemsOrder` is the region's value (identical across bounds of the same region). - The nested `effectiveSettings`/`regionSettings` block is gone. - `EssentialConstsApiType` (`@backend/trpc/router`) already reflects this (derived from `scaffoldEssentialConsts`). ## 2. Region-bound state (client must know its boundId) Today the client knows only `regionId` (persisted in `regionStore`); the resolved bound is transient. Changes: ### 2.1 `src/store/regionStore.ts` - Add `selectedBoundId: number | null`. - `setRegion(region: RegionSummary, boundId?: number | null)` persists both; include `selectedBoundId` in `partialize`; extend the no-op guard to compare boundId. ### 2.2 `src/hooks/useRegion.ts` - Expose `boundId` (from the store) on `UseRegionResult`. - On a successful `resolveRegionByLocation`, persist `setRegion(resolved.region, resolved.bound.id)` (instead of region-only). ### 2.3 `src/lib/region-switch.ts` - `confirmRegionSwitch(region, queryClient, boundId?)` forwards the boundId to `regionStore.setRegion` (manual picks get the region's effective bound id). ### 2.4 `src/components/RegionSelector.tsx` - `listRegions` now returns `effectiveBoundId` per region → pass it through `confirmRegionSwitch` so a manually chosen region still has a `boundId`. ## 3. Consuming the flat JSON ### 3.1 `src/hooks/prominent-api-hooks.ts` - **`useGetEssentialConsts`** - read `boundId` from `useRegion()` (not `regionId`); - `trpc.common.essentialConsts.useQuery({ boundId }, { refetchInterval: 60000, enabled: isReady && boundId != null, placeholderData: initialData })`; - persist under `` `essential_consts_b${boundId}` `` (was `essential_consts_r{regionId}`). - **URL builders** (rename to the new keys): - `useCacheUrl` / `useStoreWithProducts` → `products_version_num` (was `cacheVersion`); - `useAvailabilityCacheUrl` → `availability_version_num`; - `useSlotsCacheUrl` → `slots_version_num`; - region id in URLs → `data.regionId` (via `useDiscoveryRegionId`, now reading the flat `regionId` with `useRegion().regionId` fallback). - **`useRegionalConsts`** → thin passthrough of the flat data (delivery values are already top-level). Keep the exported function so `cart-page`, `checkout-page`, `floating-cart-bar`, and `PaymentAndOrderComponent` need no edits. - Remove the `effectiveSettings`/`regionSettings` fallback fields from `DiscoveryData` and the now unused `discoverySettings` helper. ### 3.2 Unchanged (verify only) - `cart-page.tsx`, `checkout-page.tsx`, `floating-cart-bar.tsx`, `PaymentAndOrderComponent.tsx` keep reading `deliveryCharge` / `flashDeliveryCharge` / `freeDeliveryThreshold` / `flashFreeDeliveryThreshold` / `minRegularOrderValue` (now flat). - `AddToCartDialog.tsx` (`isFlashDeliveryEnabled`), `flash-delivery/_layout.tsx` (`isFlashDeliveryEnabled`), `NextOrderGlimpse.tsx` (`supportMobile`), `me/complaints/index.tsx` (`supportMobile`/`supportEmail`), `UpdateChecker.tsx` (`internalAppVersion`), `HealthTestWrapper.tsx` (`versionNum`/`playStoreUrl`/`appStoreUrl`), `WebViewWrapper.tsx` (`webviewHtml`/`isWebviewClosable`) — field names unchanged in the flat JSON. - `LocationBar.tsx`, `LocationTestWrapper.tsx`, `FirstUserWrapper.tsx` — region-only; unaffected. ## 4. Out of scope / consequences - **`apps/web-ui`** (`src/hooks/prominent-api-hooks.ts`) still calls `common.essentialConsts({ regionId })` and reads `cacheVersion`/`availabilityVersionNum`/ `slotsVersionNum` → will fail input validation and show no data until migrated. Not in this plan. - If the hard break must be avoided, Part 1 can add a `regionId` fallback (server maps to `getEffectiveBoundId(regionId)`); then web-ui keeps working read-only. Decide before shipping. ## 5. Verification 0. Append planned diffs + timestamp to `change-log.txt` first. 1. Typecheck: `npx tsc --noEmit --project apps/user-ui/tsconfig.json`. 2. Smoke (after Part 1 is deployed + migration 0009 applied): - Pick/auto-resolve a region → `boundId` persisted in `freshyo-region`. - `common.essentialConsts` called with `{ boundId }`; payload cached under `essential_consts_b{boundId}`. - Catalog URLs contain `products_version_num` / `availability_version_num` / `slots_version_num` and the correct `regionId`. - Cart/checkout show the selected bound's delivery values; switching region updates them. - Flash gate (`isFlashDeliveryEnabled`), update gate (`internalAppVersion`/`versionNum`), support links, and webview notice all still work. ## 6. Checklist 1. `change-log.txt` — append planned diffs. 2. `src/store/regionStore.ts` — `selectedBoundId` + persist. 3. `src/hooks/useRegion.ts` — expose `boundId`; persist on resolve. 4. `src/lib/region-switch.ts` — forward boundId. 5. `src/components/RegionSelector.tsx` — use `effectiveBoundId`. 6. `src/hooks/prominent-api-hooks.ts` — `{ boundId }` input, per-bound cache key, renamed version fields, simplified `useRegionalConsts`, drop `effectiveSettings` fallbacks. 7. Typecheck `apps/user-ui`; fix self-introduced errors.