spring-tax-calc-service

A Java 17 and Spring Boot service for financial calculation and regulatory reporting, built the way an enterprise platform has to be built: rules that change without code changes, results that are auditable, and an architecture that survives a decade of amendments.

Financial and tax-compliance platforms fail in a predictable way. Calculation rules are hard-coded, so every rate change or new jurisdiction means a release. Results can't be explained after the fact, so nobody can answer why a figure came out the way it did. Report formats are welded to the domain model, so a new schema version rewrites half the system.

spring-tax-calc-service is a reference implementation that avoids all three. It takes financial transactions, applies a versioned, configuration-driven rule set to compute liabilities, keeps a full audit trail of how every figure was derived, and emits both a financial report and a structured XML compliance file validated against its schema.

Scope note: a generic, jurisdiction-neutral reference implementation for calculation and regulatory reporting. It demonstrates the architecture and the engineering practice, not any one country's filing product.

Architecture

Hexagonal (ports and adapters), so the domain has no idea what a database or an XML schema is.

flowchart LR
    API[REST API\nSpring Web] --> APP[Application services]
    APP --> DOM[Domain core\ncalculation engine]
    DOM --> RULES[(Versioned rule sets\nconfiguration)]
    APP --> REPO[(PostgreSQL\nJPA adapter)]
    APP --> RPT[Report adapter\nfinancial summary]
    APP --> XML[Compliance adapter\nXML + XSD validation]
    DOM --> AUDIT[Audit trail\nper-figure derivation]

• Domain core. Pure Java 17, no framework annotations: money as BigDecimal with explicit rounding, immutable value objects, records and sealed types for the transaction model.
• Calculation engine. Rules are data, not code. A rule set is versioned and selected by effective date, so a rate change is configuration and historical periods stay reproducible. Strategy and chain-of-responsibility keep each rule small and independently testable.
• Audit trail. Every computed figure records the rules applied, the inputs, and the intermediate values, so any number can be explained line by line.
• Reporting adapters. One produce