Data flow

This page sets out the data flows in Lending Agent Oversight: who provides what to whom, where it lands, and what happens next. Every flow named here is anchored to a record type from the data model and a route from the API surface.

Actors

Actor	Role under UK GDPR	Notes
Principal firm	Controller for AR, customer, and staff data	Decides purposes and means; signs Article 28 DPA with platform operator
Platform operator	Processor for the above; controller for billing-side data	Runs the SaaS, signs Article 28 DPAs with sub-processors
AR firm	Joint-controller candidate for AR-individual data; controller for its own customer data	The AR’s customer data does not enter the workspace as a structured field
AR-individual	Data subject for their own personal data	Submits MI returns, files breach reports, sees their own audit log
Principal-side staff	Data subject for their own personal data	Operate the workspace
Customer of an AR	Data subject for any personal data referenced in supervisory artefacts	Referenced by case reference only; no structured customer PII collected
FCA-auditor (per-tenant flag)	Recipient with read-only access	Only when the principal firm has enabled the role

Top-level flow

flowchart LR
  AR[AR firm and AR-individual] -->|MI return, breach report| WS[Workspace API]
  PCO[Principal-compliance-officer] -->|file review, breach triage| WS
  PA[Principal-admin] -->|AR onboarding, settings, sign-off| WS
  WS -->|writes| PG[(Postgres, RLS by tenant_id)]
  WS -->|append| AUD[(audit_events, INSERT-only)]
  AUD -->|nightly roll-up, object lock 10y| S3[(S3 compliance mode)]
  WS -->|transactional email| PM[Postmark]
  WS -->|error events, PII scrubbed| ST[Sentry]
  WS -->|attachments| OS[(S3-compatible object storage)]
  WS -->|read, scoped| FCA[FCA-auditor, per-tenant flag]
  WS -->|self-service read| AR

The workspace is hosted on Vercel. Postgres is provided by Supabase, Neon, or Railway depending on operator preference; the default is Supabase EU-region. All sub-processors are listed in sub-processors.

Per-record flows

AR-individual to principal firm: MI return submission

1. AR-user signs in (POST /api/auth/session), session cookie issued, lockout policy applies (10 fails per email per hour).
2. AR-user opens /ar/mi, drafts the return locally (localStorage) until ready.
3. AR-user submits (POST /api/mi-returns/:id/submit). The handler validates against MIReturnDraftSchema (Zod), recomputes the anomaly score against the AR’s 8-quarter trailing distribution, writes the mi_returns row, emits mi-return.submitted to the audit chain, and triggers a risk-score recompute.
4. Principal-compliance-officer sees the submitted return in the AR detail page. They mark it queried or accepted, both writing to the audit chain.
5. The AR’s view of the return is read-only after submission; subsequent transitions are visible to the AR via their own audit log.

AR-individual to principal firm: breach report

1. AR-user opens /ar/breaches/new and submits (POST /api/breaches).
2. Validation against BreachReportSubmissionSchema. The awareAt timestamp the AR provides drives the SUP 15 clock; the server records reportedAt separately.
3. The breach lands in the principal-side breach triage queue (GET /api/breaches). The principal-compliance-officer triages, classifies materiality, and either notifies the FCA (POST /api/breaches/:id/notify-fca, step-up authentication required) or progresses the breach to in-remediation without notification.
4. Every state transition writes to the audit chain. The AR sees their own breach in their own surface and via the audit log.

Principal firm to AR-individual: file review

1. Principal-compliance-officer schedules a file review (POST /api/reviews) against the AR. The handler picks the rubric from the principal firm’s vertical (MCOB / ICOBS / CONC).
2. Reviewer works through the rubric in /principal/reviews/[id], saving findings inline (PATCH /api/reviews/:id).
3. Reviewer completes the review (POST /api/reviews/:id/complete). Findings, score, and notes are locked. AR’s risk score recomputes.
4. AR sees the completed review with Challenge affordance for 10 working days. A challenge re-opens the review and writes a review.challenged event.

Principal firm to FCA: SUP 15 notification

1. Principal-compliance-officer marks a breach as material or significant.
2. Principal-admin records the FCA notification (POST /api/breaches/:id/notify-fca) with step-up authentication. The handler sets notifiedFcaAt, writes the audit event with the second-factor event id, and (in production) generates a CSV bundle for the FCA-required submission.
3. The notification itself happens out of band via the FCA’s standard channels; the workspace records the timestamp and the actor but does not directly transmit to the FCA in v1.

Annual review packet and director sign-off

1. The annual review record aggregates references to the AR’s risk trajectory, breach summaries, file review summaries, MI returns, and conduct events over the cycle year.
2. Principal-compliance-officer drafts and submits for review (PATCH /api/annual-reviews/:id).
3. Principal-admin (acting as named director) signs off (POST /api/annual-reviews/:id/sign-off) with step-up authentication. The director’s name, the firm’s FRN, and the verbatim signOffNotes are recorded.
4. Replay: at any future date, the packet can be reconstructed from the audit chain showing exactly what the director saw at sign-off.

Sub-processor flows

Three flows leave the platform’s primary database to a sub-processor.

Transactional email (Postmark). Outbound: invitation emails, MFA enrolment links, breach-deadline reminders, weekly digests. Postmark holds the recipient address and the message body for 45 days, then deletes. The workspace does not transmit personal-data-rich content via email; the email is a notification with a link back to the workspace.

Error monitoring (Sentry). Outbound: server-side exceptions with stack traces. PII is scrubbed at the SDK layer (beforeSend hook strips known PII fields from the event payload). Sentry retains for 90 days on the EU plan. The DPIA covers Sentry as a sub-processor.

Object storage (S3-compatible). Outbound: attachment uploads, audit chain nightly roll-up under object lock. Attachments are virus-scanned at upload before being persisted. The audit roll-up is append-only and immutable for 10 years.

Cross-tenant isolation

No data crosses tenant boundaries. Postgres RLS enforces tenant_id = current_setting('app.tenant_id')::uuid on every query; the session middleware sets the GUC at the start of each connection. A code path that omits the GUC fails closed (no rows returned). The audit chain is per-tenant, anchored at the tenant’s creation event.

The platform-operator’s own staff have access to the production database via a separately audited break-glass mechanism, recorded as a tenant-external operational event. This is documented in the platform operator’s own internal runbook and is not exposed to principal-firm tenants.

International transfers

Default deployment: UK-region Vercel, EU-region Postgres (Supabase Frankfurt or Neon EU), EU-region object storage. Postmark and Sentry have EU-region offerings; the platform operator selects the EU plan in both cases.

Where any incidental US transfer occurs (Sentry on the US plan, for operators that prefer it), the transfer relies on UK Standard Contractual Clauses or the UK Extension to the EU-US Data Privacy Framework. The DPIA documents the transfer assessment.

Subject-rights flows

Subject rights requests (Articles 15 to 22 of UK GDPR) are routed through the principal firm as controller. The workspace exposes:

• Subject access export (POST /api/subjects/export, principal-admin only): produces a JSON bundle plus a human-readable PDF of every record where the named subject’s email or user id appears, plus the audit events keyed to those records.
• Erasure tombstoning (POST /api/users/:id/off-board, principal-admin only, step-up required): replaces the user’s name and email with stable opaque tokens. actorUserId foreign keys are preserved for audit-chain integrity. The supervisory records themselves are retained under the SYSC 9 / Article 17(3)(b) exemption.
• Restriction flag (PATCH /api/users/:id with restricted: true): hides the user from list views while preserving in storage.

The principal firm’s response to a subject-rights request explains the SYSC 9 retention exemption where it applies. The DPIA covers the response template.