Admin interface

An admin screen is a filtered query with a chart on top, and it fails in the same handful of ways every time: a spinner with nothing behind it, an empty table that might be a failure, a filter that quietly matches everything, an export that dies at ten thousand rows.

Two halves — the server pipeline and the client contract — plus the four states, which is the section to read first if you only read one.

---

1. The four states are mandatory

Every screen explicitly handles all four. Not one of them is implicit, and a missing one is a broken screen, not a rough edge.

State	What the user sees	When
Initial / empty	An empty state with a call to action	First load, no filter applied yet
Loading	Skeleton or spinner, submit disabled	While fetching
Success	The data	Response OK
Error	A visible error, controls re-enabled	Fetch failed, or the response carries an error

Empty, missing and broken must look different. Collapsing them into one blank panel is what makes a defect unreportable: the user cannot describe what they saw, because they saw nothing. That is the same rule as padosoft-failure-visibility, which is where the server side of it lives.

An error state that leaves the submit button disabled is the worst of the four: the screen is now unrecoverable without a reload.

2. Server pipeline — the order matters

Build in this order, because each layer defines the contract of the next:

Enum  →  DTO  →  FormRequest  →  Service (query)  →  Service (metrics)  →  Controller  →  Route  →  Export

Layer	Holds
Enum	The stat/metric types, the periods, the statuses. One source for what the screen can ask for
DTO	The filter object: typed, explicit, the only thing the services accept
FormRequest	Validation and normalisation of the HTTP input; it builds the DTO
Service (query)	The master query. Filtering, grouping and pagination in SQL, not in PHP
Service (metrics)	KPI and derived values, computed from the same filtered set
Controller	Translates: DTO in, resource out. No query, no business rule
Route	In the admin group, with the middleware that group carries
Export	The same filtered set, streamed

The filter DTO is the contract. When the screen, the export and the KPI cards each build their own filter, they drift, and the export stops matching what is on screen — which is the bug that gets reported as "the numbers are wrong".

Caps are part of the contract too: a maximum date range, a maximum number of elements, a page size. Put them in the DTO and send them to the client (§3) so it can tell the user before the request.

3. The data contract across the boundary

The client is configured by the server, in one place, explicitly. No hardcoded URLs in the frontend, no global variables, no route helpers embedded in the client bundle.

Send the endpoints and the limits as data — a props object for a React root, a data-* payload for a server-rendered container:

<AdminPanel
  endpoints={{ analyze, export: exportUrl, autosuggest, breakdown }}
  limits={{ maxDays, maxItems }}
/>

Why it matters beyond tidiness: when the routes live in the server's hands, renaming one is a server change with a compiler or a route list behind it. When they are strings in the client, renaming one is a silent 404 at runtime, on the screen nobody opened yet.

Keep the shape in one typed place shared by the modules below, and derive filter options from the real domain — the enum, the database, the API — never from a hardcoded sample list that will diverge the first time a value is added.

4. Client modules

Split by responsibility, not by screen. Each is independently testable and none of them knows about the DOM of another:

Module	Owns
api	Every call: the CSRF/auth header, the error translation, the abort signal
filters	The filter state and its widgets, including autosuggest
table	Rows, sorting, the expandable detail
chart	Rendering and, crucially, teardown before re-render
kpi	The cards and their thresholds
utils	Pure formatters — no fetching, no DOM

Two rules that come from real breakage:

• Destroy a chart before drawing it again. A chart library that keeps its own canvas will stack instances on a filter change: the visible symptom is a tooltip showing values from a query you ran two filters ago.
• Delegate events for anything inside a re-rendered list. A handler bound to a row disappears with the row and takes the expand toggle with it.

5. Autosuggest on a foreign key

A select over a foreign table is a query, not a dropdown:

• minimum input length before the first request (two characters), so an empty focus does not scan the table;
• a debounce on typing — the request that matters is the one after the user stopped;
• cache the responses for the session;
• the current value must render even when it is not in the first page of results: hydrate the selected option from the server when the form is rendered, or an edit screen shows an empty box over a set value;
• the endpoint returns id and label only. An autosuggest that returns entities becomes a data leak the day someone adds a column.

6. Export

The export runs the same filtered query as the screen — the same DTO, not a reimplementation — and streams. Loading the result set into memory to build a file is the pattern that works on the developer's dataset and dies on production's.

If it can exceed a few seconds, it is a job with a notification, not a synchronous response. A download that times out behind a proxy leaves no trace anywhere for the user to report.

7. Design tokens, and the one exception

Colours, spacing and typography come from the design tokens, in the markup and in any markup the client injects. A literal hex in a template is the thing that survives a restyle and then looks broken next to everything else.

The exception: a charting or canvas API that receives colours as values cannot resolve CSS variables, so a resolved value is correct there. Read the token and pass its computed value rather than hardcoding a different hex — otherwise the chart drifts from the theme, and it drifts silently.

---

Gotchas

• A filter that matches everything when it is empty is the most expensive default in an admin panel: the first query of the day scans the table. Decide explicitly what "no filter" means, and prefer requiring one.
• KPI cards computed from a different query than the table will disagree, and the user will trust neither. One filtered set feeds both.
• Server-side pagination or nothing. A table that paginates in the client has already fetched everything.
• The empty state is not a design nicety: without it, every failure mode renders identically (§1).
• An admin route outside the admin group keeps answering, without that group's auth. The security side is in padosoft-laravel-security-review; the listing that leaks is usually the one added in a hurry.
• Do not invent the layout. Read where the neighbouring admin screens put their services, requests and client modules before creating files.

Checklist

• All four states handled; empty, missing and broken look different; controls re-enabled on error
• Enum → DTO → FormRequest → Service(query) → Service(metrics) → Controller → Route → Export
• One filter DTO feeding screen, KPI and export
• Caps (date range, item count, page size) in the DTO and sent to the client
• Endpoints and limits passed from the server; no hardcoded URL in the client
• Client split into api / filters / table / chart / kpi / utils
• Chart destroyed before re-render; delegated events in re-rendered lists
• Autosuggest: min length, debounce, cache, selected value hydrated, id+label only
• Export streams the same filtered query; queued if it can be slow
• Design tokens everywhere; resolved values only where an API cannot read CSS variables

Final report

Screen: <domain>
Server: enum · dto · request · service(query) · service(metrics) · controller · route · export
Contract: endpoints+limits passed from the server — <where>
States: initial | loading | success | error — all handled? yes/no
Caps: <range> · <items> · <page size>
Export: <sync|queued>, same DTO: yes/no
Open: <…>