Backend & data

Architectural principles

1. Monolithic backend. The platform runs as a single deployable application against a single Postgres database. The modules below are logical (one codebase, one process); they are not separately deployed services.
2. The audit log is the system of record. Every state change writes an audit entry first; module state derives from the audit. Anchored to chain every 10 minutes.
3. Tenant isolation is enforced at the database level, not just the application. Every customer-data row carries tenant_id; no query can cross tenants without a platform-admin context.
4. Money is integer pence. Never float, never decimal. Currency is always Great British Pound (GBP) unless explicitly USD Coin (USDC) on a stablecoin settlement.
5. Idempotency at every external boundary. Every Application Programming Interface (API) mutation requires FX-Idempotency-Key; replays return the original response.
6. Append-only audit; mutable state. Domain rows can be updated; audit rows can never be (database-level append-only constraint).
7. Compliance fails closed. If a downstream provider (Sumsub, ComplyAdvantage) is unreachable, the gate stays open in pending state — never silently approves.
8. Chain compliance modules are the last line. Even if every off-chain check is bypassed, the on-chain Compliance Module on Ethereum Request for Comments 3643 (ERC-3643) will block a non-compliant transfer.
9. No secrets in code or config. Provider credentials live in Hardware Security Module (HSM)-backed vault, fetched on boot, rotated quarterly.

Module map

The backend is a single deployable application — one process, one Postgres database. The list below is a logical map: twelve domain modules within that application, each owning a defined set of tables and a clear interface that other modules call in-process. The only network boundaries are the external Representational State Transfer (REST) + webhooks surface, the connections out to providers, and the connection to the FinToken X Network. "Service" is used colloquially below to mean a module's service class, not a separately deployed network service.

Module interaction · single invoice

Data model

Key tables. Column lists are illustrative — the canonical schema lives in migrations.

Core tables

Tenant isolation

State machines

Invoice

Subject (any role)

Buyer-specific lifecycle

Token lifecycle

External integrations

Chain & ERC-3643

The token mechanics, in detail.

Network

• FinToken X Network — permissioned EVM, Hyperledger Besu, Istanbul Byzantine Fault Tolerance (IBFT) 2.0 consensus.
• Validators: FinToken X (3 nodes), Mercia Bank (2 nodes), one future second partner (2 nodes). Quorum: 5 of 7.
• Block time 2s; finality on consensus block (~2s).
• No public bridge. RPC access gated by mutual Transport Layer Security (mTLS)-authenticated relay; explorer access limited per-subject to own holdings.
• Native gas token has no commercial value; metered for spam protection only. FinToken X funds gas for all token operations on behalf of users.

Contracts

Mint flow

1. invoice.state = CONFIRMED (buyer clicked C2).
2. tokenisation.mint(invoice_reference) called. Generates tokenId; computes face_pence.
3. Calls FXReceivableToken.mint(receiver=fx_minting_wallet, tokenId, face) with FinToken X validator signing.
4. On confirm, token.state = MINTED in domain DB; audit entry written.
5. Listing event fires; marketplace surfaces it to lenders within filter.

Transfer flow (lender funds)

1. Lender calls POST /v1/payments with idempotency key.
2. Settlement service initiates fiat leg (FPS from lender's designated account → FinToken X collections).
3. Tokenisation service calls FXReceivableToken.transferFrom(fx_minting_wallet, lender_wallet, tokenId).
4. The chain Compliance Module checks: lender has KYC_VERIFIED + AML_CLEARED + JURISDICTION_UK claims. If yes, transfer succeeds.
5. Audit entry: FUND_INVOICE, both fiat and chain references attached.

Compliance module logic

Pseudocode, in the order the rules run on every transfer:

function canTransfer(from, to, tokenId, amount) returns (bool, reason) {
  // 1. Both wallets must be in the Identity Registry
  if (!identityRegistry.isVerified(from) || !identityRegistry.isVerified(to))
    return (false, "wallet not verified");

  // 2. Receiver must hold required claim topics
  for topic in [KYC_VERIFIED, AML_CLEARED, JURISDICTION_UK]:
    if (!claimsRegistry.has(to, topic))
      return (false, "missing claim: " + topic);

  // 3. If transferring to an investor (not the original lender), MiFID classification required
  if (isInvestor(to) && !claimsRegistry.hasOneOf(to, [MIFID_PROFESSIONAL, MIFID_ECP]))
    return (false, "MiFID classification required");

  // 4. Lock-up (post-funding cooldown — none currently active, future-proofing)
  if (token.isLocked(tokenId)) return (false, "token locked");

  // 5. Sanctions delta — read latest, fail closed
  if (sanctionsCheck.isFlagged(from) || sanctionsCheck.isFlagged(to))
    return (false, "sanctions");

  return (true, "ok");
}

Burn flow

1. collections reconciliation matches obligor inbound credit to invoice_reference.
2. Onward payments fire to lender + (if fractionalised) all slice holders.
3. On all onward payments confirmed, FXReceivableToken.burn(tokenId) called.
4. Token state → BURNED; burned_at + burn_tx recorded; audit entry anchored.

Audit log & tamper-evident store

The single most regulator-relevant subsystem on the platform.

Architecture

• Append-only Postgres table audit_entries with no UPDATE grants. DELETE is database-level revoked.
• Every entry includes prev_hash (hash of prior entry) — forms a hash chain.
• Every 10 minutes the audit service reads pending entries, builds a Merkle tree, anchors the root on the FinToken X Network in the FXAuditAnchor contract.
• The chain transaction hash is then written back to the merkle_batches table.
• Verification: anyone with read access can recompute a Merkle path from a target entry to the anchor and verify against on-chain state.

Action taxonomy (illustrative)

Security boundaries

• Module call boundaries are enforced in code, not on the network. The backend is a single process; there is no internal service mesh. Every module entry point checks the caller's role and tenant scope before doing anything; the unit tests pin those checks.
• External REST surface is JSON Web Token (JWT) + per-tenant API key. JWT signed by the auth module; API key carries tenant scope. Both required for sensitive endpoints.
• Webhook signatures HMAC-SHA256 over {timestamp}.{body}. Receivers must verify the timestamp is within 5 minutes of now (replay window).
• HSM-backed signing keys for DKIM, webhook secrets, audit Merkle commit, chain transaction signing.
• Row-Level Security (RLS) at the database — connection-level tenant pinning; no application-only tenant filtering.
• Object storage encryption at rest — invoice PDFs, Sumsub raw payloads, OCR artefacts, all per-tenant keys.
• Quarterly cross-team red-team of the bypass-marking invariant: try to take a customer action as platform admin without leaving a fingerprint, fail closed.

Environments

Rate limits

Related

• Index — overview, principles, money rules.
• End-to-end view — single invoice across all eight personas.
• Platform Admin · audit log — UI on top of this audit subsystem.