If you are building the systemMedium

Engineers, data and product people who have to model a trade they never see. The domain is the hard part, not the code — and almost nothing written for developers explains it.

7 min read · 1 249 words

Somebody has to build the thing that books the trade, values the position, sends the confirmation and produces the number a regulator reads. That work is mostly domain modelling, and the domain is documented for people who trade rather than for people who represent it. This page adds no new subject matter: it is a route through what is already here, in the order a system actually meets it.

Why the usual explanation is the wrong shape for you

• You need the states, not the motivation. Why somebody bought a swap is not a field. What the swap is between the trade date and the first payment, and what has to be true for it to move on, is the whole of your problem.
• The edge cases are the requirement. A trading explanation gives the normal path in a sentence and the exceptions never. Your system spends most of its code on the exceptions, and every one of them has a name somebody expects you to know.
• Nothing is one thing. An instrument has several identifiers, several prices, several dates and several quantities, and each pair of them disagrees for a reason. A model that assumes one of each is a model that will be rewritten.
• And the failure mode is silence. A wrong number in this domain does not throw; it is reported, believed, and found weeks later by somebody reconciling. That is the same defect family the rest of this site keeps naming.

Start here: what a trade is as data

• Market microstructure — where a price comes from before it is a number in your database: an order book, a request for quote, an auction. It also says why "the price" is a question rather than a field, which is the first modelling decision you will get wrong.
• What happens when you press buy — the plain-language end-to-end, and the shortest description of the pipeline your system sits inside.
• What a number is measuring — notional, exposure, market value and sensitivity are four different quantities on one position, and a schema with one "amount" column has already lost. Read this before designing anything.
• Price, value and mark — a trade that happened, a model's output, and the number a statement had to print. Three different provenances, and a system that stores them in the same column cannot answer where a figure came from.

Then the lifecycle, which is where the work is

Every asset-class page here answers the same five-stage question — agreeing it, confirming it, clearing it, settling it, and what a failure looks like — so the eleven markets can be read against each other rather than one at a time. That comparison is exactly the one a system has to generalise over.

• Clearing and settlement — novation, the central counterparty, and why the party you traded with is not the party you end up owing. This is the single most misrepresented step in finance software.
• Margin and collateral — initial against variation, and the fact that only one of them comes back. Two different obligations, two different schedules, and modelling them as one number is how a system tells a desk it has cash it does not have.
• A contract note and a broker statement — the documents your output is compared against, field by field, by somebody who will find the discrepancy.
• Why a payment takes days — the answer is not latency, and the reason is structural rather than technical.

Corporate actions: the hardest thing in the domain

If one part of this domain is going to cost you a year, it is this one. An instrument that changes underneath every record that references it, retroactively, on a schedule set by somebody else, with an election deadline and a default if nobody answers.

• Corporate actions — what the events are and what each does to a holding, a position and a history.
• Reading a corporate action notice — the document that arrives, the dates on it, and which of them your system has to act on rather than record. Ex-date, record date and payment date are three different things and only one of them decides who is entitled.
• The general lesson for a schema: history in this domain is not immutable. A split restates every price before it, and a system that treats stored prices as facts will disagree with every chart in the building.

Why reconciliation exists, and what it is really checking

• Because two correct systems disagree. Different sources, different timestamps, different conventions, different rounding — and the difference is information rather than a bug to suppress.
• The conventions page is the one to keep open: day counts, settlement conventions and quoting rules are where two implementations of one formula stop agreeing, and none of them is guessable.
• How a position hits the books — the same holding produces three different reported numbers depending on a classification made when it was bought. Your system is frequently the thing that has to hold all three at once.
• The product control seat is who reads what your system produces and asks why it moved. Their questions are the acceptance criteria nobody wrote down.

The seats around yours

Each of these answers the same six questions, so they can be read against each other: what the seat does, a day, what it is measured on, what it touches on this site, how it goes wrong, and the concepts to master.

• Technology and the quant seat — the two seats this page is most directly for.
• Operations — who lives with what you built, and whose exception queue is the honest measure of it.
• Ratings and data — where identifiers, reference data and prices come from, and the fact that a price has a licence attached to it.
• Risk management — the consumer of your numbers who is allowed to not believe them.

Four things worth knowing before the first design meeting

• An identifier is not an identity. An instrument has several, they are issued by different bodies for different purposes, they are reused, and the mapping between them changes. Building on any single one is a decision to migrate later.
• A date is a convention, not a timestamp. Trade date, value date, settlement date and payment date are four different things, each computed under a calendar that depends on the market and the currency, and none of them is "now".
• A quantity has a unit and the unit is not obvious. Shares, notional, contracts, barrels, per-100 of face. The units section on every asset-class page exists because this is where a system silently multiplies by a hundred.
• And a rounding rule is part of the contract. Not a display concern. Two systems that round differently produce a break every day, for ever, and somebody will spend a career on it.

The one habit

Model the failure before the happy path. Every page in the case studies is a system that worked until an assumption stopped holding, and in most of them the assumption was in a data model rather than in a strategy. When you cannot find the answer, the useful question is not "what should this field be" — it is "what document decides", and which document governs is the general answer.