Lookups Master Data — config-driven use case

Add a Lookups master-data screen under Platform Settings, built entirely on the existing config-driven runtime (CrudConfigWrapper):

• a Lookup Code dropdown above a grid of that lookup’s entries (Key, Value);
• Add Entry (header button) adds a Key / Value to any USER lookup;
• Edit (Value only) and Delete an entry from the row menu, for USER lookups only;
• SYSTEM lookups are view-only.

No new React components: every gap is closed by extending the runtime’s config vocabulary (types, schema validator, request/response utils, mutation hooks), so any future config can use the same keys.

Out of scope:

• creating a new lookup table (POST /lms/api/v1/lookups) — deferred by the owner (Decided #7);
• deleting a lookup table, renaming a lookupCode, changing a locale (no API);
• backend changes (the contract is followed as given, Decided #6);
• app-owned crud configs (registerCrudConfigModules, still pending in docs/plan/archived/app-owned-crud-configs/);
• the Lease Closure Tracker Playwright work (its #7 resumes after this plan).

Background docs: requirements, config-driven design.

1 — What we know (current state)

Purpose

Lookups are the tenant’s key/value lists behind the app’s dropdowns and labels (lease types, payment frequencies, GL account tags, closure-checklist categories, …). The app can only read them today. Admins need to add, reword and remove entries in the lists they own (USER), without touching the lists the code depends on (SYSTEM).

Backend contract (Decided #1, #2, #6)

• The PUT replaces the whole lookupData list. The contract’s samples show it: the GET and PUT samples share id a1b2c3d4-…, and entries missing from the PUT body are missing from its response.
• A lookup table is { id, lookupCode, lookupData[], listType: SYSTEM | USER, appLocale, tenantName, createdAt, updatedAt, createdBy, updatedBy }.
• SYSTEM lookups cannot be modified; only USER lookups can (Decided #8).

Runtime architecture today (the parts this plan uses)

platformSettings.json leaf ──► CrudConfigWrapper(<slug>_config.json, hydrated + schema-validated)
  ├─ CrudConfigFilterBar ── list.filters[] (dropdown, options.api, default_first)   ✅ reused
  │     └─ fetchCrudConfigFilterOptions ── ApiService.get(url)                      ❌ no headers
  ├─ useCrudConfigListQuery ── createGetQueryHook (one shared hook for all configs)
  │     ├─ URL {token} ← filter values (constructURL binds :lookupCode)             ✅ reused
  │     ├─ static `headers` per hook factory                                        ❌ not per config
  │     └─ transformCrudConfigListResponse ── rows_path / rename / flatten / defaults
  │                                            rows lose the parent record          ❌
  ├─ buildCrudConfigListRows ── row_level_actions[].conditions (equals)             ✅ reused
  ├─ CrudConfigToolbar ── one `add` button                                          ✅ reused
  └─ CrudConfigListDialogs
        ├─ AddCrudConfigItem   ─► useCrudConfigAddMutation    (always POST, form values + filters)
        ├─ EditCrudConfigItem  ─► useCrudConfigEditMutation   (always PUT,  form values + row)
        └─ DeleteConfirm       ─► useCrudConfigDeleteMutation (always DELETE, row values)
              all three ─► createCrudConfigDynamicMutationHook ─► runCrudConfigDynamicMutation
                            sends ONE row's values; never the rest of the list   ❌

• Dropdown fields (FieldApi) already support headers and response_transformation.rename; the label falls back to the value (transformCrudConfigFieldOptionsResponse).
• The schema validator rejects unknown keys (SUPPORTED_RESPONSE_TRANSFORMATION_KEYS, SUPPORTED_PAYLOAD_TRANSFORMATION_KEYS, …), so every new key must be registered there.
• Configs live in packages/bsq-platform/src/config-driven/data/, are auto-discovered, and are tied to a nav leaf through meta.child_slug (Counter Parties is the closest precedent: finlease /lms URLs, mdm_counter_parties screen key, __passthrough__ action keys).
• Config literals are localized by npm run sync-config-driven-i18n into packages/bsq-shared/src/i18n/locales/*.json (admin.configDriven.<slug>.*).
• Finlease’s own lookups cache (useGetLookupsQuery, plain useQuery) uses the default staleTime of 0 from new QueryClient() in main.tsx, so it refetches whenever a lookup consumer mounts.

Mocks today

• apps/finlease/__mocks__/handlers/lookupsHandlers.ts has one handler, GET /lms/api/v1/lookups, returning buildMockLookups(entities) — rebuilt from constants on every request, so nothing can be changed.
• Every seeded table is SYSTEM except GL_ACCOUNT_TAGS (USER). CLOSURE_CHECKLIST is SYSTEM in the mocks but USER in the backend’s sample.
• SEEDED_CLOSURE_CHECKLIST_LOOKUP is also consumed by the closure-checklist mocks and the Lease Closure Tracker specs.

Key files (for implementers)

2 — What we are changing

Product ask

Runtime extensions (generic config vocabulary)

Save rule (G2, read → merge → write)

Every write sends { lookupData: [...] } with only key and value on each item, to PUT /lms/api/v1/lookups/{id}/modification where {id} comes from the read.

Mandates

1. Mocks first. The lookups MSW store, by-code GET and PUT handlers land before any config, so dev and Playwright exercise the contract from Phase #1 on.
2. Reuse the config-driven components; add no new ones. CrudConfigWrapper, CrudConfigFilterBar, the toolbar, AddCrudConfigItem, EditCrudConfigItem, the delete confirm and the row-actions menu are used as they are. Gaps are closed in types, the schema validator, utils and the existing query/mutation hooks only.
3. Generic, not lookups-specific. No lookup identifiers in bsq-platform runtime code. Every new key is named and specified so another config could use it.
4. Schema in the same phase. Every new config key is added to crudConfig.types.ts and validated in crudConfigSchema.utils.ts in the phase that introduces it.
5. Opt-in only. Configs that don’t use a new key behave exactly as today: same verbs, same payloads, same headers. In particular, Add/Edit/Delete keep their hard-coded POST/PUT/DELETE unless read_merge is present.
6. Contract as given. /lms URLs, bare responses, the PUT replaces the list, exact Accept-Language: en (Decided #1, #2, #4, #6).
7. SYSTEM is view-only in the UI (Decided #8), and the mock rejects SYSTEM modifications like the backend does.
8. Access: screen key mdm_lookups; every action key __passthrough__ (Decided #5).
9. Tests:
   • no specs for MSW handlers or fixtures;
   • no *.queries.spec — mutation and query behaviour is tested through the consuming component specs;
   • no config-only spec files (asserting JSON through resolver utils).
10. No new inline comments. One-line JSDoc on new exported symbols only.

Per-phase delivery gate

Each phase must pass before the next starts:

1. Implement. Apply only that phase’s diff.

2. Test. Every source file whose behaviour changes gets its colocated spec updated in the same phase. Run only the affected specs:

   • packages/bsq-platform: npx jest --config jest.config.cjs <spec paths>;
   • apps/finlease: npm test -- <spec paths>.

   Never run a whole suite.

3. Lint. npx eslint <changed files> --config ../../eslint/lint-ci.config.js --quiet, and npx prettier --check --ignore-path ../../.prettierignore <files>.

4. Type-check. npm run type-check in every touched package (packages/bsq-platform, apps/finlease).

5. Duplication. npm run jscpd and npm run jsinspect when a phase adds helpers.

6. i18n. npm run check-i18n-keys, plus npm run sync-config-driven-i18n:check once a config exists.

Target architecture

Platform Settings › Account Settings › Lookups      (platformSettings.json leaf, meta.child_slug "lookups")
  └─ CrudConfigWrapper(lookups_config.json)          access: list "mdm_lookups", everything else "__passthrough__"
       ├─ filter lookupCode ── GET /lms/api/v1/lookups  [G1 headers]  label/value = lookupCode, default_first
       ├─ list ── GET /lms/api/v1/lookups/code/{lookupCode}  [G1 headers]
       │     rows_path "lookupData" + parent_fields ["lookupCode","listType"]  [G3]
       │     → rows { key, value, lookupCode, listType }
       ├─ row ⋯ Edit / Delete ── conditions listType equals USER             (existing row conditions)
       ├─ toolbar Add Entry ── AddCrudConfigItem
       │     fields: lookupCode (dropdown: GET /lookups, headers, row_conditions listType=USER [G3]), key, value
       └─ add / edit.write / delete api = PUT /lms/api/v1/lookups/{id}/modification + read_merge  [G2]
             read  GET /lms/api/v1/lookups/code/{lookupCode}   ({lookupCode} ← form values / row)
             merge append | replace | remove on lookupData, keyed by "key", items keep {key, value}
             write PUT … {id} ← read response; body { lookupData: [...] }
             success → existing list invalidation; finlease lookup consumers refetch on mount

Dropped (do not implement)

Phases

#0 — Contract and decisions (P0, no code) — Done

Recorded under Decided #1–#10. One question remains open (limits); it doesn’t block #1–#5.

#1 — Lookups mocks: mutable store, by-code GET, PUT (P0)

Files:

• apps/finlease/__mocks__/mocks/lms/lookupsData.ts, __mocks__/mocks/lms/persist.ts
• apps/finlease/__mocks__/handlers/lookupsHandlers.ts

Changes:

• Store: one in-memory list of lookup tables, seeded from today’s constants and persisted to localStorage through persist.ts (new storage key), like the closure-checklist mocks. ENTITY_NAME stays derived from the entities mock on every read (SYSTEM, never stored).
• CLOSURE_CHECKLIST becomes USER, matching the backend sample, so the Lease Closure Tracker categories can be managed. GL_ACCOUNT_TAGS stays USER; everything else stays SYSTEM.
• GET /lms/api/v1/lookups: reads the store (bare array, unchanged shape).
• GET /lms/api/v1/lookups/code/:lookupCode: bare table; 404 for an unknown code.
• PUT /lms/api/v1/lookups/:id/modification: replaces lookupData, bumps updatedAt / updatedBy, returns the bare table; 404 for an unknown id; 400 with a message for a SYSTEM table (status to confirm, open question 2).
• Field names stay camelCase (the real contract).

Acceptance:

• ChecklistTab.spec, ChecklistItemDialog.spec and the closure-checklist mocks still pass unchanged (they import SEEDED_CLOSURE_CHECKLIST_LOOKUP, whose entries don’t change).
• Dev server: a PUT through the browser console changes what the Lease Closure Tracker’s Category dropdown shows on the next visit.
• No handler specs (Mandate 9).

#2 — G1: headers on operation APIs (P0)

Files:

• crudConfig.types.ts — OperationApi.headers?: Record<string, string>.
• crudConfigSchema.utils.ts — validate operation-API headers with the existing validateFieldApiHeaders.
• CrudConfig.queries.ts — a GET list API that declares headers reads through useCrudConfigListGetWithHeadersQuery (useQuery + fetchCrudConfigListWithHeaders); the shared createGetQueryHook list hook is unchanged. createQueryHook.ts is not touched.
• crudConfigQuery.utils.ts — fetchCrudConfigFilterOptions passes options.api.headers to ApiService.get / .post, like fetchCrudConfigFieldOptions does today.
• Specs: crudConfigQuery.utils.spec.ts, crudConfigSchema.utils.spec.ts.

Acceptance (specs):

• a function headers is called with the transformed input and its result is sent; an object headers is sent as before; no headers → no extra header;
• filter options are fetched with the configured headers (GET and POST);
• schema accepts string-valued headers on an operation API and rejects non-string values.

#3 — Read-only Lookups screen (P0)

Files:

• packages/bsq-platform/src/config-driven/data/lookups_config.json — new.
• .../config-driven/utils/mdmAccessControl.ts — LOOKUPS: 'mdm_lookups'.
• apps/finlease/src/utils/adminLandingActionIds.ts (+ spec) — lookups: MDM_ACCESS_CONTROL_KEYS.LOOKUPS.
• apps/finlease/src/config/platformSettings.json — leaf { "id": "lookups", "seq_no": "01#015#12", "name": "lookups", "menu_type": "Tab", "children": [] }.
• apps/finlease/src/config/menuJsonPatches.ts — mdm_lookups entry after mdm_counter_parties (backend menu_json doesn’t return it).
• packages/bsq-shared/src/i18n/locales/*.json — via npm run sync-config-driven-i18n.

Changes:

• Config: title, entity_id_key: "key", meta.child_slug: "lookups", fields key / value.
• operations.list:
  • api: GET /lms/api/v1/lookups/code/{lookupCode}, headers: { "Accept-Language": "en" }, response_transformation.rows_path: "lookupData";
  • filters: lookupCode dropdown, options.api GET /lms/api/v1/lookups with the same header, label_key / value_key lookupCode, default_first: true, access_control_key: "__passthrough__";
  • layout: Key, Value; pagination.enabled: false; access_control_key: "mdm_lookups".
• No toolbar, add, edit or delete yet.

Acceptance:

• adminLandingActionIds.spec covers the new slug.
• Manual: the leaf opens the screen; the first lookup is selected; switching codes reloads the grid; both GETs carry Accept-Language: en (network tab).
• No config-only spec (Mandate 9).

#4 — G3: parent_fields and row_conditions (P0)

Files:

• crudConfig.types.ts — ResponseTransformation.parent_fields?: string[], ResponseTransformation.row_conditions?: ListRowLevelActionCondition[].
• crudConfigSchema.utils.ts — add both to SUPPORTED_RESPONSE_TRANSFORMATION_KEYS; validate shapes; parent_fields entries count as declared row keys (so row-action conditions may reference them).
• crudConfigQuery.utils.ts:
  • transformCrudConfigListResponse — after rows_path, copy parent_fields from the object that holds the array (the path minus its last segment; the response root for a one-segment path) onto each row, then keep rows passing row_conditions (rowMatchesActionConditions);
  • transformCrudConfigFieldOptionsResponse — apply row_conditions to option rows before mapping to { label, value }.
• lookups_config.json — list parent_fields: ["lookupCode", "listType"].
• Specs: crudConfigQuery.utils.spec.ts, crudConfigSchema.utils.spec.ts, buildCrudConfigListRows.spec.tsx (a row action hidden by a condition on a parent field).

Acceptance (specs):

• one-segment and nested rows_path both receive the parent fields; a row’s own key wins over a parent key with the same name;
• row_conditions filter list rows and field options; absent → unchanged output;
• schema rejects a non-array parent_fields and malformed conditions.

#5 — G2: read_merge on add / edit / delete (P0)

Files:

• crudConfig.types.ts — OperationApi.read_merge?: { read: OperationApi; items_path: string; item_id_key: string; item_fields: string[]; action: 'append' | 'replace' | 'remove' }.
• crudConfigSchema.utils.ts — validate read_merge (read API, non-empty item_fields, action in the closed set) on add.api, edit.write and delete.api only.
• crudConfigPayloadTransformation.utils.ts — pure mergeCrudConfigCollectionItem(items, item, { item_id_key, item_fields, action }) returning the new list or a typed error (duplicate / not_found).
• CrudConfig.queries.ts:
  • createCrudConfigDynamicMutationHook takes the operation name;
  • when that operation’s API has read_merge, mutationFn runs runCrudConfigReadMergeMutation: interpolate read.url from { ...row, ...values, ...filters }, GET it (with read.headers), merge, interpolate the write URL from the read response, send with the configured method (resolveCrudConfigBodyMutationMethod);
  • otherwise the existing runCrudConfigDynamicMutation path is untouched (Mandate 5).
• packages/bsq-shared/src/i18n/locales/*.json — admin.crudConfig.readMerge.duplicate / .notFound messages, surfaced through the existing mutation-error path (verify crudConfigApiErrorUserMessage shows a thrown error’s message; extend it if not).
• Specs: crudConfigPayloadTransformation.utils.spec.ts (merge), crudConfigSchema.utils.spec.ts, and one read-merge case each in AddCrudConfigItem.spec.tsx, EditCrudConfigItem.spec.tsx and useCrudConfigConfirms.spec.ts (Mandate 9: query behaviour through consumers).

Acceptance (specs):

• append / replace / remove produce the right list and keep only item_fields; duplicate append and missing replace/remove return the typed error and make no write;
• Add: the read URL uses the form’s value; Edit: the row’s parent field; Delete: the row values; the write URL {id} comes from the read response; the configured method is used;
• configs without read_merge still POST/PUT/DELETE exactly as before (existing specs unchanged and green).

#6 — Add / Edit / Delete in the Lookups config (P0)

Files:

• lookups_config.json
• packages/bsq-shared/src/i18n/locales/*.json — via npm run sync-config-driven-i18n -- --force for en (new labels); hi / ms reviewed by hand per the script’s rules.

Changes:

• Field lookupCode: display.helper_text: "Only user lookups are shown"; dropdown with api GET /lms/api/v1/lookups, headers: { "Accept-Language": "en" }, response_transformation: { "rename": { "lookupCode": "value" }, "row_conditions": [{ "field": "listType", "operator": "equals", "value": "USER" }] }, required.
• Fields key / value: required; max_length placeholders 100 / 255 until open question 1 is answered.
• Toolbar: one add button, “Add Entry”, access_control_key: "__passthrough__".
• add: layout Lookup Code, Key, Value; api = PUT modification with read_merge append; access and cancel keys __passthrough__.
• edit: prefill: "row"; layout Key (disabled), Value; write = PUT modification with read_merge replace; access and cancel keys __passthrough__.
• delete: api = PUT modification with read_merge remove; confirmation title/message.
• row_level_actions: Edit and Delete, each with disabled_conditions: [{ "field": "listType", "operator": "equals", "value": "SYSTEM" }], display.disabled_tooltip (“System lookups cannot be edited” / ”… deleted”) and access_control_key: "__passthrough__".

Acceptance (manual, dev server on mocks):

• CLOSURE_CHECKLIST (USER): add an entry from the header (choosing any USER code), edit its value, delete it; each change survives a reload.
• A SYSTEM lookup shows no Edit / Delete, and SYSTEM codes are absent from the Add Entry dropdown.
• A duplicate key shows the duplicate message and makes no PUT.
• npm run sync-config-driven-i18n:check passes.

#7 — E2E + manual verify (P1)

Then the Lease Closure Tracker’s #7 (Playwright) resumes.

Sequencing

1. #1 mocks — first (Mandate 1).
2. #2 headers — independent of #1; can run in parallel.
3. #3 read-only screen — needs #1 (by-code GET) and #2 (headers).
4. #4 parent fields + row conditions — independent of #3; needed by #6.
5. #5 read-merge — needs #1 (PUT handler) for manual checks; independent of #3 / #4 in code.
6. #6 config add/edit/delete — needs #3, #4, #5.
7. #7 Playwright + manual — after #6.

Merge candidates:

• #2 and #3 ship the first visible screen and can be one commit.
• #4 is small and can go with #5.

File touch list

Do not touch:

• createQueryHook.ts (+ spec) and bsq-shared types/queryHook.ts (owner, Phase #2);
• CrudConfigWrapper, CrudConfigFilterBar, CrudConfigToolbar, AddCrudConfigItem.tsx, EditCrudConfigItem.tsx, CrudConfigListDialogs.tsx, the confirm dialog components (Mandate 2);
• runCrudConfigDynamicMutation’s existing behaviour and the hard-coded verbs for non-read_merge configs (Dropped I);
• finlease’s Lookups.queries.ts and LOOKUP_CODES (Dropped H);
• other *_config.json files.

Decided

1. URL prefix is /lms for every lookups endpoint.
2. Responses are bare objects (no { success, data } envelope).
3. Deleting an entry is allowed, after a confirmation.
4. Accept-Language: en is required exactly on the lookups GETs (G1).
5. Access: screen key mdm_lookups; every action key __passthrough__ for now, as Counter Parties does. Real ids later change config values only.
6. The backend contract is followed as given: the PUT replaces the whole lookupData list; no per-entry endpoints (Dropped F).
7. Creating a lookup table is deferred (Dropped E).
8. SYSTEM lookups are view-only; only USER lookups can be modified. On SYSTEM rows Edit / Delete stay visible but disabled, with the tooltips “System lookups cannot be edited” / “System lookups cannot be deleted” (owner, Phase #4). Add Entry offers only USER codes.
9. Add Entry is a header action for any USER lookup, with its own Lookup Code dropdown — not tied to the grid’s selection, and not a row action.
10. Writes use read → merge → write per operation (read_merge), reading the target lookup by code at save time (Dropped B, C).

Open questions

1. Limits: max lengths for key and value? The config uses 100 / 255 as placeholders. Should the key format (UPPER_SNAKE_CASE) be enforced client-side (Dropped J)?
2. Errors: the status code and message the backend returns for a SYSTEM modification, an unknown id and an unknown code (the mock assumes 400 / 404 / 404). Does the PUT reject duplicate keys in lookupData, and with what message? Until confirmed the frontend keeps its own duplicate check (owner); the not-found check stays regardless, because the backend only sees the final list.

Progress checklist

• #0 Contract and decisions
• #1 Lookups mocks
• #2 G1 — headers on operation APIs
• #3 Read-only Lookups screen
• #4 G3 — parent fields + row conditions + disabled row actions
• #5 G2 — read_merge on add / edit / delete
• #6 Add / Edit / Delete in the config
• #7 E2E + manual verify

Progress log