Data shapes

This is the single-page reference for every shape used by Oversight. The narrative discussion lives in Data model; this page is the lookup.

Primitive aliases

export type Ulid = string;          // 26-char Crockford Base32, URL-safe
export type IsoTimestamp = string;  // ISO 8601 with offset, e.g. 2026-05-08T18:00:00Z
export type Frn = string;           // FCA Firm Reference Number, 6-7 digits
export type Pence = number;         // Integer GBP minor units

Enums

Name	Values
Vertical	"mortgage", "general-insurance", "credit-broking"
RubricCode	"MCOB", "ICOBS", "CONC"
ArType	"AR" (Appointed Representative), "IAR" (Introducer AR)
RiskBand	"low", "moderate", "elevated", "high", "critical"
Persona	"principal-admin", "principal-compliance-officer", "ar-user"
Role	Persona values plus "fca-auditor"
ArStatus	"active", "suspended", "under-investigation", "terminated"
BreachCategory	"conduct", "financial-crime", "data-protection", "complaints-handling", "advice-suitability", "disclosure", "training-competence", "other"
BreachSeverity	"minor", "moderate", "material", "significant"
BreachCustomerImpact	"none", "potential", "actual-low", "actual-high"
BreachStatus	"open", "in-remediation", "resolved", "closed"
FileReviewStatus	"scheduled", "in-progress", "complete", "challenged"
MIReturnStatus	"draft", "submitted", "queried", "accepted"
AnnualReviewStatus	"draft", "in-review", "signed-off", "rejected"
ConductEventType	"complaint", "training-completion", "supervision-1to1", "policy-attestation", "other"

PostalAddress

Field	Type	Semantics
line1	string	Street address, required
line2	string | null	Optional
city	string	Required
postcode	string	UK postcode, validated server-side
country	"GB"	Literal, UK-only at v1

AppointedRep

Field	Type	Semantics
id	Ulid	Primary key
type	ArType	AR or IAR
tradingName	string	Customer-facing name
legalName	string	Companies House name
frn	Frn | null	Null for IARs (share principal’s FRN)
status	ArStatus	Lifecycle state
permissions	Permission[]	Granted regulatory permissions
city	string	Demo only; production uses registeredOffice: PostalAddress
appointedOn	IsoTimestamp	Date the AR contract started
lastAnnualReviewAt	IsoTimestamp | null	Drives timeSinceLastReview risk input
nextReviewDueAt	IsoTimestamp	Cadence policy + last review
riskScore	number	Composite 0-100
riskBand	RiskBand	Derived from riskScore
isSelfEmployed	boolean	PS22/11 enhanced-supervision flag
supportsImportantBusinessService	boolean	SYSC 15A flag
contact	{ name: string; email: string }	Primary contact at the AR

Permission

Field	Type	Semantics
code	string	e.g. "MCOB.ARRANGE", "CONC.CREDIT_BROKING"
label	string	Plain-language label for the UI
grantedOn	IsoTimestamp	When granted
revokedOn	IsoTimestamp | null	Null while active

BreachReport

Field	Type	Semantics
id	Ulid	Primary key
arId	Ulid	Subject AR
title	string	Short headline, 4-200 chars
description	string	Facts, 20-10000 chars
category	BreachCategory	Taxonomy
severity	BreachSeverity	Self-assessed at filing, may be revised on triage
customerImpact	BreachCustomerImpact	Drives notify-FCA routing and risk weighting
awareAt	IsoTimestamp	Drives the SUP 15 clock
reportedAt	IsoTimestamp	When filed in Oversight
notifiedFcaAt	IsoTimestamp | null	Null until step-up notification recorded
notifyByAt	IsoTimestamp | null	Computed deadline by SUP 15.3 timing
rootCauseTaxonomy	string[]	Up to 8 tags
status	BreachStatus	Lifecycle
filedByPersona	Persona	Demo only; production uses filedBy: Ulid

FileReview

Field	Type	Semantics
id	Ulid	Primary key
arId	Ulid	Subject AR
caseRef	string	The AR’s internal case reference being reviewed
reviewerName	string	Demo only; production uses reviewerId: Ulid
rubricCode	RubricCode	Determines the rubric for this review
findings	FileReviewFinding[]	Per-rubric-item outcome
score	number	0-100 derived from findings
status	FileReviewStatus	Lifecycle
startedAt	IsoTimestamp | null	Set on first edit
completedAt	IsoTimestamp | null	Set on complete transition
rootCauseTaxonomy	string[]	Up to 8 tags
notes	string	Free-text reviewer notes

