u

AGENTS.md

@@ -49,8 +49,8 @@ flow:
     component: dashfront
     runtime: React 19 (PureComponent & Function Components)
     state_layers:
-      automats: [artikelAutomat, deliveryEditorAutomat, authAutomat, supplierAutomat, navigationAutomat, userSettingsAutomat, companyAutomat, categoryAutomat, brandAutomat, unitAutomat, posterminalAutomat]
-    transport: src/api (http(), ApiClient)
+      automats: [artikelAutomat, articleSearchAutomat, articleIndexAutomat, deliveryEditorAutomat, authAutomat, sseAutomat, supplierAutomat, navigationAutomat, userSettingsAutomat, companyAutomat, categoryAutomat, brandAutomat, unitAutomat, posterminalAutomat, deliveryAutomat, quoteAutomat, orderAutomat, entityAutomat, customergroupAutomat, numberAutomat]
+    transport: src/api (http(), named namespaces)
     egress:
       protocol: HTTP (fetch with credentials: "include") & SSE (/api/events)
       proxy: Vite dev server (/api -> http://localhost:4208)
@@ -99,10 +99,7 @@ flow:
 ```
 src/
 ├── api/                     # Backend communication layer
-│   ├── index.js             # Canonical API module exports (article, category, delivery, etc.)
-│   ├── ApiClient.js         # Object-oriented API client (this.article, this.delivery, etc.)
-│   ├── StorageManager.js    # Client-side cache / local storage management
-│   └── storageManagerContext.js # React context provider for StorageManager
+│   └── index.js             # Canonical API module (article, category, delivery, entity, …)
 ├── automats/                # react-automat state modules (fine-grained subscriptions)
 │   ├── artikelAutomat.js    # Article cache, deduplicated loads, and reactive single-article state
 │   ├── authAutomat.js       # Authentication state, session bootstrap, company selection
@@ -191,9 +188,15 @@ In `dashfront`, two state management solutions coexist harmoniously:
 
 ### B. Configuration Automats (`src/automats/`)
 - Company, hierarchical `category` tree, `brand`, `posterminal`, and `unit` state live in dedicated automats (`companyAutomat`, `categoryAutomat`, `brandAutomat`, `unitAutomat`, `posterminalAutomat`).
+- Company-scoped **lists** (article index, deliveries, quotes, orders, entities, customer groups, number sequences) live in list automats built by `createListAutomat`.
 - Reads use the same fine-grained `subscribe`/selector pattern as the domain automats.
 - Cross-automat coordination is done by subscribing to `authAutomat`: when it reaches `authed` with a `selectedCompanyId`, these automats load themselves and reset on `anon` (see [§10](#10-deep-dive-configuration-automats-company-category-brand-unit--pos-terminals)).
 
+### C. No React Context for Data (`src/api` has no context layer)
+- There is **no** store/context provider in this app. Components import the automat or `src/api` namespace they need directly. There is deliberately no `static contextType` for data access.
+- Call the API through the namespace functions (`article.getBySku(...)`, `delivery.list()`), and keep shared/cached state in an automat.
+- Barrel exports live in [src/automats/index.js](file:///home/seb/src/dashfront/src/automats/index.js); `src/main.jsx` imports it for its side effects so every store is registered before the session bootstraps.
+
 ---
 
 ## 5. Backend Communication & Authentication Rules
@@ -320,6 +323,33 @@ All domain Automats are located in [src/automats/](file:///home/seb/src/dashfron
 ### 6. `userSettingsAutomat` ([src/automats/userSettingsAutomat.js](file:///home/seb/src/dashfront/src/automats/userSettingsAutomat.js))
 - **Role**: Stores client-side user layout preferences such as viewer panel coordinates and drawer positions.
 
+### 7. `sseAutomat` ([src/automats/sseAutomat.js](file:///home/seb/src/dashfront/src/automats/sseAutomat.js))
+- **Role**: Owns the **single** `EventSource` for `/api/events` and fans signals out into the domain automats. Reconnects whenever the selected company changes; disconnects on logout.
+- **Built-in handlers**: `category` → `categoryAutomat.loadTree()` + `invalidateAllCategoryViews()`; `articles` → `articleIndexAutomat.reload()` + category-view invalidation; `warehouse` → `warehouseAutomat.reload()`; `attributename` / `propertyname` → `attributeAutomat.load()` / `propertyAutomat.load()`; `supplier` → `supplierAutomat.reload()`.
+- **Extension API**:
+  - `sseAutomat.actions.on(event, handler)` — register a handler for a named backend event. Returns an unsubscribe callback. Handlers registered while disconnected attach on the next connect.
+  - `sseAutomat.actions.watchArticle(sku, handler)` — subscribe to `article-<sku>` for one SKU. Exactly one listener is bound per SKU while at least one caller is subscribed; the listener resolves its handler set at call time, so an unwatched SKU is a no-op.
+  - `invalidateArticle(sku)` — reloads the article plus its keyed history/supplier views. Background refreshes stay silent.
+
+### 8. Company-Scoped List Automats
+Built with the shared [src/automats/createListAutomat.js](file:///home/seb/src/dashfront/src/automats/createListAutomat.js) factory, which follows the brand/unit/warehouse pattern (`status: idle | loading | ready | failed`):
+
+| Automat | Backs |
+|---|---|
+| `articleIndexAutomat` | Article search index (`GET /api/articleIndex`), mapped to the recordset shape; also patched optimistically on rename |
+| `deliveryAutomat` | Delivery list |
+| `quoteAutomat` / `orderAutomat` | Quote / order lists |
+| `entityAutomat` / `customergroupAutomat` | Customer list and customer groups |
+| `numberAutomat` | Document number sequences |
+
+Each exposes `load()` (deduplicated), `reload()` (silent), `replace()`, `ensureLoaded()`, and `reset()`. They subscribe to `authAutomat`, so they load on `authed` with a `selectedCompanyId` and reset to `idle` on `anon`.
+
+### 9. `articleSearchAutomat` ([src/automats/articleSearchAutomat.js](file:///home/seb/src/dashfront/src/automats/articleSearchAutomat.js))
+- **Role**: Client-side search over the cached article index for the `/artikel` overview. `search(target)` returns `{ categoryFacets, totalCount, recordset, error }`; the page subscribes to `result` instead of receiving a callback.
+
+### 10. `articleDetailAutomat` ([src/automats/articleDetailAutomat.js](file:///home/seb/src/dashfront/src/automats/articleDetailAutomat.js))
+- **Role**: Two `KeyedAutomat` stores keyed by SKU — `articleHistoryAutomat` (`GET /api/article/{sku}/history`, paginated client-side) and `articleSupplierAutomat` (`GET /api/article/{sku}/supplier`). Both reload automatically when `sseAutomat` reports an `article-<sku>` signal.
+
 ---
 
 ## 10. Deep Dive: Configuration Automats (Company, Category, Brand, Unit & POS Terminals)