Operating model

Architecture, API and accounting controls

Implementation guidance for Finance, security, operations and engineering. Detailed Markdown guides are included in the repository docs folder.

Help centre OpenAPI JSON API guide

Ledger architecture

Each layer has a distinct accounting purpose

SubledgerA detailed ledger that sits below the general ledger. The FCY subledger tracks open items in foreign currency; the ZAR subledger tracks their rand values, settlements and exchange differences.

Gross statistical ledger Statistical entryA record of the gross premium or claim amount in the contract currency. Statistical entries are only ever added to, and settlement, fees or exchange movements never change them.Immutable premium and claim quantum in contractual FCY.
FCY operational subledgerOpen receivables, payables, reserves and allocations.
ZAR accounting subledger ZAR carrying valueThe rand value an open foreign-currency item is currently held at in the books. It starts at the recognition-rate value and is restated at each month-end until the item is settled.Recognition, carrying, settlement and revaluation values.
General-ledger boundary JournalA balanced set of ZAR debit and credit lines for the general ledger. Each journal links back to the transactions that produced it.Approved, balanced ZAR journals with source-item detail.

Recognition rules

The system derives every rate date

Recognition rateThe exchange rate used when a transaction is first recorded. Premiums use the policy inception date, liability claims use the date reported and all other claims use the date of loss.

PremiumPolicy inception date.
Liability claimDate reported.
All other claims use date of lossThe derived rate date is read-only.
Settlement Settlement rateThe exchange rate on the bank or payment value date. It gives the rand value of the cash received or paid; the difference from the carrying value is realised FX.Bank or payment value date; system-calculated realised FX.
Month-end Closing rateThe exchange rate at the end of a reporting period. Items still open at month-end are restated at this rate.Open items are restated at the closing rate on the period end.

Role and permission matrix

Least privilege is enforced server-side on every request

Maker-checkerA control where one person prepares a transaction and a different person approves it. Nobody can approve their own work.

Role	Authorised scope	Control
Finance preparer	Captures policies, premiums, receipts, fees and statements, and prepares the month-end close.	Maker cannot check own work
Finance approver	Posts premiums and receipts, issues statements and approves the month-end close.	Maker cannot check own work
Claims preparer	Registers claims and prepares reserve movements and payments.	Maker cannot check own work
Claims approver	Approves claim reserve movements and payments.	Maker cannot check own work
Underwriting	Sets up policies and reads premiums.	Maker cannot check own work
Treasury	Approves remittances and looks after bank profiles.	Maker cannot check own work
Auditor	Reads the register, statements, transactions and the full audit history, and can export them.	Maker cannot check own work
Administrator	Can do everything, including viewing people, rate providers and system settings.	Maker cannot check own work

The full permission list for each role is on Users and roles. In production, roles are assigned in Microsoft Entra ID.

Receipt modes

Cash direction is configured per component

Net cashThe money actually expected in the bank: the gross amount allocated minus the amounts the broker keeps, such as commission.

Mode	Cash	Commission	FX
Net commission receipt	Gross less broker-retained components	Settled through commission clearing	Receivable and payable FX kept separate
Gross receipt	Full gross premium	Remains payable for separate settlement	Receipt FX recognised at bank value date

API

Versioned JSON over HTTPS with one response envelope

Read the API guide

Other systems API keyA secret that lets another system use this application's API with limited permissions. It is shown only once, expires, and can be revoked at any time.Systems sign in with an API key or a Microsoft Entra application registered by an administrator. They can read and prepare work but never approve, close a period or administer. The API guide explains access, examples and every endpoint.
Envelope Correlation IDA reference attached to every request and response. Quote it to support so they can find exactly what happened.Every response is { ok, data | error, correlationId }; errors carry a code, a message and field-level violations.
Writes Idempotency keyA unique reference sent with a request so that repeating it, for example after a double click or a dropped connection, does not create a second record.Every create, validate, approve and post needs an Idempotency-Key header, so a retry never creates a second record.
ExportsThe register and audit history accept format=csv and export every row that matches the filters, with a UTF-8 byte-order mark and spreadsheet-safe cells.

Role

Authorised scope

Control

Finance preparer

Captures policies, premiums, receipts, fees and statements, and prepares the month-end close.

Maker cannot check own work

Finance approver

Posts premiums and receipts, issues statements and approves the month-end close.

Maker cannot check own work

Claims preparer

Registers claims and prepares reserve movements and payments.

Maker cannot check own work

Claims approver

Approves claim reserve movements and payments.

Maker cannot check own work

Underwriting

Sets up policies and reads premiums.

Maker cannot check own work

Treasury

Approves remittances and looks after bank profiles.

Maker cannot check own work

Auditor

Reads the register, statements, transactions and the full audit history, and can export them.

Maker cannot check own work

Administrator

Can do everything, including viewing people, rate providers and system settings.

Maker cannot check own work

Mode

Cash

Commission

Net commission receipt

Gross less broker-retained components

Settled through commission clearing

Receivable and payable FX kept separate

Gross receipt

Full gross premium

Remains payable for separate settlement

Receipt FX recognised at bank value date