All posts
Architecture · 11 min read · Jun 18, 2026

Designing Calculation Engines That Return Explainable Results

A calculation result carrying its own derivation

A method that takes an application and returns an amount looks complete. It is correct, it is tested, and it is finished until the first person disagrees with the output. Then the questions start: why this figure, why lower than expected, which rate was used, what would have to change to get more. None of them can be answered from a number.

The usual answer is that someone opens the code, reconstructs the path for that case, and explains it in an email. That works at ten cases a month and collapses at a thousand. The alternative is to make the calculation return its own derivation - a design decision with consequences well beyond whichever engine performs the arithmetic.

Who needs the explanation

  • The applicant, who wants to know why the figure differs from what they expected.
  • The approver, who is accountable for a decision they did not compute.
  • Support, answering the same question dozens of times without access to a debugger.
  • Audit, months later, asking whether the policy in force at the time was applied.
  • Finance, reconciling your output against a downstream system that disagrees by a small amount.
  • Your own team, deciding whether a reported bug is a bug or the rules working correctly.

That last one is worth dwelling on. Without a derivation, every disputed result is a development investigation. With one, most are resolved by reading the record - which changes the cost profile of the whole system.

The anatomy of an explainable result

PartWhy it is there
The inputs, echoed backProves what the calculation saw, which often differs from what the user believes they submitted
The policy version appliedMakes the result reproducible after the policy changes
Intermediate valuesWhere the number stopped matching expectation is usually mid-calculation
The decisions taken, as codesWhich branch, band or category applied, in a form that can be reported on
The binding constraintAnswers why not more, which is the most common question of all
The final value and its roundingThe output, plus how it got to that precision
Six parts, none optional if the result will ever be questioned.

The binding constraint is the part teams leave out and regret. A result of two hundred thousand explains nothing; a result of two hundred thousand because the scheme maximum applied, where the percentage alone would have given two hundred and eighty, answers the question before it is asked.

Shape it as a result object

None of this requires a rules engine. It requires that the calculation returns a structure rather than a scalar, and that every step writes to it as it goes.

java
public final class CalculationResult {

    private final Map<String, Object> inputs;
    private final String policyVersion;
    private final List<Step> steps;
    private final BigDecimal finalAmount;
    private final String bindingConstraint;   // null when nothing bound

    // Each step records a stable code, the values it used,
    // and what it produced.
    public record Step(
        String code,              // BASE-01, RATE-02, CAP-01
        String description,
        Map<String, Object> using,
        BigDecimal produced
    ) {}
}
The derivation is data, so it can be stored, rendered, compared and tested.

Because the steps are data rather than log lines, everything downstream becomes possible: rendering them in a screen, attaching them to a letter, asserting on them in tests, and reporting on which constraint binds most often.

Reproducibility needs the policy version

An explanation that cannot be regenerated is a snapshot, not an explanation. The requirement to state is precise: the same inputs, with the same policy version, must produce the same output forever.

That is only achievable if the rates, caps and thresholds are versioned rather than overwritten, and if each processed case records which version it used. Storing only the current values means a case processed last year cannot be recomputed at all, which is exactly when someone asks. This is the reproducibility requirement that should drive how policy values are stored in the first place.

Never rebuild the explanation in the interface

The most common failure here is not omitting the explanation. It is producing it twice - once in the calculation, once in the screen or the letter template that describes the result to a human. The second implementation is written from the same specification, drifts within months, and produces the uniquely damaging outcome where the system shows a correct number alongside an incorrect explanation of it.

The rule is that the calculation is the only thing allowed to say why. Presentation formats what it produced and adds nothing. If a screen needs a sentence the derivation cannot supply, the missing piece belongs in the derivation.

Codes for machines, text for people

Each step should carry both a stable code and human wording, and they serve different purposes. The code never changes, so it can be referenced in a support ticket, counted in a report, and asserted in a test. The wording can be rewritten, translated, and softened for an applicant without invalidating anything.

Collapsing them into one field forces a bad trade: either the report groups by a sentence that someone will improve, or the applicant reads a message that looks like an error identifier. Keeping both costs one extra field.

Choosing the granularity

A full execution trace is not an explanation - it is a log, and it overwhelms the reader without answering the question. The right granularity is the smallest set of steps that answers why is this not what I expected.

In practice that means one step per business-meaningful decision: how the base figure was established, which category applied, what rate that gave, what the computed amount was, and what constrained the final result. Five steps that map to sentences in the policy document beat fifty that map to method calls.

Test the derivation, not only the total

Asserting on the final amount alone lets a calculation be right for the wrong reason - two offsetting errors, or a correct figure produced by a rule that should not have applied. Those defects survive every test and surface later as a case where the offset no longer cancels.

java
// Weak: passes even if the wrong rate and wrong base cancel out
assertEquals(new BigDecimal("280000"), result.finalAmount());

// Strong: asserts the path as well as the destination
assertEquals(new BigDecimal("280000"), result.finalAmount());
assertEquals(List.of("BASE-01", "RATE-01", "COMPUTE-01"),
             result.stepCodes());
assertNull(result.bindingConstraint());
Golden derivations catch the right-answer-wrong-reason class of defect.

Store it with the record

A derivation regenerated on demand is not the derivation that produced the original decision - code has changed since. Persist it alongside the result at the moment of calculation, and treat it as part of the record rather than as a cache.

The storage cost is trivial next to the documents these systems already hold, and it is what makes the figure defensible years later. It also gives the approvers downstream something to review other than a total, which measurably improves the quality of the approvals themselves.

Conclusion

Returning a number is the cheapest thing a calculation can do and the most expensive thing to live with. Return the inputs it saw, the policy version it used, the decisions it took as stable codes, the constraint that bound, and the final value - stored with the record, generated in exactly one place, and asserted in tests. The arithmetic is the easy part. Being able to defend the arithmetic, to an applicant or an auditor, years after the code has moved on, is what the design is actually for.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar