Problem statement
Design the object model and core APIs for a progressive tax calculator that computes tax owed from taxable income across a set of marginal brackets, for several jurisdictions, filing statuses, and tax years.
Operating context. A jurisdiction defines, per filing status and tax year, an ordered set of brackets (a lower bound and a rate). Tax is the sum over brackets of the income falling in each band times that band's rate. The calculator applies a standard (or itemized) deduction to gross income before bracket computation, and flat or percentage credits after, flooring liability at zero. It also reports both the marginal rate and the effective rate. The computation is pure: given the same inputs it always returns the same result. Multiple calculators can be composed (for example a federal calculator and a local one).
Out of scope. Real tax-law edge cases and exotic deductions, e-filing or form generation, a persistence layer, currency conversion, and any UI.
What to produce. The class hierarchy (Jurisdiction, BracketTable, Bracket, FilingStatus, Deduction, Credit, TaxCalculator), the public APIs each exposes, the marginal-bracket computation, and how a new tax year or jurisdiction is added as data rather than code. Be explicit about how a bracket table is validated as ordered and non-overlapping at construction, and how multiple calculators compose without editing any single calculator.
Functional requirements
- Compute total tax for a given taxable income using a jurisdiction's ordered marginal brackets.
- Select the correct bracket table by filing status and tax year.
- Apply a standard or itemized deduction to gross income before bracket computation.
- Apply flat or percentage credits after tax is computed, flooring the final liability at zero.
- Report both the marginal rate and the effective rate for a computed result.
Non-functional requirements
- Tax computation is O(number of brackets) and pure — identical inputs always yield identical output, with no shared mutable state.
- Bracket tables, deductions, and credits are pluggable data or strategies — a new jurisdiction or tax year is data, not a change to the calculator.
- Monetary amounts use exact decimal or minor-unit arithmetic with an explicit rounding rule per band.
- A bracket table is validated as ordered and non-overlapping at construction; an ill-formed table is rejected before any computation.
- The calculator is unit-testable in isolation with no I/O and no wall clock.
- Composing calculators (for example federal then local) needs no change to a single calculator's class.
Topics
- System Design LLD
- Oop Solid
- Patterns Strategy
- Patterns Composite
- Finance Tax