FileReviewFinding

Field	Type	Semantics
itemCode	string	Rubric item code, e.g. "MCOB 4.7A.2"
itemLabel	string	Plain-language descriptor (denormalised for audit immutability)
outcome	"pass" | "advisory" | "fail" | "n/a"	Scored outcome
evidence	string	Reviewer’s evidence note
remediation	string | null	Required remediation if fail

MIReturn

Field	Type	Semantics
id	Ulid	Primary key
arId	Ulid	Subject AR
period	{ year: number; quarter: 1 | 2 | 3 | 4 }	Reporting period
submittedAt	IsoTimestamp | null	Null while draft
status	MIReturnStatus	Lifecycle
metrics	MIReturnMetrics	Reported figures
anomalyScore	number	0-1, computed against AR’s own historic distribution

MIReturnMetrics

Field	Type	Semantics
newBusinessVolumeGBP	Pence	Total volume in the period, integer pence
newBusinessCount	number	Count of new business cases
complaintsReceived	number	All complaints received
complaintsUpheld	number	Subset upheld; must be <= complaintsReceived
breachesSelfReported	number	Breaches the AR self-reported in the period
conductEventsLogged	number	Conduct events captured
cancellations	number	New-business cancellations in the period

AnnualReview

Field	Type	Semantics
id	Ulid	Primary key
arId	Ulid	Subject AR
cycleYear	number	Calendar year of the review
status	AnnualReviewStatus	Lifecycle
riskTrajectory	{ at: IsoTimestamp; score: number }[]	Snapshot of the AR’s score history
breachSummaryRefs	Ulid[]	Breaches in scope
fileReviewSummaryRefs	Ulid[]	File reviews in scope
miReturnRefs	Ulid[]	MI returns in scope
signOffByName	string | null	Demo only; production uses signOffByUserId: Ulid
signOffAt	IsoTimestamp | null	Set on sign-off
signOffNotes	string	Free-text reviewer notes

ConductEvent

Field	Type	Semantics
id	Ulid	Primary key
arId	Ulid	Subject AR
type	ConductEventType	Taxonomy
occurredAt	IsoTimestamp	When the event happened
detail	string	Free-text

RequiredAction

Field	Type	Semantics
id	Ulid	Primary key (transient in production, derived per request)
arId	Ulid	Owning AR
title	string	Display label
dueAt	IsoTimestamp	Due date
href	string	Surface to land on

AuditEvent (demo)

Field	Type	Semantics
id	Ulid	Primary key
at	IsoTimestamp	When the action happened
actorName	string	Demo only; production uses actorUserId: Ulid | null
actorRole	Role	Acting role
action	string	Action name, e.g. "breach.notify-fca"
subjectType	"ar" | "breach" | "review" | "annual-review" | "mi-return" | "tenant" | "user"	Subject taxonomy
subjectId	Ulid	Subject row

AuditEvent (production)

Adds tenantId: Ulid, actorUserId: Ulid \| null (replaces actorName), ip: string \| null, userAgent: string \| null, prevHash: string (SHA-256 of prior event’s hash), hash: string (SHA-256 of canonicalised JSON of this row including prevHash).

Tenant (production-only)

Field	Type	Semantics
id	Ulid	Primary key
legalName	string	Companies House name
tradingName	string	Customer-facing name
frn	Frn	Principal firm’s FRN
vertical	Vertical	Determines default rubric
rubric	RubricCode	Active rubric for file reviews
brandHex	string	Brand colour hex
registeredOffice	PostalAddress	Required
onboardedAt	IsoTimestamp	When the tenant signed up

User (production-only)

Field	Type	Semantics
id	Ulid	Primary key
tenantId	Ulid	Tenant scope
email	string	Sign-in identity, unique within tenant
displayName	string	UI-rendered name
role	Role	RBAC role
arId	Ulid | null	Set when role === "ar-user", null otherwise
status	"invited" | "active" | "suspended" | "off-boarded"	Lifecycle
lastLoginAt	IsoTimestamp | null	For audit and session reporting

Attachment (production-only)

Field	Type	Semantics
id	Ulid	Primary key
filename	string	Original filename
mimeType	string	Detected at upload
bytes	number	Size after virus scan
storageKey	string	Object-store key, prefixed tenant/<tenantId>/...

Zod schemas

For the canonical Zod definitions, see Data model: Zod schemas. Every write route in API routes cites the schema it parses against.