SDK, HTTP API and calculators service boundary

TaxKit has one calculator boundary with multiple caller surfaces. The SDK is the primary in-process surface. HTTP is a transport over that same calculator path.

When this matters

Use this model when deciding where code should live. Tax logic belongs in rules and calculators, not in HTTP handlers, browser clients or docs examples.

How it works

ts
Production: SDK and HTTP boundary

Plain TypeScript caller
  -> TaxKit.calculate / TaxKit.safe.calculate / au.incomeTax.annual
    -> @taxkit/sdk/effect calculateReportRequest
      -> @taxkit/sdk/effect calculateRunRequest
        -> PublicCalculatorService.calculate
          -> CalculationEngine

HTTP caller
  -> @taxkit/api-http route contract
    -> CalculatorApiHandlerLive
      -> PublicCalculatorService.calculate
        -> CalculationEngine

The HTTP calculate route calls PublicCalculatorService.calculate directly. The SDK helpers call the same service. HTTP does not depend on the SDK helpers.

Boundary rules

  • Use the SDK when TypeScript can run in-process.
  • Use HTTP when the caller needs transport or OpenAPI.
  • Keep endpoint field detail in generated OpenAPI.
  • Keep canonical facts, reports and CalculatorServiceError in the owning calculator packages.

Read this page as Markdown