PRODUCT REPORT — Regions & Location Release Date: 2026-10-04 Scope: everything currently uncommitted in the worktree (customer app, admin apps, superadmin console, backend). Note: database migrations are written but not yet applied; nothing below is live until they run. ===================================================================== 1. CUSTOMER APP (user-ui) ===================================================================== 1.1 Automatic region detection on startup - When the app opens, it asks for location permission and figures out which service region the customer is in, using the delivery-area maps drawn for each region. No manual setup needed for most users. - If permission is denied, or the phone's location switch is off, the app shows a clear "Unable to obtain location" screen explaining exactly which of the two is the problem, with a button that opens the right Settings page (app settings for permission, system location settings on Android). The user can also just pick a region manually and continue. - If the customer is outside every service area, the app says so plainly and still lets them pick a region and browse. 1.2 Region display and switching - The home screen shows the current region above the search bar. It slides away as you scroll so the search bar stays visible. - Tapping the region opens a dropdown to switch regions. The same dropdown now appears on all main tabs (Home, Offers, Flash delivery, Stores, Me). - Switching region reloads that region's products, prices, stores, slots and offers automatically. 1.3 Cart is remembered per region - The cart is saved separately for each region. Going back to a previous region restores exactly what was left there, including quantities. - When the cart is carried into a new region, every item is re-matched to the closest available delivery slot. Items that can't be delivered there are removed. A summary dialog shows what moved (old time vs new time, with a warning when the shift is over an hour) and what was removed. - Applies to both the regular cart and the 1-hour delivery cart. 1.4 Delivery addresses belong to regions - The address form now ends with a mandatory region dropdown, pre-filled with the customer's detected region. - On the cart page there is an address selector. Adding a new address in the current region selects it immediately. If the new address is in a different region, the app shows all addresses in that region and asks the user to pick one. - Changing the selected address to one in another region triggers the same cart check as switching regions: a confirmation dialog appears first when slots would move or items would be removed; empty or unaffected carts switch over silently. - The checkout page no longer has its own address picker; it shows the chosen address read-only. Address selection happens on the cart page. 1.5 Push notifications carry the region - The device's push token is saved together with its region, both for logged-in and logged-out users. If the same device is used by another account or region later, the record moves with it instead of erroring. - Older app installs that never reported a region are treated as region 1. ===================================================================== 2. ADMIN APPS (admin-ui + admin-web) ===================================================================== 2.1 Admins only see and touch their own region - Product, store, slot, banner, tag, group, snippet and order screens are all filtered to the logged-in admin's region. Cross-region editing is blocked with a clear error, including: - editing or deleting another region's product, store, prices or stock, - narrowing an "available in all regions" product down to one region, - widening a product to all regions. - Only super-admins can perform cross-region actions. - The "available in all regions" checkbox is locked (visible but disabled) for non-super-admins on all-region products; the server enforces the same rule regardless. 2.2 All-region products - A product can be marked available in all regions. It carries one store per region (chosen from per-region dropdowns in the product form, with every region's stores visible), while price and stock stay per-region. - Every region selection in the form is mandatory — a product cannot be saved with a region missing its store. - Editing a product's per-region stores later actually updates them (previously those edits were silently lost). 2.3 Region-aware pickers - Product/SKU/tag/store pickers in banners, groups, tags and campaign screens now show the admin's own region data (super-admins see everything combined), instead of always showing region 1. 2.4 App settings per area (customize-app) - Settings such as delivery charges, free-delivery limits, flash delivery charges and support contacts can now differ per delivery area (bound), edited through tabs at the top of the customize screen — one tab per area, the first marked Default. - If an area has no value saved, it inherits from the default area, then region-level values, then built-in defaults. 2.5 Broadcast notifications go region-wide only - "Notify all users" from an admin reaches only devices registered in that admin's region. ===================================================================== 3. SUPERADMIN CONSOLE ===================================================================== 3.1 Regions management - Full list / create / edit screens for regions, each with any number of delivery-area maps (GeoJSON polygons), a name, description and priority per area. Areas are evaluated in priority order; priority 1 is the region default. Duplicate priorities and missing names are rejected in the form and on the server. - Regions cannot be deleted (too much depends on them). - The first region (Mahabubnagar) ships with its two delivery-area maps already loaded. 3.2 Mandatory notification channels per region - Every new region must be created with at least one Telegram channel (bot + destination); the form won't submit without it. - Staff admin accounts are created with an explicit region and role. ===================================================================== 4. ORDERS, NOTIFICATIONS & CHARGES (platform behavior) ===================================================================== 4.1 Order pricing follows the delivery address - Item prices, flash availability, delivery charges and minimum-order thresholds are all taken from the order address's area — not always region 1 as before. An order placed in region 2 is validated and priced with region 2's data. 4.2 Staff alerts are regional - When an order is placed, only admins of that order's region get the push alert (with a tap-through to the order). Orders with no determinable region still alert everyone so nothing is missed. - Order alerts also go to Telegram, one message per region, delivered to every Telegram channel configured for that region. Regions with no channel configured are logged and skipped. - Raising a complaint also alerts the relevant region's admins (based on the complaint's order, else the customer's default address). 4.3 Tags can repeat across regions - The same tag name (e.g. "Fruits") can now exist in multiple regions; names only need to be unique within one region. (Requires the pending migration; until it runs, the old global uniqueness still applies.) ===================================================================== 5. EDGE CASES & SAFETY BEHAVIOR ===================================================================== - No region match: user is told they are outside the service area and can continue by picking a region manually. - No permission / location off: distinct messages and correct Settings destination for each case; manual region pick always available. - App reinstall / corrupted saved data: stored region is validated on launch; unknown values are discarded and the user is asked again. - Empty cart on region/address change: switches over silently, no popups. - Cart lines that survive a move keep working; only real changes are shown. - Slot moves under an hour apply quietly on confirmation; moves over an hour are flagged prominently in the confirmation. - Canceling a region/address confirmation leaves everything exactly as it was (cart, region, selected address). - Rapid repeated switches: overlapping operations are guarded so carts can't corrupt each other. - Addresses without coordinates: area is resolved from the region default; charges fall back down the chain (area → default area → region → built-in). - Areas whose maps overlap: the highest-priority area wins, consistently for detection, pricing and settings. - Deleting a delivery area also cleans up its area-specific settings so no orphaned values linger; editing an area keeps its identity (and its settings) instead of recreating it. - Old devices/tokens with no region recorded are treated as region 1, so nobody silently stops receiving notifications after the upgrade. ===================================================================== 6. INTENTIONALLY UNCHANGED / KNOWN NOTES ===================================================================== - Coupons, reviews, payments and complaint handling (other than the new admin alert) are not region-dependent. - Flash-delivery eligibility of a product is still decided per region. - The legacy fallback vendor page and old REST summary endpoints were removed; all screens use the current data paths. - Super-admins retain full cross-region visibility and action rights in every admin surface.