u

src/automats/index.js

@@ -1,3 +1,9 @@
+/**
+ * @file index.js
+ * @description Central barrel exporting all domain, configuration, and list
+ * automats, along with their action creators and reactive selectors.
+ */
+
 export * from './deliveryEditorAutomat';
 
 export { default as authAutomat } from './authAutomat';
@@ -84,6 +90,7 @@ export {
   categoryDisplayName,
   categorySlug,
   normalizeCategoryMap,
+  categoryViews,
   getOrCreateCategoryAutomat,
   disposeAllCategoryViewAutomats,
   invalidateAllCategoryViews,
@@ -106,4 +113,81 @@ export {
   selectHasPendingAsk,
 } from './chatAutomat';
 
+/**
+ * ============================================================================
+ * Overview of Automats in Dashfront
+ * ============================================================================
+ *
+ * Automats are lightweight, reactive, out-of-tree state containers powered by
+ * `react-automat`. They manage all client-side state without React context,
+ * hooks, or HOCs, enabling pure, zero-flash rendering in `React.PureComponent`
+ * via constructor reads and fine-grained subscriptions.
+ *
+ * 1. Multi-Tenant Session & Security
+ * ----------------------------------------------------------------------------
+ * - `authAutomat`: Tracks authenticated session (`user`, `googleClientId`,
+ *   `selectedCompanyId`, and auth status `'loading' | 'anon' | 'authed'`).
+ *   Coordinates session bootstrap, company switching, and acts as the root
+ *   lifecycle trigger that loads or resets all company-scoped automats.
+ *
+ * 2. Real-Time SSE Hub
+ * ----------------------------------------------------------------------------
+ * - `sseAutomat`: Manages the single persistent Server-Sent Events connection
+ *   (`GET /api/events`). Automatically reconnects when the active company changes
+ *   and terminates on logout. Dispatches incoming server mutation signals into
+ *   targeted automats (`artikelAutomat`, `articleDetailAutomat`, `categoryAutomat`,
+ *   `articleIndexAutomat`, `warehouseAutomat`, `supplierAutomat`, `attributeAutomat`,
+ *   `propertyAutomat`).
+ *
+ * 3. Domain & Entity Caches
+ * ----------------------------------------------------------------------------
+ * - `artikelAutomat`: In-memory cache for full article records (`GET /api/article/:sku`)
+ *   with inflight request deduplication, optimistic renames, and reactive selectors.
+ * - `articleDetailAutomat`: Keyed automats (`articleHistoryAutomat`, `articleSupplierAutomat`)
+ *   providing per-SKU supplier catalog bindings and change history.
+ * - `deliveryEditorAutomat`: Interactive draft state machine for incoming goods receipts
+ *   and invoice reconciliation (line items, supplier article auto-matching, PDF/receipt OCR).
+ *
+ * 4. Company Configuration & Catalogs
+ * ----------------------------------------------------------------------------
+ * - `companyAutomat`: Active company settings (tax rates, ISO language, root category ID).
+ * - `categoryAutomat`: Hierarchical category tree (ID -> node map), mutations (create,
+ *   rename, move, reorder, delete), and breadcrumb resolution.
+ * - `categoryViewAutomat`: Keyed view container (`categoryViews`) holding articles and child
+ *   categories per slug path, auto-preloaded when category tree finishes loading.
+ * - `brandAutomat`: Catalog manufacturer and brand records.
+ * - `unitAutomat`: Allowed units of measure (Stück, kg, Liter, etc.).
+ * - `posterminalAutomat`: Point-of-sale hardware terminals and enabled category filters.
+ * - `attributeAutomat`: Product attribute definitions and discrete values (e.g. Size, Color).
+ * - `propertyAutomat`: Custom product property and metadata names.
+ * - `supplierAutomat`: Directory of vendor entities and supplier article mappings.
+ * - `warehouseAutomat`: Warehouse locations and stock storage areas.
+ *
+ * 5. Company-Scoped List Automats (`createListAutomat`)
+ * ----------------------------------------------------------------------------
+ * Built with the shared list factory with deduplicated `load()`, silent `reload()`,
+ * and automatic synchronization with `authAutomat`:
+ * - `articleIndexAutomat`: Fast client-side search index (`GET /api/articleIndex`).
+ * - `deliveryAutomat`: Delivery receipt list (`GET /api/delivery`).
+ * - `quoteAutomat`: Sales quotes / Angebote (`GET /api/quote`).
+ * - `orderAutomat`: Sales orders / Bestellungen (`GET /api/order`).
+ * - `entityAutomat`: Customers and business partners (`GET /api/entity`).
+ * - `customergroupAutomat`: Customer discount groups (`GET /api/customergroup`).
+ * - `numberAutomat`: Document numbering sequences (`GET /api/number`).
+ *
+ * 6. Search & Infinite-Scroll Grid Automats
+ * ----------------------------------------------------------------------------
+ * - `articleSearchAutomat`: Client-side search engine querying `articleIndexAutomat`.
+ * - `articleHistoryGridAutomat`: Virtualized infinite-scroll grid for article history.
+ * - `globalHistoryGridAutomat`: Virtualized infinite-scroll grid for global audit logs.
+ *
+ * 7. UI State & Utilities
+ * ----------------------------------------------------------------------------
+ * - `chatAutomat`: AI assistant chat drawer state, conversations, and live SSE streaming tokens.
+ * - `navigationAutomat`: Persists last visited delivery document path and article SKU.
+ * - `userSettingsAutomat`: User layout preferences (viewer position, drawer widths in IndexedDB).
+ * - `helpAutomat`: Interactive help badge states and popper positioning (in IndexedDB).
+ * ============================================================================
+ */
+