Building an Islamic inheritance calculator is like trying to solve a Rubik’s Cube blindfolded. At first glance, it seems like a straightforward problem: take some family relationships, apply some percentages, and output the results. But as any software engineer will tell you, what appears simple often hides a labyrinth of complexity.

Part 1 of a series exploring the technical challenges behind building Miraas, an Islamic inheritance calculator

The Deceptive Simplicity of Islamic Inheritance Calculation: A Software Engineering Perspective

The Problem That Looks Simple

At first glance, building an Islamic inheritance calculator seems straightforward: take some family relationships, apply some percentages, and output the results. How hard could it be?

This assumption couldn’t be more wrong. What appears to be a simple mathematical problem quickly reveals itself as one of the most intricate rule-based systems you’ll encounter in software engineering.

The Engineering Puzzle

1. Complex Conditional Logic

Islamic inheritance law (Ilm al-Fara’id) isn’t just about fixed percentages. It’s a sophisticated system with:

Blocking rules: Certain heirs can completely block others from inheriting
Conditional shares: A mother’s share changes based on whether siblings exist
Cascading dependencies: One heir’s presence affects multiple others’ calculations
Gender-based variations: Male and female heirs often have different rules
Generational considerations: Grandchildren vs. children, paternal vs. maternal relatives

// This innocent-looking method hides incredible complexity
public ShareResult GetShare(RelationType relation, InheritanceCase inheritanceCase)
{
    // Each relation type can have multiple conditional paths
    // Mother gets 1/3, but only if no siblings exist
    // Father gets 1/6 if sons exist, but residue if no sons
    // The combinations are exponential
}

2. The Awl Problem: When Math Breaks

One of the most fascinating challenges is handling Awl - situations where fixed shares exceed 100% of the estate. This isn’t a bug; it’s a feature of Islamic law that requires proportional reduction of all shares.

// When fixed shares total 13/12 (108.33%), we need Awl
if (totalFixed > Fraction.One)
{
    // Proportionally reduce ALL shares
    var awlDenominator = totalFixed;
    foreach (var heir in fixedShareHeirs)
    {
        var originalShare = heir.Result.Fraction;
        var reducedShare = originalShare / awlDenominator;
        // Each 1/4 becomes (1/4) × (12/13) = 3/13
    }
}

3. Precision Matters: The Fraction Challenge

You can’t use floating-point arithmetic for inheritance calculations. Religious and legal precision demands exact fractional representation:

public struct Fraction
{
    public int Numerator { get; }
    public int Denominator { get; }
    
    // 1/3 + 1/6 must equal exactly 1/2, not 0.4999999
}

4. State Management Complexity

The calculation engine must track:

Which heirs are blocked and why
Multiple types of shares (fixed, residuary, Radd)
Warnings and edge cases
Audit trails for transparency

The QA Nightmare

Scenario Explosion

Testing an Islamic inheritance calculator is a combinatorial explosion:

15+ heir types (sons, daughters, fathers, mothers, various siblings, grandparents, spouses)
Multiple counts (2 sons vs. 3 sons changes everything)
Gender combinations (deceased male vs. female affects spouse shares)
Blocking scenarios (sons block many other heirs)
Edge cases (Awl, Radd, residuary distribution)

A conservative estimate: thousands of valid test scenarios.

Domain Expertise Required

Unlike testing a shopping cart, QA engineers need to:

Understand Islamic jurisprudence principles
Verify calculations against religious texts
Distinguish between different schools of thought
Recognize when scholarly review is needed

The Oracle Problem

What’s the “correct” answer? Unlike mathematical functions with clear outputs, inheritance law has:

Scholarly disagreements on edge cases
Different interpretations across Islamic schools
Cases requiring human judgment

QA Testing Strategy & Common Pitfalls

The Layered Testing Approach

Effective QA for inheritance calculations requires multiple testing layers:

1. Unit Testing: Rule Isolation

[Test]
public void Mother_Gets_OneThird_When_No_Siblings_Exist()
{
    var case = new InheritanceCase(new DeceasedPerson(Gender.Male));
    case.AddHeir(new Mother());
    // No siblings added
    
    var result = engine.Calculate(case);
    Assert.That(result.GetHeirShare(RelationType.Mother), Is.EqualTo(Fraction.Third));
}

2. Integration Testing: Rule Interactions

[Test]
public void Complex_Awl_Scenario_With_Multiple_Heirs()
{
    // Husband (1/4) + 2 Full Sisters (2/3) + Mother (1/6) = 13/12 > 1
    // Should trigger Awl proportional reduction
}

3. Acceptance Testing: Real-World Scenarios

Family case studies from Islamic jurisprudence books
Historical precedents from Islamic courts
Edge cases identified by Islamic scholars

Common QA Failures & How They Happen

1. The “Happy Path” Trap

What QAs often test:

