updates on the redesign page for all the pages

2026-05-30 17:54:07 +05:30
parent ba88501bc4
commit b8097efbcf
20 changed files with 8664 additions and 3331 deletions
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(npm install)",
+      "Bash(npm install:*)",
+      "Bash(npm run lint)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run build)",
+      "Bash(npm run build:*)",
+      "Bash(npm start)",
+      "Bash(npm run start:*)",
+      "Bash(yarn)",
+      "Bash(yarn install)",
+      "Bash(yarn lint)",
+      "Bash(yarn build)",
+      "Bash(yarn start)",
+      "Bash(npx eslint:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(ls:*)",
+      "Bash(pwd)",
+      "Bash(wc:*)",
+      "Bash(node -e:*)",
+      "Bash(node --version)"
+    ],
+    "deny": [
+      "Bash(rm -rf /:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git commit --amend:*)",
+      "Bash(git checkout -- .:*)",
+      "Bash(git clean -f:*)",
+      "Bash(git branch -D:*)",
+      "Bash(npm publish:*)",
+      "Bash(yarn publish:*)"
+    ]
+  }
+}
--- a/.claude/skills/nearlexpress-docs/SKILL.md
+++ b/.claude/skills/nearlexpress-docs/SKILL.md
@@ -0,0 +1,409 @@
+---
+name: nearlexpress-docs
+description: "Architecture, navigation flow, per-page API map, optimisation pipeline, and FCM rules for the NearlExpress Console (nearlexpress-xpressconsole-d0ee01adebe9). Load when working anywhere in this repo or when the user asks about its pages (orders, deliveries, dispatch, tenants, pricing, customers, riders, invoices, reports, requests), the AI dispatch solvers (routes.workolik.com / routemate.workolik.com), the optimisation → preview → reconcile → assign → notify pipeline, FCM/Firebase notifications, TanStack Query data flow, or which API endpoint a given page calls."
+metadata:
+  version: 2.0.0
+---
+
+# NearlExpress Console — Project Reference
+
+A React 18 operator console for the NearlExpress dispatch platform. Operators use it to manage orders, run the AI dispatch optimiser, watch a live map of riders, edit tenants/pricing/invoices, and pull BI reports. Production users are warehouse staff, not end customers.
+
+This skill is the **knowledge** Claude needs about the system (what each page does, which API each calls, how the pieces wire together). The **rules** Claude must follow when editing live in the root `CLAUDE.md` — don't restate them here.
+
+---
+
+## 1. Architecture at a glance
+
+- **Brand colour: `#662582` (NearlExpress purple)** — defined in `src/themes/theme/default.js` as `primary.main`. Used by the sidebar, page headers, dialog/popup headers, KPI primary tiles, search bars, edit-action buttons. Gradient pair `#662582 → #9255AB`. Status badges use a separate semantic palette (amber/indigo/cyan/teal/emerald/red/orange) — see root `CLAUDE.md` §6.
+- **Stack:** React 18.2 + react-app-rewired (CRA), MUI 5, TanStack Query 5, Redux Toolkit, react-router 6, axios, dayjs, leaflet, firebase 10 (FCM), notistack, formik+yup, react-dnd.
+- **Entry:** `src/index.js` → providers (Redux store, QueryClient, Router, ThemeCustomization, Notistack) → `src/App.js`.
+- **Auth gate:** `App.js` checks `localStorage.getItem('authname')` — empty redirects to `/login`. Login posts to `jupiter.nearle.app/users/console/login` with `configid: 9` and the device's FCM token.
+- **Routing:** `src/routes/MainRoutes.js` declares all `/nearle/*` routes, lazy-loaded via `components/Loadable`. Sidebar items are declared in `src/menu-items/nearle.js`.
+- **Data layer:** every server call lives in `src/pages/api/api.js`. Pages call those exports via `useQuery` / `useInfiniteQuery` / `useMutation`. Query keys MUST include every filter parameter so caching invalidates correctly.
+- **State:** Redux Toolkit slices (`fcmSlice`, `loginUserSlice`, `menu`, `snackbar`, `toastSlice`, `auth`) for cross-page state; per-page UI state stays in `useState`.
+- **Two API bases:** `process.env.REACT_APP_URL` (primary) and `process.env.REACT_APP_URL2` (used for `/users/update`, `/tenants/update`, archival `/orders/getorders`, rider logs).
+- **External services (hardcoded):** `routes.workolik.com` (Bike/Manual solver), `routemate.workolik.com` (Auto/multi-trip solver), `jupiter.nearle.app` (login + final delivery commit).
+- **localStorage keys:** `authname`, `userid`, `roleid`, `userfcmtoken`, `applocations` (cached zone list).
+- **Notifications:** FCM init in `App.js` via `firebase_notification/notification.js` (`generateToken`, `initFirebaseNotificationListener`). Service worker at `public/firebase-messaging-sw.js`.
+
+---
+
+## 2. End-to-end console flow
+
+```mermaid
+flowchart TD
+    classDef entry   fill:#f9f6ff,stroke:#a78bfa,stroke-width:2px,color:#2e1065;
+    classDef auth    fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#831843;
+    classDef nav     fill:#eef2ff,stroke:#6366f1,stroke-width:2px,color:#312e81;
+    classDef core    fill:#e0f2fe,stroke:#0ea5e9,stroke-width:2px,color:#0c4a6e;
+    classDef sub     fill:#ecfeff,stroke:#06b6d4,stroke-width:1.5px,color:#155e75;
+    classDef action  fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f;
+    classDef ext     fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
+    classDef report  fill:#f5f5f4,stroke:#78716c,stroke-width:1.5px,color:#292524;
+    classDef state   fill:#fdf4ff,stroke:#8b5cf6,stroke-width:1.5px,color:#581c87;
+
+    Boot([Browser load<br/>src/index.js]):::entry
+    Providers["Providers wiring<br/>Redux · QueryClient · Router · Theme · Notistack"]:::entry
+    App["src/App.js<br/>localStorage('authname') gate"]:::auth
+    FCMInit["generateToken()<br/>initFirebaseNotificationListener()"]:::auth
+    SW["public/firebase-messaging-sw.js"]:::auth
+    Login[/"/login<br/>pages/nearle/login1.js"/]:::auth
+
+    Boot --> Providers --> App
+    App -- no authname --> Login
+    Login -- POST jupiter.nearle.app/users/console/login --> AuthOK{Auth OK?}
+    AuthOK -- yes (save authname/userid/roleid/userfcmtoken) --> Layout
+    AuthOK -- no --> Login
+    App --> FCMInit --> SW
+
+    Layout["layout/MainLayout<br/>Sidebar + Header + Outlet"]:::nav
+    Sidebar["menu-items/nearle.js"]:::nav
+    Layout --- Sidebar
+    Sidebar --> Dispatch
+    Sidebar --> Orders
+    Sidebar --> Deliveries
+    Sidebar --> Tenants
+    Sidebar --> Pricing
+    Sidebar --> Customers
+    Sidebar --> Riders
+    Sidebar --> Invoice
+    Sidebar --> ReportsHub
+
+    Dispatch[/"/nearle/dispatch<br/>Live Map · Riders · Batches"/]:::core
+    Orders[/"/nearle/orders<br/>Orders Dashboard"/]:::core
+    Deliveries[/"/nearle/deliveries<br/>Dispatched Deliveries"/]:::core
+    Tenants[/"/nearle/tenants<br/>Client/Tenant Management"/]:::core
+    Pricing[/"/nearle/pricing<br/>Pricing Matrix (master-detail)"/]:::core
+    Customers[/"/nearle/customers<br/>Customer Directory"/]:::core
+    Riders[/"/nearle/riders<br/>Rider Pool"/]:::core
+    Invoice[/"/nearle/invoice<br/>Billing"/]:::core
+    Requests[/"/nearle/requests<br/>Expense Approvals"/]:::core
+    ReportsHub[/"/nearle/reports/*<br/>BI Suite"/]:::core
+
+    OrdersCreate[/"/orders/create"/]:::sub
+    OrdersMulti[/"/orders/createorders"/]:::sub
+    OrdersDetails[/"/orders/details"/]:::sub
+    OrdersPreview[/"/orders/preview"/]:::sub
+    DispatchPreview[/"/dispatch/preview"/]:::sub
+    RidersCreate[/"/riders/create"/]:::sub
+    RidersEdit[/"/riders/edit"/]:::sub
+    ClientsCreate[/"/clients/create"/]:::sub
+    CustomerCreate[/"/customer/create"/]:::sub
+    InvoicePreview[/"/invoice/preview"/]:::sub
+    ReportsOS[/"/reports/orderssummary"/]:::report
+    ReportsOD[/"/reports/ordersdetails"/]:::report
+    ReportsRS[/"/reports/riderssummary"/]:::report
+    ReportsRL[/"/reports/riderslogs"/]:::report
+
+    Orders --> OrdersCreate
+    Orders --> OrdersMulti
+    Orders --> OrdersDetails
+    Riders --> RidersCreate
+    Riders --> RidersEdit
+    Tenants --> ClientsCreate
+    Customers --> CustomerCreate
+    Invoice --> InvoicePreview
+    ReportsHub --> ReportsOS
+    ReportsHub --> ReportsOD
+    ReportsHub --> ReportsRS
+    ReportsHub --> ReportsRL
+
+    %% Optimisation pipeline
+    SelectOrders["Select N pending orders"]:::action
+    ChooseSolver{"Choose Dispatch Mode"}:::action
+    SolverBike["Mode 1 · Bike<br/>POST routes.workolik.com<br/>/optimization/riderassign"]:::ext
+    SolverAuto["Mode 2 · Auto<br/>POST routemate.workolik.com<br/>/optimization/riderassign"]:::ext
+    SolverManual["Mode 0 · Manual<br/>POST routes.workolik.com<br/>/optimization/createdeliveries"]:::ext
+    Reconcile["POST routes.workolik.com<br/>/optimization/reconcile-steps"]:::ext
+    FinalAssign["POST jupiter.nearle.app<br/>/deliveries/createdeliveries"]:::ext
+    NotifyRider["POST /utils/notifyuser (FCM)"]:::ext
+
+    Orders --> SelectOrders --> ChooseSolver
+    ChooseSolver -- Bike --> SolverBike
+    ChooseSolver -- Auto --> SolverAuto
+    ChooseSolver -- Manual --> SolverManual
+    SolverBike --> OrdersPreview
+    SolverAuto --> OrdersPreview
+    SolverManual --> OrdersPreview
+    OrdersPreview --> DispatchPreview
+    DispatchPreview -. manual edit .-> Reconcile
+    Reconcile --> DispatchPreview
+    DispatchPreview -- Assign --> FinalAssign
+    FinalAssign --> NotifyRider
+    FinalAssign -- redirect --> Deliveries
+
+    %% Deliveries actions
+    DChangeRider["Change Rider"]:::action
+    DCancel["Cancel Delivery"]:::action
+    DUpdate["Update Amount / Notes"]:::action
+    Deliveries --> DChangeRider --> NotifyRider
+    Deliveries --> DCancel --> NotifyRider
+    Deliveries --> DUpdate
+
+    %% Cross-cutting
+    subgraph CROSS [Cross-cutting infrastructure]
+      direction LR
+      Store["Redux: fcm · login · menu · snackbar · toast · auth"]:::state
+      QC["TanStack Query (cache + infinite scroll)"]:::state
+      Env["REACT_APP_URL · REACT_APP_URL2 · REACT_APP_GOOGLE_MAPS_API_KEY"]:::state
+      LS["localStorage: authname · userid · roleid · userfcmtoken · applocations"]:::state
+    end
+
+    Layout -. reads .-> Store
+    Layout -. reads .-> LS
+    Orders & Deliveries & Dispatch & Tenants & Pricing & Customers & Riders & Invoice -. fetches via .-> QC
+    QC -. base URLs from .-> Env
+```
+
+---
+
+## 3. Optimisation pipeline (sequence)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as Operator
+    participant O as /nearle/orders
+    participant S as Solver (routes/routemate.workolik.com)
+    participant P as /nearle/dispatch/preview
+    participant R as reconcile-steps
+    participant J as jupiter.nearle.app
+    participant D as /nearle/deliveries
+    participant F as FCM (rider device)
+
+    U->>O: Select pending orders (checkbox)
+    U->>O: Pick dispatch mode (Bike / Auto / Manual)
+    O->>S: POST riderassign or createdeliveries
+    S-->>O: Optimised route & assignments
+    O->>P: Redirect to preview
+    U->>P: Drag steps / swap rider (optional)
+    P->>R: POST reconcile-steps (after each manual edit)
+    R-->>P: Updated, validated sequence
+    U->>P: Confirm "Assign"
+    P->>J: POST /deliveries/createdeliveries
+    J-->>P: 200 OK
+    P->>F: POST /utils/notifyuser (per rider)
+    P->>D: Redirect to deliveries dashboard
+```
+
+**Hard rule:** never call `POST /deliveries/createdeliveries` after manual edits without calling `POST /optimization/reconcile-steps` first. Skipping reconcile corrupts route sequences.
+
+---
+
+## 4. Page-by-page API map
+
+> Every named function below lives in `src/pages/api/api.js`. URLs use `REACT_APP_URL` unless noted otherwise (`REACT_APP_URL2`).
+
+### 4.1 Authentication
+- **Page:** `pages/nearle/login1.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `https://jupiter.nearle.app/live/api/v1/users/console/login` | `POST` | *direct axios* | Console staff auth. Requires `authname`, `password`, `configid: 9`, `userfcmtoken`. |
+| `/partners/getlocations/?userid={id}` | `GET` | `fetchAppLocations` | Operational locations assigned to the operator. |
+| `REACT_APP_URL2/users/update` | `PUT` | `updateUser` | First-time password setup / change password. |
+
+### 4.2 Orders
+- **Page:** `pages/nearle/orders/orders.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/orders/getordersummary/?applocationid={appId}` | `GET` | `fetchPercentageData` / `fetchorderscount` | Status statistics (total, pending, delivered, cancelled). |
+| `/orders/tenant/getorders/` | `GET` | `fetchOrders` | Infinite paginated order list. |
+| `/utils/getapptypes/?tag=paymentmode` | `GET` | `fetchPaymentType` | Payment-mode dropdown options. |
+| `/partners/getriders/?applocationid={appId}` | `GET` | `fetchRidersList` | Active riders for manual assignment. |
+| `/tenants/gettenants/?applocationid={appId}&status=active` | `GET` | `getTenants` | Active tenants for filter. |
+| `/tenants/gettenantlocations/?tenantid={appId}` | `GET` | `gettenantlocations` | Store branches for a tenant. |
+| `/partners/getallriders?partnerid=64` | `GET` | `getallriders` | Full driver pool for bulk dispatch. |
+| `/orders/updateorder` | `PUT` | `cancelOrder` | Cancel a single order. |
+| `/orders/updatemultipleorders` | `PUT` | `cancelMultipleOrder` | Bulk cancel. |
+
+### 4.3 AI dispatch / optimisation
+- **Pages:** `orders/orders.js`, `dispatch/Preview.js`
+
+| Endpoint | Method | Function | Mode |
+| --- | --- | --- | --- |
+| `https://routes.workolik.com/api/v1/optimization/createdeliveries` | `POST` | `createOptimisationDeliveries` | Mode 0 · Manual |
+| `https://routes.workolik.com/api/v1/optimization/riderassign?hypertuning_params={params}` | `POST` | `createAutomationDeliveries` | Mode 1 · Bike hyper-tuning |
+| `https://routemate.workolik.com/api/v1/optimization/riderassign?strategy=multi_trip` | `POST` | `createAutomationDeliveries` | Mode 2 · Auto multi-trip |
+| `https://routes.workolik.com/api/v1/optimization/reconcile-steps` | `POST` | `reconcileSteps` | Validate sequence after manual edits |
+| `https://jupiter.nearle.app/live/api/v1/deliveries/createdeliveries` | `POST` | `finalCreatedeliveries` | Commit assignments |
+
+### 4.4 Deliveries
+- **Page:** `pages/nearle/deliveries/deliveries.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/deliveries/getdeliveries/` | `GET` | `fetchDeliveries` | Streams delivery records (infinite query). Client-side wave filter by `assigntime`. |
+| `/deliveries/deliverysummary/` | `GET` | `fetchCountAPI` / `fetchPercentageAPI` | Lifecycle chip counts (pending/accepted/arrived/picked/active/skipped/delivered/cancelled). |
+| `/orders/getorderdetails?orderheaderid={id}` | `GET` | `getorderdetails` | Items detail for invoice preview. |
+| `/deliveries/updatedelivery` | `PUT` | `cancelDeliveryAPI` | Cancel with feedback. |
+| `/deliveries/updatedelivery` | `PUT` | `changeRiderAPI` | In-transit rider reassignment (also resets `assigntime`). |
+| `/deliveries/updatedelivery` | `PUT` | `updateDeliveryAPI` | Amount / notes update. |
+| `/utils/notifyuser` | `POST` | `notifyRider` | FCM push to rider's device. Required after every rider-affecting mutation. |
+
+### 4.5 Tenants
+- **Page:** `pages/nearle/clients/Tenants.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/tenants/getalltenants/?status={status}&applocationid={appId}&keyword={kw}&pageno={p}&pagesize={n}&moduleid=6` | `GET` | `getalltenants` | Onboarded tenants. |
+| `/tenants/gettenantsummary/?moduleid=6&applocationid={appId}` | `GET` | `gettenantsummary` | Tab counts. |
+| `/tenants/getpricinglist/?moduleid=6&applocationid={appId}` | `GET` | `getpricinglist` | Subscription / billing contracts. |
+| `/tenants/gettenantpricing/?tenantid={id}` | `GET` | *direct axios* | Tenant base pricing config. |
+| `REACT_APP_URL2/tenants/update` | `PUT` | *direct axios* | Profile / coordinates / approval. |
+| `REACT_APP_URL2/tenants/update/services` | `PUT` | *direct axios* | Customised tenant service rates. |
+
+### 4.6 Pricing
+- **Page:** `pages/nearle/clientPricing/clientPricing.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/utils/getallpricing/?applocationid={appId}` | `GET` | *direct axios* | Base pricing models for the zone. |
+
+### 4.7 Customers
+- **Page:** `pages/nearle/customers/customers.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/customers/getcustomersummary?applocationid={appId}` | `GET` | `getcustomersummary` | Customer count summary. |
+| `/customers/getallcustomers/` | `GET` | `getallcustomers` | Searchable directory (infinite query). |
+| `/customers/update` | `PUT` | *direct axios* | Update customer profile + address. |
+
+### 4.8 Riders
+- **Pages:** `riders/riders.js`, `createrider.js`, `editRider.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/partners/getallriders/?applocationid={appId}&pageno={p}&pagesize=20&keyword={kw}&status={status}` | `GET` | `fetchAllRiders` | Filtered driver list. |
+| `/partners/getallridersummary/?applocationid={appId}&status={status}` | `GET` | `getallridersummary` | Crew breakdowns. |
+| `/partners/getriders/?applocationid={appId}&pageno={p}&pagesize=20&keyword={kw}` | `GET` | `fetchRiders` | Active/online riders. |
+| `/utils/getriderstatus` | `GET` | `getriderstatus` | Check-in history. |
+| `/partners/createrider` | `POST` | *direct axios* | Onboard rider. |
+| `/partners/update/rider` | `PUT` | *direct axios* | Edit rider vehicle/license/bank/status. |
+
+### 4.9 Invoices
+- **Pages:** `invoice/invoice.js`, `invoicePreview.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/invoice/getinvoiceinsight` | `GET` | `fetchinvoiceinsight` | Global accounting summary. |
+| `/invoice/getallinvoice/?billstatus={status}` | `GET` | `fetchdeliverylist` | Invoice list (Paid vs Unpaid tabs). |
+
+### 4.10 Dispatch (live tracker)
+- **Page:** `pages/nearle/dispatch/Dispatch.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/utils/getriderperiodiclogs?userid={id}` | `GET` | `getRiderPeriodicLogs` | Rider GPS/battery/connectivity/current order — polled for live map. |
+| `https://routes.workolik.com/api/v1/batch/efficiency` | `POST` | `fetchBatchEfficiency` | Per-batch solver efficiency rating. |
+
+### 4.11 Reports / BI
+- **Pages:** `reports/ordersSummary.js`, `ordersDetails.js`, `ridersSummary.js`, `ridersLogs.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/deliveries/getreportsummary/?applocationid&tenantid&locationid&fromdate&todate` | `GET` | `getreportsummary` | Aggregated fulfilment. |
+| `/deliveries/getreportlocationsummary/?...` | `GET` | `getreportlocationsummary` | Per-branch breakdown. |
+| `REACT_APP_URL2/orders/getorders/?fromdate&todate&applocationid&pageno&pagesize` | `GET` | `fetchorderdetails` | Archival historical orders. |
+| `/deliveries/getriderbydelivery/?applocationid&tenantid&locationid&fromdate&todate` | `GET` | `getriderbydelivery` | Per-rider delivery trace. |
+| `/deliveries/deliverysummary/?applocationid&fromdate&todate` | `GET` | `fetchCount` | Volume metrics over range. |
+| `/deliveries/getridersummary/?applocationid&fromdate&todate` | `GET` | `fetchRidersSummary` | Per-rider performance stats. |
+| `/partners/getpartners` | `GET` | `fetchLocations` | Merchant locations for routing. |
+| `REACT_APP_URL2/partners/getriderlogs/?applocationid&fromdate&todate&keyword` | `GET` | `fetchRidersLogs` | Driver login / checkout audit. |
+
+### 4.12 Requests (expense reimbursements)
+- **Page:** `pages/nearle/requests/requests.js`
+
+| Endpoint | Method | Function | Purpose |
+| --- | --- | --- | --- |
+| `/payments/requests/getpaymentrequest/?partnerid={tid}&status={0 or 1}` | `GET` | `clientdetailspending` / `clientdetailsapproved` | Status 0 = Pending, 1 = Approved. |
+
+---
+
+## 5. Route → file map (full)
+
+| Route | File | Lazy import name |
+| --- | --- | --- |
+| `/login` | `pages/nearle/login1.js` | `Login` |
+| `/nearle/dispatch` | `pages/nearle/dispatch/Dispatch.js` | `Dispatch` |
+| `/nearle/dispatch/preview` | `pages/nearle/dispatch/Preview.js` | `DispatchPreview` |
+| `/nearle/orders` | `pages/nearle/orders/orders.js` | `Orders` |
+| `/nearle/orders/preview` | `pages/nearle/orders/OrdersPreview.js` | `OrdersPreview` |
+| `/nearle/orders/create` | `pages/nearle/orders/createorder1.js` | `Createorder1` |
+| `/nearle/orders/createorders` | `pages/nearle/orders/multipleOrders.js` | `MultipleOrders` |
+| `/nearle/orders/details` | `pages/nearle/orders/details.js` | `Details` |
+| `/nearle/deliveries` | `pages/nearle/deliveries/deliveries.js` | `Deliveries` |
+| `/nearle/tenants` | `pages/nearle/clients/Tenants.js` | `Tenants` |
+| `/nearle/clients/create` | `pages/nearle/clients/createclient.js` | `Createclient` |
+| `/nearle/pricing` | `pages/nearle/clientPricing/clientPricing.js` | `ClientsPricing` |
+| `/nearle/customers` | `pages/nearle/customers/customers.js` | `Customers` |
+| `/nearle/customer/create` | `pages/nearle/clients/createCustomer.js` | `CreateCustomer` |
+| `/nearle/riders` | `pages/nearle/riders/riders.js` | `Riders` |
+| `/nearle/riders/create` | `pages/nearle/riders/createrider.js` | `Createrider` |
+| `/nearle/riders/edit` | `pages/nearle/riders/editRider.js` | `EditRider` |
+| `/nearle/invoice` | `pages/nearle/invoice/invoice.js` | `Invoice` |
+| `/nearle/invoice/preview` | `pages/nearle/invoice/invoicePreview.js` | `InvoicePreview` |
+| `/nearle/requests` | `pages/nearle/requests/requests.js` | `Requests` |
+| `/nearle/reports/orderssummary` | `pages/nearle/reports/ordersSummary.js` | `OrdersSummary` |
+| `/nearle/reports/ordersdetails` | `pages/nearle/reports/ordersDetails.js` | `OrdersDetails` |
+| `/nearle/reports/riderssummary` | `pages/nearle/reports/ridersSummary.js` | `RidersSummary` |
+| `/nearle/reports/riderslogs` | `pages/nearle/reports/ridersLogs.js` | `RidersLogs` |
+| `/viewprofile` | `pages/nearle/viewProfile.js` | `ViewProfile` |
+| `/maintenance/{404,500,under-construction,coming-soon}` | `pages/maintenance/*` | — |
+
+---
+
+## 6. Per-page state-flow primer
+
+```mermaid
+flowchart LR
+    subgraph PAGE [Any operator page]
+        UI[React component] --> QH["useQuery / useInfiniteQuery / useMutation"]
+        UI --> US["useState (local UI state)"]
+    end
+    QH -- "queryKey = [name, appId, filters...]" --> Cache["TanStack Query cache"]
+    QH -- queryFn --> ApiLayer["pages/api/api.js"]
+    ApiLayer --> AxRaw["axios (raw)"]
+    ApiLayer -. some calls .-> AxInt["utils/axios.js (401 interceptor)"]
+    AxRaw --> EnvURL["process.env.REACT_APP_URL"]
+    AxRaw --> EnvURL2["process.env.REACT_APP_URL2"]
+    AxRaw --> ExtOpt["routes / routemate / jupiter (hardcoded)"]
+    UI -. dispatches .-> RTK["Redux store"]
+    UI -. emits toast .-> Notistack
+    UI -. reads .-> LS["localStorage"]
+```
+
+**Conventions for new pages:**
+- Query keys must include every filter parameter so caching invalidates correctly.
+- Use `useInfiniteQuery` for paginated rows; auto-drain with an `IntersectionObserver` on a sentinel `<div ref={loadMoreRef} />` at the bottom of the `TableContainer`. The canonical pattern is in `deliveries.js` (search for `useInfiniteQuery({` and the adjacent `IntersectionObserver` block).
+- Mutations: after success, call `.refetch()` on every related query. Project does not yet use `queryClient.invalidateQueries`.
+- Errors → `OpenToast(message, 'error', 2000)` from `components/third-party/OpenToast`.
+
+---
+
+## 7. FCM rules
+
+- Initialised once in `App.js` (`generateToken` + `initFirebaseNotificationListener`).
+- After any mutation affecting a rider (assign, cancel, change rider), call `POST /utils/notifyuser` with the target rider's `userfcmtoken`.
+- The service worker (`public/firebase-messaging-sw.js`) handles background tokens and desktop notifications. Subtle bugs there cause silent delivery failures — do not edit without a clear reason.
+
+---
+
+## 8. Glossary
+
+- **Zone / `applocationid`** — operator's warehouse / operational hub. `0` means "All Zones". Every list endpoint takes this.
+- **Tenant** — the business / brand whose orders flow through the platform.
+- **Location** — a tenant's branch within a zone.
+- **Rider / Partner** — the delivery driver.
+- **Batch / Wave** — a time-of-day slot (Morning 0–8, Afternoon 9–12, Evening 16–19). Bucketed by `assigntime` on the deliveries page in **local** time to match dispatch's bucketing.
+- **Slab** — a pricing tier (base + per-km + min-km + max-km + min-orders).
+- **Solver hypertuning** — the optimiser's strategy (Balanced, Fuel Saver, Aggressive, Strict Zones).
+
+---
+
+## 9. Cross-references
+
+- Project rules and conventions Claude must follow are in the root `CLAUDE.md`. Don't restate them here.
+- Page-level design system tokens (the `DT` block, `pillFieldSx`, `SoftPaper`, `AccentAvatar`) are documented in `CLAUDE.md` §6 — the implementation source-of-truth is `src/pages/nearle/deliveries/deliveries.js` lines 104–297.