Settings

The settings surface is the principal-admin’s tenant configuration page. It renders at /demo/principal/settings and groups three editable areas behind editorial tabs: Oversight calendar, Rubric editor, Connectors and enrichments. Every change is versioned: historic file reviews stay scored against the rubric in force at the time, and earlier task cycles are not retroactively re-cadenced.

Live: lending-agent-oversight.vercel.app/demo/principal/settings.

Why a settings surface

The supervision programme of a principal firm is bespoke within a regulatory framework. Two firms in the same vertical can run materially different programmes — different file-review cadences, different MI fields, different rubric items added on top of the canonical set, different connectors wired up. The platform ships with sensible defaults and exposes the levers needed to adapt to the firm’s policy without losing audit fidelity.

Section label: Settings · principal-admin.
Title in Fraunces: Tenant configuration.
Subtitle: “Customise the rubric, oversight calendar, and data connectors for [Skin shortname]. Every change is versioned. Historic file reviews stay scored against the rubric in force at the time, and earlier task cycles are not retroactively altered.”

The Tabs use variant="line" — a magazine-style horizontal column-rule rather than the default rounded-pill background. Active tab carries an underline-rail rather than a fill, signalling that the tab strip is structural rather than chromatic.

Tab 1 — Oversight calendar

Shows every supervisory task the principal firm is expected to run, grouped by category. See the Oversight tasks reference for the full canonical catalogue.

Per-task row

Each row carries:

Title and description in the row body.
Source badge — the regulatory anchor in mono small-caps (e.g. PS22/11, SUP 12.6A, DISP 1).
Applies-to badge — AR only, IAR only, or omitted for all.
Firm-level badge where the task is firm-level rather than per-AR.
Customised badge (amber-soft) when the principal-admin has overridden the default frequency or disabled the task.
Owner role in the row footer.
Frequency dropdown — single-select on the right with six options: Weekly, Monthly, Quarterly, Half-yearly, Annual, Ad-hoc. Disabled when the task itself is disabled.
On checkbox — toggles enabled for the task.

Header bar

N customised counter or Default configuration if untouched.
Reset to defaults button — disabled until at least one task is customised.

Categories rendered

Tasks group into Cards by category, in this order: Review, Data collection, Attestation, Filing.

In production, every frequency change writes a TaskFrequencyChange audit event with old and new values, attribution, and timestamp. Past cycles are not retroactively re-cadenced; the next cycle uses the new frequency. The annual self-assessment exports the full task register including the in-force frequency at each cycle and any changes made during the period.

Tab 2 — Rubric editor

A nested Tabs surface (also variant="line") splits the editor into two:

[Rubric code] (AR) — the principal’s vertical rubric (MCOB, ICOBS, or CONC depending on the active skin) for full AR appointments.
IAR — the vertical-agnostic IAR rubric (introduction quality, status disclosure, scope adherence, hand-off).

Per-rubric view

Each view renders a Card grouped by section. Inside each section:

Canonical rows — each canonical rubric item rendered as a row with a checkbox (toggling marks the item inapplicable for this tenant, dimming the row at 50% opacity), the code in mono, the plain-language label, and an outline Canonical badge.
Custom rows — items added by the principal-admin. Same row shape but with an amber-soft Custom badge and an × button to remove.

Add custom item form

Below the rubric, an Add custom item Card with:

Code input (mono, free text — production: principal can pick a tenant-prefixed code or a tenant-specific reference to an internal policy).
Label input — plain-language descriptor.
Section select — defaults to existing sections, Internal always available as a fallback.
Add to rubric button — disabled until code and label are filled.

A footnote reminds the reader that custom items append to the rubric for the chosen code, reviewers see them grouped under their section, and a RubricChange audit event is captured with each addition. The demo persists across sessions via Zustand persist; production keeps the full version history.

Versioning model

Each rubric edit increments the rubric version. A FileReview references the rubric version it was scored against, so a change to the rubric does not retroactively alter prior reviews. The annual review packet shows the rubric version at the time of each review.

Tab 3 — Connectors and enrichments

Two sections: MI ingestion and Enrichment. Each renders a 2-column grid of connector Cards.

Connector card

Carries:

Icon container — emerald 10% / 600 colour for connected, destructive for error, muted for not-configured.
Label and kind — connector name and kind in mono (CRM webhook, Companies House, etc.).
Status badge — Connected (with a ping-pulsing emerald dot), Syncing (amber with spinning refresh icon), Error (destructive), or Not configured (outline).
Description — what the connector does.
Stats grid — Cadence (Every 4 hours, On event, Daily, Weekly, Nightly, or Manual), Last sync (relative time), AR coverage (% of network for MI, raw count for enrichment), Fields enriched (count, enrichment connectors only).
Auto-populated fields — chip cloud of the field names the connector populates (enrichment connectors only).
Action row — Disconnect / Connect toggle, Re-sync (when connected), API docs ↗ link to the provider’s developer portal (Companies House, CreditSafe, FCA Register).

Section: MI ingestion

Four connectors:

AR CRM webhook — on-event, 92% coverage. Each AR’s CRM posts case-completion events to a per-tenant signed webhook. Idempotent on the CRM’s case ID.
Lender portal feeds — every 4 hours, 78% coverage. Daily pull from the principal’s lender-portal aggregator.
Complaints system — on-event, 100% coverage. Bidirectional sync; AR-originated complaints tagged with originatingArId.
CSV upload (fallback) — manual, 14% coverage. For ARs without an integrated source system.

Section: Enrichment

Three connectors:

Companies House — daily, 100% coverage. 8 fields auto-populated. Provider docs: https://developer.company-information.service.gov.uk/.
CreditSafe — weekly, 100% coverage. 5 fields. Provider docs: https://www.creditsafe.com/gb/en/business/api.html.
FCA Register — nightly, 100% coverage. 6 fields. Provider docs: https://register.fca.org.uk/Services/V0.1/Help/Index.

Reset

Header carries Reset connector states — disabled until at least one connector has been toggled. Resets all status overrides back to the shipped defaults.

Add connector

Below the two sections, a dashed-border Card with Browse connector catalogue (demo). Disabled in the demo; production: paste a webhook URL, paste an API key, or upload an OAuth consent.

States

Untouched. All three tabs render the canonical defaults. No customisation badges visible.
Customised. Each tab maintains an internal counter (N customised); reset buttons activate.
Persistence. All four pieces of state — task overrides, custom rubric items, inapplicable rubric codes, connector status overrides — persist across sessions via Zustand persist on localStorage. Refreshing the page preserves the customisation. The walkthrough mode reset clears them.

Components

app/demo/principal/settings/page.tsx (page shell with Tabs)
components/principal/settings-oversight-calendar.tsx
components/principal/settings-rubric-editor.tsx
components/principal/settings-connectors.tsx

State is held in lib/state.ts and seeded by:

lib/oversight-tasks.ts (canonical task catalogue)
lib/rubrics.ts (canonical rubrics)
lib/connectors.ts (connector catalogue)

How this connects to the rest of the demo

The oversight tasks reference documents the full default catalogue and the override model.
The file-review rubrics reference covers the canonical MCOB / ICOBS / CONC / IAR items.
The connectors and enrichment architecture covers the production design for each connector kind.
Customisations affect the file review workflow (rubric items applied), the annual review packet (task cycles aggregated), and the AR detail header (auto-enrichment provenance line).
All edits are eventually visible to the audit log under the RubricChange, TaskFrequencyChange, and ConnectorStatusChange audit-event types.