Deceased: Male
Heirs: 1 Son, 1 Daughter, Wife, Father, Mother

What they miss:

No sons (changes everything for daughters)
Multiple wives (affects share calculations)
Deceased female (changes spouse shares)
Missing parents (affects sibling inheritance)

2. The Blocking Blindness

Common mistake: Testing heirs in isolation without considering blocking rules.

// This test is WRONG - it ignores that sons block many heirs
[Test]
public void Uncle_Gets_Residue() // ❌ FAILS if sons exist
{
    var case = new InheritanceCase(new DeceasedPerson(Gender.Male));
    case.AddHeir(new Son()); // This blocks the uncle!
    case.AddHeir(new Uncle());
    
    // Uncle gets nothing, not residue
}

3. The Fraction Precision Error

What breaks: Using decimal arithmetic instead of exact fractions.

// ❌ WRONG: Precision loss
decimal motherShare = 1.0m / 3.0m; // 0.333333...
decimal fatherShare = 1.0m / 6.0m; // 0.166666...
decimal total = motherShare + fatherShare; // 0.499999... ≠ 0.5

// ✅ CORRECT: Exact fractions
Fraction motherShare = new Fraction(1, 3);
Fraction fatherShare = new Fraction(1, 6);
Fraction total = motherShare + fatherShare; // Exactly 1/2

4. The Gender Assumption

Subtle bug: Assuming deceased gender doesn’t matter.

// Husband's share depends on deceased gender!
// If deceased is male → impossible scenario
// If deceased is female → husband gets 1/4 or 1/2

5. The Count Confusion

Edge case: Multiple heirs of same type with different rules.

// 1 daughter gets 1/2, but 2+ daughters get 2/3 total
// QAs often test only single counts

Testing Strategy Framework

Phase 1: Rule Verification

Test each inheritance rule in isolation
Verify blocking relationships
Validate share calculations for each heir type

Phase 2: Combination Testing

Test common family structures
Verify Awl scenarios (shares > 100%)
Test Radd scenarios (shares < 100%)

Phase 3: Edge Case Hunting

Boundary conditions (0 heirs, maximum heirs)
Invalid combinations (husband + male deceased)
Scholarly disagreement cases

Phase 4: Domain Expert Review

Islamic scholar validation
Cross-reference with jurisprudence texts
Verify warning messages and scholarly review triggers

The QA Checklist That Actually Works

✅ For each test case:

Specified deceased gender
Considered all blocking relationships
Used exact fraction arithmetic
Tested both single and multiple counts
Verified total shares equal 100% (or explained why not)
Checked for appropriate warnings
Validated against Islamic jurisprudence source

✅ For the test suite:

Covers all 15+ heir types
Tests all blocking combinations
Includes Awl scenarios (shares > 100%)
Includes Radd scenarios (shares < 100%)
Tests invalid input handling
Verifies scholarly review triggers

The AI/LLM Trap: Why Automation Fails

The Hallucination Risk

Large Language Models seem perfect for this problem - they’ve ingested Islamic texts and can generate inheritance calculations. But this is precisely where they become dangerous:

❌ LLM Output: "The wife gets 1/4 because there are no children"
✅ Reality: Wife gets 1/8 because stepchildren (sons of deceased) exist

The Stakes Are Too High

This isn’t a chatbot giving restaurant recommendations. Incorrect inheritance calculations can:

Violate religious obligations - potentially affecting one’s spiritual standing
Cause family disputes - destroying relationships over money
Create legal issues - in countries where Islamic law applies
Perpetuate injustice - giving someone more or less than their religious right

The Confidence Problem

LLMs present answers with artificial confidence. They don’t say “I’m 60% sure” - they state rules as facts. In inheritance law, uncertainty should trigger scholarly consultation, not algorithmic guessing.

Why This Matters for Engineers

This project teaches us that:

Domain complexity is often hidden - Simple requirements can hide exponential complexity
Precision requirements vary by domain - Financial/legal systems need different standards
Cultural and religious sensitivity - Some domains require extra care and humility
Testing strategy must match domain - You need domain experts, not just test cases
AI isn’t always the answer - Some problems require deterministic, auditable logic

The Path Forward

Building Miraas taught us to:

Embrace the complexity rather than oversimplify
Separate concerns clearly (blocking, shares, distribution)
Make calculations transparent and auditable
Always recommend scholarly review for edge cases
Test extensively with domain experts

In our next post, we’ll dive deeper into the specific engineering patterns we used to tame this complexity, including the blocking engine, share calculation strategies, and how we handle the dreaded Awl scenarios.

Miraas is available at https://miraas.azurewebsites.net - but remember, it’s a tool to assist understanding, not replace scholarly consultation.

Github: https://github.com/khurram-uworx/miraas

Miraas: A Software Engineering Perspective on Islamic Inheritance Calculation