Designing a Multi-Level Calculation Engine That Explains Why Results Fail

Most systems today are very good at giving answers. Very few are good at explaining them.

If you’ve ever built a scoring system, risk model, eligibility engine, or analytics pipeline, you’ve likely faced this:

• The final result is “Failed”
• But no one knows why

And that’s where things break down:

• Users lose trust
• Debugging becomes painful
• Business teams keep asking questions

In one of our recent projects, we had to design a multi-level calculation engine where each level depended on the previous one, more importantly, we had to trace failures all the way back to their root cause.

This blog breaks down how to design such a system.

The Problem: Results Without Explainability

Let’s say your system has 4 levels:

• Level 1: Raw data checks
• Level 2: Derived metrics
• Level 3: Aggregated scoring
• Level 4: Final classification (Failed / Good / Advanced / Best in Class)

Now imagine: Level 4 = Failed

But why?

Possible reasons:

• A single input field failed validation
• A derived metric was below threshold
• Aggregation logic weighted something incorrectly

Without traceability, you're blind.

Core Idea: Make Calculations Traceable, Not Just Executable

Instead of designing calculations like this:

final_score = calculate_level4(data)

Design them like this:

result = {
    "value": final_score,
    "status": "Failed",
    "trace": {
        "level_3": {...},
        "level_2": {...},
        "level_1": {...}
    }
}

Every level should return:

• value
• status
• metadata
• failure reasons (if any)

Designing the Multi-Level Flow

Think of it as a pipeline: Level 1 → Level 2 → Level 3 → Level 4

But instead of passing only values, pass context objects:

class CalculationResult:
    def __init__(self, value, status, reasons=None, meta=None):
        self.value = value
        self.status = status
        self.reasons = reasons or []
        self.meta = meta or {}

Now each level:

• consumes previous result
• adds its own reasoning
• propagates failures forward

Failure Propagation Strategy

Key design decision: Should failure at Level 1 automatically fail Level 4?

Two approaches:

1. Hard Fail Propagation: If any level fails → final result = Failed. Simple, strict, easy to reason.
2. Weighted / Conditional Propagation: Some failures are tolerable. Final result depends on scoring thresholds.

Example:

if level_2.score < 50:
    reasons.append("Low derived metric score")

This gives flexibility but requires careful design.

Storing Calculation Logic (Dynamic vs Static)

{
  "field": "revenue",
  "condition": "<",
  "threshold": 1000,
  "failure": "Revenue too low"
}

Debugging & Observability

This is where most systems fail.

Add:

• Structured logs per level
• Unique calculation IDs
• Store traces (even temporarily)

Example output:

{
  "final_status": "Failed",
  "reasons": [
    "Level 2: Revenue too low",
    "Level 1: Missing transaction data"
  ]
}

Now: Devs can debug • Business teams understand • Users trust the system

Performance Considerations

Traceability adds overhead. Optimize by:

• Avoiding deep copies of large objects
• Storing only failure paths (not everything)
• Using lazy evaluation where possible