Building TaxCalc.ng: Engineering Lessons From Creating a Nigerian Tax Compliance Platform

Software that deals with taxes has to earn trust. A result can look polished and still be unhelpful if a person cannot understand what it means, what to do next, or whether the workflow reflects the rules that apply to them.

That shaped how I approached TaxCalc.ng. I was not only implementing formulas. I was translating a complicated subject into a product people could use with confidence, while keeping the system understandable enough to maintain as requirements changed.

Here, I am reflecting on the product and engineering choices behind that work. I am staying with the public lessons rather than private business information or internal implementation details.

The problem was bigger than calculations

At first glance, tax software can look like an input-and-output problem: collect a few numbers, apply the relevant rules, and show a result. The calculation matters, but it is only one part of the experience.

People also need to know which information belongs in each field, why it is needed, and what the result means. They may arrive with incomplete records or a different understanding of the terminology. A mathematically correct answer does not create much confidence if the route to it feels opaque.

I came to see the problem as two connected parts:

• represent tax and payroll rules accurately enough for the supported use cases;
• present those rules as a workflow that a person can follow without having to think like the software.

That distinction shaped my product decisions as much as my technical ones. Labels, validation messages, ordering, and explanations all became part of correctness.

Designing for real users

Compliance language is precise, but precision can become a barrier when it is copied directly into an interface. I had to decide where the product should retain formal language and where a plain explanation would help someone move forward.

For this product, simplifying the experience did not mean simplifying the underlying rules. It meant revealing complexity when it became useful. I wanted people to see the next decision they needed to make, not every branch the system might eventually evaluate.

This led me to favour focused flows over large forms. I also treated validation as guidance rather than a final obstacle: catching a missing or inconsistent value close to where it was entered makes the problem easier to understand and correct.

There is a trade-off here. More explanation can reduce uncertainty, but too much makes an important task feel heavier. I found a useful balance by keeping the main path concise and putting context near the decisions that needed it.

Building reliable workflows

When I think about reliability in compliance software, I am not only asking whether the application is online. I am also asking whether the same inputs produce a consistent result, whether invalid states are rejected clearly, and whether a change in one part of a workflow has an unexpected effect somewhere else.

I found it helpful to separate the rule-oriented parts of the product from the way screens collect and display information. That boundary makes both sides easier to reason about. It also makes it possible to test important cases without relying only on a person clicking through the interface.

The constraints were practical. Tax rules can change, people can provide surprising combinations of data, and a small team has limited time to operate complex systems. That made explicit behaviour, repeatable checks, and clear failure states more valuable to me than clever abstractions.

Not every edge case should be hidden behind a default. When the system does not have enough information to make a responsible decision, asking a clear follow-up question is often more reliable than guessing.

Choosing simplicity before complexity

It is tempting to respond to a serious domain by building a serious-looking architecture. I do not think those are the same thing. More services, queues, data stores, and layers would create more ways for the product to fail without automatically making a calculation or workflow more trustworthy.

For this project, I preferred a small number of well-understood components and added complexity only when a real requirement called for it. That kept the path from a rule to the result easier to trace, which matters when behaviour needs to be checked or changed.

The trade-off was accepting that a simple design might need deliberate revision as the product grows. I would rather make that revision with evidence than pay the operational cost of hypothetical scale from the beginning. A design I can explain and test is a useful starting point; it can evolve when I can see where the pressure actually is.

Lessons learned

The strongest lesson for me was that trust is built across the whole workflow. Correct calculations are essential, but so are understandable questions, useful validation, predictable behaviour, and honest handling of uncertainty.

I also learned to treat domain rules as product material, not just implementation detail. Working through why a rule exists and how a person encounters it often exposes a better product decision than starting from the shape of the code.

Finally, I learned that simplicity needs discipline. A small architecture is valuable when its boundaries are clear, its important paths are tested, and the team can tell when the current design no longer fits. For TaxCalc.ng, that approach has helped me keep my attention on the real problem: making tax and payroll compliance easier to understand and operate.