Item Filter & Sort — Visual Architecture

Companion to architecture.md, implementation-notes.md and summary.md.

Diagrams use PlantUML per documentation site conventions.

---

1. Architecture — component diagram

---

2. SSRM lifecycle — sequence diagram

---

3. Cache layers

[SPA] Redux slice (localStorage)
  - filterQuery: { tokens, operation }
  - sortModel: [{ colId, sort }]
  - Survives reload. Sent with every SSRM request.

[BFF] unstable_cache — raw tier
  - Key: ['items-all', tenantId]
  - Tag: 'items-all:' + tenantId   (tenant-scoped — busting
                                     'items-all' globally would
                                     invalidate every tenant's
                                     cache and grind the system
                                     to a halt)
  - TTL: 5 minutes (CACHE_TTL_SECONDS = 300)
  - Content: StrippedArdaResult[] (drops 'previous',
    'createdBy', 'createdAt' + 'secondarySupply'
    payload field — fits under the 2MB
    unstable_cache per-entry limit)

[BFF] unstable_cache — mapped tier
  - Key: ['items-all-mapped', tenantId]
  - Tag: 'items-all:' + tenantId (same tenant tag — one
                                   revalidateTag busts both tiers
                                   for that tenant only)
  - TTL: 5 minutes
  - Content: Item[] (mapped once per cache fill, not per SSRM request)
  - Cap:    HARD_MAX_ITEMS per tenant (BFF memory bound)

---

4. Filter model shape

PropertyFilterQuery (persisted in Redux + localStorage):

  {
    tokens: [
      { propertyKey: 'classificationType', operator: '=',  value: 'Office' },
      { propertyKey: 'supplier',           operator: ':',  value: 'Acme' },
      {                                    operator: ':',  value: 'bolt' }
    ],
    operation: 'and'
  }

Sent with every SSRM request as filterTokens + filterOperation.
Free-text tokens (no propertyKey) match against ALL 26 filterable fields.

---

5. File map

NEW files:
  [BFF] src/app/api/arda/items/query-ssrm/route.ts     — SSRM endpoint
  [BFF] src/app/api/arda/items/_lib/cachedItems.ts      — cache + pagination loop
  [BFF] src/app/api/arda/items/_lib/filterEngine.ts     — token matching
  [BFF] src/app/api/arda/items/_lib/sortEngine.ts       — multi-column sort
  [SPA] src/app/items/ItemsPropertyFilter.tsx            — filter toolbar UI
  [SPA/BFF] src/app/items/filteringProperties.ts         — 26 field defs + ITEM_FIELD_ACCESSORS_TYPED
  [SPA] src/store/slices/itemsFilterSortSlice.ts         — Redux persistence
  [BFF] src/lib/mappers/itemsGridMapper.ts               — stripToGridColumns
  [BFF] src/app/actions/revalidateItems.ts               — cache bust server action

MODIFIED files:
  [SPA] src/app/items/page.tsx                           — SSRM metadata, PropertyFilter
  [SPA] src/app/items/ItemTableAGGrid.tsx                — SSRM datasource
  [SPA] src/components/table/ArdaGrid.tsx                — SSRM mode, refreshGrid
  [SPA] src/lib/ardaClient.ts                            — queryItemsSSRM()
  [SPA] src/store/rootReducer.ts                         — register slice