# SDK, HTTP API and calculators service boundary [#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 [#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 [#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 [#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.

## Related concepts [#related-concepts]

* [API overview](/api/overview)
* [Plain SDK](/sdk/plain-sdk)
* [Effect SDK](/sdk/effect-sdk)
* [API and SDK architecture](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/api-and-sdk.md)