Active chapterCase study
Case study / 02
A standalone REST microservice for multi-jurisdiction tax calculation and commission computation. Handles US sales-tax stacking, EU VAT, UK three-tier VAT, and Canadian GST/HST - all backed by decimal.js for zero floating-point rounding errors.
01 / System behavior
A project-specific technical mechanism based on the recorded architecture and implementation context.
JurisLogic is a plug-and-play headless microservice designed to be consumed by any frontend, mobile app, or backend service with no coupling or lock-in. Every monetary operation flows through immutable Money value objects backed by decimal.js with banker's rounding (ROUND_HALF_UP), guaranteeing penny-perfect accuracy across all jurisdictions.
The service covers four jurisdiction families: US (state + county + city stacking), EU (per-country standard and reduced rates), UK (standard 20%, reduced 5%, zero-rated), and Canada (HST provinces vs GST+PST). Each jurisdiction is implemented as a concrete Strategy, resolved by a TaxStrategyFactory - adding a new jurisdiction means writing one class and registering it, with zero changes to existing code.
03 / Architecture record
A structured reading of the architecture recorded with this project.
The codebase follows a strict Hexagonal (Ports & Adapters) Architecture with three layers:
• Domain Layer (src/domain/) - Pure TypeScript classes with zero framework imports. Contains Value Objects (Money, TaxRate, JurisdictionCode), Entities (Transaction aggregate root, TaxRule, Commission), and Strategies (ITaxStrategy interface with US, EU, UK, CA implementations plus the TaxRulePipeline chain).
• Application Layer (src/application/) - Use case orchestrators (CalculateTax, CalculateCommission, ProcessBatchTransaction) that build domain objects from DTOs, check cache, resolve strategies, run pipelines, and write audit logs. Depends entirely on abstract port interfaces - ICachePort, IQueuePort, IAuditLogPort, ITaxRuleRepository.
• Infrastructure Layer (src/infrastructure/) - Concrete adapters: PrismaService for PostgreSQL, RedisCacheAdapter, BullMQ queue adapter, and Prisma audit log adapter. The NestJS InfrastructureModule is the single composition root that wires adapters to ports.
Cross-cutting concerns - exemptions, surcharges, minimum tax floors - are handled by a Chain of Responsibility pipeline with a fluent builder API. The application layer orchestrates use cases (single tax, commission, batch) through abstract port interfaces, keeping business logic framework-free. Infrastructure adapters wire Redis caching, BullMQ async batch processing, and PostgreSQL audit logging.
The commission system supports three models: flat-fee, percentage, and tiered (progressive brackets similar to income tax), all computed with the same decimal precision guarantees.
05 / Selected highlights
The decisions and workflows that carry the most explanatory weight.
06 / Supported metrics
TypeScript, NestJS, Prisma, PostgreSQL, Redis, BullMQ, decimal.js, Docker, Swagger/OpenAPI, Jest
View source repository• Interface Layer (src/interfaces/rest/) - NestJS controllers with Swagger decorators and DTOs. Thin layer that delegates to use cases.
Design Patterns: Strategy, Factory, Chain of Responsibility, Decorator, Builder, Value Object, Repository, Ports & Adapters.