Unknot
Book a call

A debt module for a platform whose software handles deals but not the math behind them

The situation

A platform’s software runs deals well: the pipeline, the documents, the approvals. It cannot calculate a loan.

Its users lend. They want drawdowns, interest, fees and covenant tests worked out inside the software, not in a spreadsheet beside it.

Nothing has been built yet. The scope is agreed, and the build comes next.

Why it is hard

Loan math looks simple and is not. The rules live in the definitions of a loan agreement, and each agreement writes them slightly differently.

The details that decide the numbers are easy to get wrong:

  • Money drawn mid-period earns interest from the day it is drawn, not from the next period.
  • A floor on the base rate stops the rate falling below a set level, even when the market rate does.
  • The day count decides whether a year has three hundred and sixty days or three hundred and sixty-five.
  • Interest added to the loan, instead of paid in cash, starts earning interest itself from the next period.
  • A fee is charged on the undrawn part of the loan, for as long as it can be drawn.
  • Covenant tests, the limits a borrower must stay within, are defined differently in almost every agreement.

Engineers build what passes their unit tests. The real test is a real loan agreement, and the errors are small in any one period.

Across a book of loans and several years, they are not small. Usually nobody notices until a borrower disputes a statement.

The approach

We will write the specification before any code. Every definition in the documents becomes a rule, with the clause it came from.

  • For each rule, a worked example calculated by hand to the day, agreed with the platform before it is built.
  • A schedule computed period by period, from each day’s balance and the rate after any floor. It gives cash interest, interest added to the loan and fees on the undrawn part.
  • Covenant tests computed from the same figures, each one tied to its written definition.
  • A test suite built from the worked examples, run on every change to the code.
  • A handover the platform’s own engineers can maintain: the specification, the tests and the module.

Nothing ships without the worked example that proves it. When the platform meets a new kind of loan, the first step is a new example, not new code.

A worked example

The loan below is invented, and so is every figure in it. It is 20 million: 12 million drawn at the start and 8 million in mid-May.

The margin is 6.5 percent over the base rate, which has a floor of 2 percent. Undrawn money pays 0.75 percent a year.

From the third quarter, 3 points of the margin is added to the loan instead of paid.

Synthetic example. The correct schedule for a loan of 20 million: 12 drawn at the start, 8 in mid-May. Thousands, except rates.
Quarter Days Base rate used Cash interest Fee on undrawn Interest added to loan Loan at end
Quarter 1904.1%31815012,000
Quarter 2913.4%4047020,000
Quarter 3922.0%281017920,179
Quarter 4922.0%284018020,359

Worked correctly, the borrower owes 1,309 thousand in cash for the year. Another 359 thousand is added to the loan.

The base rate falls below the floor in the second half, so the floor sets the rate. The mid-May draw earns interest for its own days in the second quarter.

Cash due for the year understated, thousands Draw dated to the next period mid-period draw earns nothing 96 No floor on the base rate the rate falls below its minimum 51 A 365-day year not the day count the loan uses 18 Interest added once a year not at the end of each period 3 0 20 40 60 80 100 Synthetic example
Cash due for the year understated, thousands Draw dated to the next period mid-period draw earns nothing 96 No floor on the base rate the rate falls below its minimum 51 A 365-day year not the day count the loan uses 18 Interest added once a year not at the end of each period 3 0 20 40 60 80 100 Synthetic example
Figure 1. A loan of 20 million, drawn in stages: how much each shortcut understates a year of cash owed. Synthetic example.

Four common shortcuts together miss 165 thousand of the cash due, 13 percent. The largest, dating the mid-May draw to the next period, misses 96 thousand on its own.

The smallest shortcut, adding interest to the loan once a year, looks harmless in one year. It compounds for the life of the loan, on every loan in the book.

A test built from the worked example catches each shortcut the first time the code runs.

Where it breaks

  • Worked examples cover the terms we have seen. A loan written in a new way needs a new example before the module can be trusted with it.
  • Covenant tests are computed only as the documents define them. A definition nobody wrote down stays outside the module.
  • It calculates what the agreement says. Amendments and waivers still have to be entered by a person.

If your software calculates loans, test it against worked examples before a real loan does.