User UI state

A user's arrangement of the web app belongs to the user account, not to one browser. The client module webapp/js/ui-state.js reads and writes named values through two routes of the auth module, and the server stores them per user in the table auth_user_ui_state. This page explains the data model, the routes, the write coalescing, the conflict rule for the home layout, and which preferences are not stored on the server.

In short¶

• One row holds one key and one JSON value for one user; the key is unique among live rows of that user (src/cluster_erp/modules/auth/ui_state/models.py:13-35).
• GET /api/v1/auth/ui-state returns every key of the signed-in user; PUT /api/v1/auth/ui-state/{key} stores one value (src/cluster_erp/modules/auth/ui_state/routes.py:21-39).
• Both routes take the user id from the session, never from the request, and require authentication only (src/cluster_erp/modules/auth/ui_state/routes.py:15-18).
• A stored value may be at most 262,144 bytes as JSON (src/cluster_erp/modules/auth/ui_state/schemas.py:8-29).
• The client batches writes for 600 ms and flushes pending writes when the page is hidden or closed (webapp/js/ui-state.js:41-73).

How it works¶

Server side¶

The base columns and soft delete come from the shared base model; see base model and ids. An update of a value is recorded by the automatic change history like any other mapped entity; see change history.

Client side¶

loadUiState() reads all keys once per session and shares one request among early callers. A failed read returns null and leaves the local copy in use (webapp/js/ui-state.js:18-39). saveUiState(key, value) updates the in-memory copy, queues the value, and restarts a 600 ms timer; the flush sends one PUT per key with keepalive so that a write survives a page reload (webapp/js/ui-state.js:41-73). visibilitychange to hidden and pagehide flush the queue at once (webapp/js/ui-state.js:58-65). Logout drops the cache and the queue (webapp/js/ui-state.js:75-85).

Keys written by the web app¶

Widget settings such as the Mine or All scope are stored inside the layout value, on the widget item's cfg (webapp/js/widget-scope.js:4-8).

Home layout conflict rule¶

The home layout is cached in local storage and stored on the server. hydrateFromServer() decides which copy wins (webapp/js/home.js:4565-4631):

1. Dock pins, recent searches, density, and the docked button are taken from the server as they are (webapp/js/home.js:4579-4589).
2. If the server has no layout for this device class, a first-time class starts from the PC layout; otherwise the local copy is published to the server (webapp/js/home.js:4590-4615).
3. If both exist, each carries an updatedAt stamp. The server copy replaces the local one only when it is strictly newer; a newer local copy is sent to the server (webapp/js/home.js:4616-4631).

A failed request changes nothing; the local arrangement is never discarded because the server could not be reached (webapp/js/home.js:4565-4570).

Preferences kept in the browser only¶

Why it is built this way¶

• The comment in webapp/js/ui-state.js:1-9 states that a layout kept only in local storage differed per browser, device, and host name, and that a cleared cache looked like a reset.
• The model docstring states that only the owning user, or an administrator acting for them, can change a row (src/cluster_erp/modules/auth/ui_state/models.py:14-21).
• The schema comment states that the size cap stops a user from storing arbitrary amounts of data in the per-user slot (src/cluster_erp/modules/auth/ui_state/schemas.py:8-9).

Rules and boundaries¶

• The project's written engineering rules require browser test suites to use web-client/_ui_state_guard.mjs. The guard runs suites under a dedicated test account so that a suite never changes a real person's layout (web-client/_ui_state_guard.mjs:1-4). See e2e battery.
• Browser tests: web-client/_e2e_dock_pins.mjs, web-client/_e2e_app_wheel.mjs, web-client/_e2e_density.mjs, web-client/_e2e_mobile_home.mjs, web-client/_e2e_command_palette.mjs.

Interaction with other parts¶

• The decision record is server-side UI state.
• Authentication of the two routes is described on authentication and sessions.

Limits and open points¶

• Keys are free strings chosen by the client, between 1 and 60 characters; a longer key is rejected with HTTP 422 before the handler runs (src/cluster_erp/modules/auth/ui_state/models.py:34, src/cluster_erp/modules/auth/ui_state/routes.py:33).
• No route deletes a key. Not determined from code: whether keys of retired features are ever removed.

Terms introduced¶

Related pages¶

• Web app platform
• Home screen, dock, and launcher
• Device classes
• Auth module
• Server-side UI state

Verified against commit 92f8051 on 2026-11-13.