Rules-as-Code DSL for Payroll Tax with Explainable Payslips

The problem: tax rules change every budget and live in spreadsheets

Every year, a finance bill changes salary tax slabs, rates, exemptions or surcharges. Small companies, schools and software houses that run payroll in spreadsheets or a basic payroll package then scramble: someone edits formulas, someone else checks a few payslips by hand, and errors surface months later as under-deducted tax or unhappy employees. When an employee asks "why was this much deducted?", the honest answer is often "the spreadsheet says so".

The law itself is written as general rules with exceptions. Spreadsheets and ordinary code flatten that structure into nested IF statements that no accountant can review.

What already exists and the gap

• Catala, developed at Inria, is a programming language for law based on default logic, used to formalise French family benefits and US tax sections; it found a bug in an official French implementation.
• OpenFisca is an open source rules-as-code engine in Python used by several governments to model tax and benefit systems.
• Commercial payroll software encodes tax rules inside the vendor's code, updated on the vendor's schedule and not reviewable by the customer.
• Spreadsheets with nested formulas remain the default for many small employers.

The gap is a lightweight DSL aimed at payroll teams rather than governments: small enough to learn in an afternoon, reviewable by an accountant, with tests from official examples and payslips that explain themselves.

What you build

• The language: declarations for inputs (gross salary, allowances, tax year), tax slab tables, and rules. A rule can have a general case and exceptions, so "10 percent on income above X, except for this category" reads like the law. Types include money with a currency, percentages, dates and periods, and the checker refuses nonsense.
• The toolchain: parser, type checker, and either an interpreter or a code generator to Python or JavaScript. Syntax highlighting in VS Code so accountants can read rules comfortably.
• Explanations: evaluation records a trace. On the payslip, each deduction expands to "slab 3 applies because annual taxable income is between A and B; rate R on the excess; plus fixed amount F".
• The demo: upload employees, pick a tax year, generate explained payslips and a year-end summary.

Pick one real jurisdiction for the main rule sets. Salary tax in Pakistan is a good candidate because slabs change frequently, but the language must not hard-code any country.

The technically interesting part

Language design is the core. What constructs does payroll actually need? How do you express exceptions without turning rules into spaghetti? How does the type system prevent a whole class of bugs, such as mixing monthly and annual amounts? Catala's use of default logic is worth studying, and your report should explain which ideas you adopted, which you simplified and why.

The second interesting part is testing against authority. Build your test cases from official worked examples and have an accountant check more. Then show the diff between two tax years: the new budget expressed as a small, reviewable change to rule files, with tests that fail until the rules are updated.

How to evaluate it

• Correctness: all official examples and at least 30 accountant-reviewed cases pass for both tax years.
• Expressiveness: lines of DSL versus lines of equivalent spreadsheet formulas or general-purpose code for the same rules.
• Readability: three or more accountants or finance students read a rule file and answer comprehension questions; compare with the same rules as spreadsheet formulas.
• Change cost: time to encode a new tax year's changes, and number of tests that caught mistakes during the update.
• Checker value: a list of seeded bugs (unit mix-ups, wrong periods) and how many the type checker catches.

Suggested plan

1. Weeks 1 to 3: read Catala and OpenFisca material, collect the tax rules and official examples for your chosen jurisdiction.
2. Weeks 4 to 8: grammar, parser and a minimal evaluator for slabs.
3. Weeks 9 to 12: type system for money, percentages and periods, error messages.
4. Semester 2, weeks 1 to 4: exceptions, explanation traces, second tax year.
5. Weeks 5 to 9: payroll demo, PDF payslips, VS Code highlighting.
6. Weeks 10 to 14: accountant review, readability study and report.

Path to a product

The first customer is an accounting firm that runs payroll for several small clients and rebuilds spreadsheets each budget season. Sell an annual subscription that includes maintained rule sets for each tax year, with the language and engine open source to build trust. Payroll software vendors are a second market: license the rule sets and engine instead of maintaining their own. Scale by adding jurisdictions and other rule-heavy domains such as provident fund and social security contributions.

Scope warning

Do not build a full payroll system with attendance, banking files and HR records. Do not try to encode the whole tax code; salary income tax for employees is enough. Do not present the output as tax advice; it is a calculation tool that professionals verify.

Learn what you need on Sefism

• Programming roadmap : solid language fundamentals before you design one.
• Programming cheat sheet : types, recursion and data structures you use in the checker.
• Crafting Interpreters : scanning, parsing and tree-walking evaluation step by step.
• Refactoring.Guru: Design Patterns : the interpreter and visitor patterns used in language tooling.
• JSON Schema: Getting Started : validating employee input files before they reach the engine.

Get help with this idea

The key decision here is how small the language can be while still expressing a real budget change. If you want a second opinion on scope, stack or how to evaluate it before you pitch it to your supervisor, bring your draft proposal and we will pressure-test it together. You build it; the guidance is on the decisions.

• Discuss this idea with a mentor
• Send a query to Tauseef
• Book a 1:1 session

New here? Create a free account first.