Skip to content

0033 — Server-side pagination for Accounts Portal record lists (Nov 2026)

Status: accepted (2026-11-03), first tranche shipped: the shared architecture + Orders. Builds on ADR 0032 (All Time defaults).

Problem

Every list page called getX() → apiGetAllRows, which pages through the WHOLE filtered result (200 rows a request) into browser memory, then the table slices it on screen. Search, filters, sort, summary cards and exports all ran on that in-memory copy, and the guard stops at 20,000 rows (it errors rather than truncating). With All Time as the default this becomes the normal case as history grows.

What the audit found

  • The backend already pages every accounting list (dto.ParsePage, 50 default / 200 max, {rows,total,page,pageSize}), with a stable ORDER BY ..., id and a COUNT(*) for the total.
  • What was missing for real server-side lists: server filters (channel, invoice status, amount range), server sort, a database summary (the cards were sum(rows)), "fetch exactly these ids" for selections spanning pages, and an unbounded All Time (ADR 0032 used a 2000-01-01 floor and an end-of-today ceiling).
  • In live mode the Orders "GST charged" and "Refunded" cards were sum of placeholder zeros (the list wire carries no tax breakdown). The summary now reads the real columns.

Decision (shared architecture)

  1. All Time is unbounded on the server. dto.ParseRange honours ?allTime=true (year 1 … year 9999); the portal sends it together with from/to so an endpoint that does not read it keeps a sane range. No arbitrary floor, no "today" ceiling (a record created a moment later is never missed). This applies to every endpoint that uses ParseRange.
  2. One page per request. Frontend: getXPage(query) returns Paginated<T>; useServerPaging(matchKey) holds page / size / sort and returns to page 1 whenever the set of matches changes (in the same render) or the size/sort changes, and clamps a page that no longer exists; DataTable has a server mode (manual pagination and sorting, total from the server, only server-sortable columns sortable, selection kept as ids, previous rows dimmed while loading). Stale responses are dropped by useAsyncData; free text is debounced.
  3. Summary = database aggregate over the same filter (SummarizeOrders), requested separately, so cards never change with the page. GST is summed only over orders that carry a tax snapshot and says how many; nothing is estimated.
  4. One filter, three queries. orderWhere is shared by the page, its COUNT and the summary, so they cannot disagree. Sort keys are a whitelist ending in the unique id (equal timestamps page deterministically). All values are bind parameters; ids is UUID-validated and capped at 500.
  5. Exports never truncate and never hold unbounded memory. "All filtered" pages through the server 200 at a time (collectAllPages), checks the first response's total against MAX_EXPORT_ROWS (50,000) and stops with an error if it is larger. "This page" is separate and labelled. "Selected" re-reads exactly the selected ids from the server, so a selection spanning pages is complete.

Module inventory

Module Route Before Now
Orders /orders all rows in browser server-paged, server filters/sort/summary/exports
Sales register (line-based) /sales-register all rows not migrated: needs an invoice-line-level filter/summary; unbounded All Time applies
Invoices, Payments, Settlements /invoices, /payments, /settlements all rows not migrated; unbounded All Time applies
Purchases, Suppliers, Expenses all rows not migrated (expenses already has its own server-paged register endpoint)
Customers, Notes, Returns, Documents, Audit logs, Report/Filing history, Reconciliation all rows not migrated
Simple Orders / Invoices /simple/* all rows not migrated
Dashboards, GST, TDS, auditor reports, deliveries, warehouse period / own queue out of scope (period reports; warehouse has its own paged queue)

The 20,000-row guard still protects every list that is not migrated yet: it errors rather than truncating.

Not changed

Business rules, statuses, amounts, permissions, the warehouse workflow and label, invoice issuance flags, GST/TDS period logic.

Limits worth knowing

  • Offset paging: a record created while you are on page 3 can shift later pages by one on the next request. Counts and the summary are re-read with every filter change.
  • Orders sort: the list sorts by created date (default), amount or order number across the whole result; the other columns are not sortable in server mode because they cannot be sorted across pages.
  • The channel filter is real but APP is the only channel.

Amendment (2026-11-03): Orders advanced filters

The four filters that PR #159 left ignored in live mode are server filters (PR #160), each from data the system already records, shared by the list, COUNT, summary and the all-filtered export:

  • Customer state - the delivery-address state, matched against every spelling the invoice engine's GstStateCodeFromValue maps to that GST code (dto.GstStateSpellings). A spelling the engine does not recognise matches no state; nothing is fuzzy-matched.
  • GST treatment - the order's stored tax snapshot: INTRA_STATE (CGST+SGST charged), INTER_STATE (IGST charged), NO_SNAPSHOT (no tax figures stored). Nothing is inferred and no GST calculation was touched.
  • Payment method - orders.payment_mode (credits only / gateway only / credits + gateway). The earlier list (UPI, COD, ...) was never recorded on orders and was removed.
  • Delivery status - warehouse shipment stage plus order status: awaiting shipping / packed / dispatched / delivered. Courier-tracking states (in transit, RTO ...) are recorded nowhere, so they are not offered. Read-only on warehouse tables.

Invalid values return 422. The remaining list modules in the inventory above are still not migrated.