System Architecture · Corex Financial Systems

The infrastructure
behind a real
cross-border FX system.

Corex didn't start as code. It started as a WhatsApp operation moving AOA ↔ ZAR by hand — and every architectural decision below exists because I lived the operational problem it solves.

188 Java classes 19 tables · 19 migrations 306 tests · all passing state-driven core full audit trail
01operational_context

Built from operational friction,
not from a tutorial.

Before a single line of Java, the business ran on messages, spreadsheets and trust. The architecture is a direct translation of those real constraints into a system.

// the manual reality
Coordination by hand
Matching a client who needs ZAR with a supplier holding ZAR — confirming rates, payments and timing manually over WhatsApp. Every step was a potential point of failure or dispute.
// the trust problem
Who pays first?
In P2P FX, the core tension is settlement order. The system encodes this with a state machine, payment verification and an immutable audit log — so trust comes from the structure, not from knowing someone personally.
// the scale problem
One operator, many transactions
Manual coordination doesn't scale past a handful of deals a day. Automated matching, timeouts and status transitions let the system carry the operational load that a person used to.
// the compliance problem
Everything must be traceable
Moving money across borders demands a record of every action. Audit logging isn't a feature bolted on — it's woven into each transition, so any transaction can be reconstructed end to end.
02operational_flow

How a single exchange
moves through the system.

From the moment a client requests an exchange to final settlement and audit. Scroll horizontally to follow the full path.

01 Client Request
02 Quote Engine
03 Instant-Rail Match
04 Payment Verification
05 Settlement
06 Audit Logging
07 Completed
03transaction_state_machine

Every transaction is
a finite set of states.

The lifecycle is explicit. A transaction can only move forward through defined transitions — and any deviation routes to a controlled terminal state.

PENDING matched · awaiting payment
PAID proof submitted
CONFIRMED funds verified
PROCESSING payout to beneficiary
COMPLETED terminal · success
alternative terminal states
CANCELLED · incl. automatic timeout DISPUTED · controlled resolution path
04design_principles

The constraints that
shaped the system.

P_01
State before features
A money-moving system lives or dies on its state model. Before building any UI, the transaction lifecycle was defined as an explicit state machine — illegal transitions simply cannot happen.
P_02
Every action leaves a trace
Audit logging is not optional. Each transition writes an immutable record — who, what, when — so any transaction can be reconstructed and any dispute resolved against facts.
P_03
Time is a first-class actor
In FX, a stale quote is a liability. Automated timeout rules expire pending states and release matched liquidity, so the system never hangs waiting on a human that went quiet.
P_04
Trust encoded in structure
Instead of relying on personal relationships, trust scoring and payment verification make the settlement order safe between parties who have never met.
P_05
No custody by design
The platform never holds client money — it goes straight to the partner. Safety comes from collateral the partner posts, which caps how much exposure they can carry at once, not from us sitting on the funds. Commissions accrue in a settlement ledger closed per cycle: an accounting record, not an escrow wallet.
05three_worlds

One platform,
three worlds.

Every user enters through their own door, with their own narrative, permissions and dashboard — around one shared matching heart.

// world 01 · client
Exchange in one page
Direction, payment rail with limits in sight, amount validated against the rail's cap, beneficiary, match — one screen, no stepper. KYC gates block any transaction until identity is verified.
// world 02 · partner
A cockpit, not a form
Liquidity partners see incoming orders first, manage their instant-payment accounts per rail, and track their growth, projections and reliability score — the metrics the match engine actually uses.
// world 03 · operations
Structure over supervision
The Corex team configures rails and reference rates, verifies KYC, resolves disputes and closes commission settlements — with every action written to the audit trail.
06implementation

What it runs on.

A deliberately boring, proven stack — chosen so the interesting complexity lives in the domain logic, not in the infrastructure.

Java 17 Spring Boot Spring Security PostgreSQL 15 Flyway JWT Auth REST API Next.js TypeScript Matching Engine State Machine Audit Logging

This is how I think
about your system too.

If you have an operational problem that needs to become real infrastructure — structure first, then execution — let's talk.

Let's Talk Back to Portfolio