# Architecture

## System rule

**The middleware connects systems; FEI decides; the Ledger records; the Platform presents; regulated providers execute.**

## Connection model

```text
External ecosystem
  -> External Integration Zone
  -> canonical commands and events
  -> Threasury internal services
  -> Platform BFFs
  -> web, mobile and enterprise experiences
```

### Northbound

Approved employers, universities, fintechs and corporate partners use versioned External APIs. Authentication alone is insufficient: contract, capability, consent, purpose and resource-scope policy must all allow the request before a canonical command can reach FEI.

### Southbound

FEI emits canonical commands to the Internal Integration API. The adapter runtime selects a certified adapter and contains all provider-specific authentication, payloads and workflow. Normalised provider results return as canonical facts and events.

### Inbound events

Provider webhook -> signature and replay validation -> deduplication and ordering -> canonical event -> durable event backbone -> Payment Orchestration/Reconciliation -> Ledger Command Gateway.

The Gateway can say that a provider settled instruction `pay_234` for GBP 250.00. It cannot choose debit/credit accounts or create postings.

### Outbound events

Internal domain event -> disclosure and permission decision -> partner transformation -> signed webhook/API/file delivery. Raw journals are not exposed unless explicit policy and use case allow it.

## Source of truth

| Component | Authority |
| --- | --- |
| FEI | Missions, commitments, rules, co-ordination and decisions |
| Ledger | Journals, postings, balances, allocations and reconciliation |
| Identity | Parties, authentication, roles and consent |
| Payment Orchestration | Payment-instruction lifecycle |
| Gateway | Integration state, mappings, delivery state and partner configuration |
| Provider | Provider-side accounts, transactions, settlement and regulated execution |
| Apps | No authoritative financial or domain state |

### Consent and provider permission

Threasury's Consent Manager is authoritative for the customer's purpose-bound grant, requested data scopes, expiry, evidence and revocation. A regulated provider remains authoritative for the permission it holds for its own Item or bank connection. The Gateway keeps those states separate: it observes provider permission and expiry, launches provider reauthorisation, consumes signed permission webhooks and revokes provider access through the certified adapter. Provider permission never broadens or replaces the Threasury grant; both must permit access.

## Extension model

New providers implement `ProviderAdapter`, declare canonical capabilities, pass the common certification suite and are promoted per capability and environment. No provider-specific class may be imported by FEI, Ledger, Platform BFFs or canonical domain code.