| status | canonical |
|---|---|
| last_reviewed | 2026-06-25 |
| source_of_truth | root-docs |
| confidence | medium |
WhatTax is the public monorepo for the open-source tax engine, API, SDK and documentation site.
The repo is early, but the main public integration surfaces now exist. The
implemented surface is a standalone Bun API app, a TanStack Start web scaffold
that calls that API, a Fumadocs-backed docs app, an Effect HTTP API package
with health, generated docs, metadata and public calculation endpoints, a
reusable calculator orchestration package, deterministic core engine
primitives, Australian pay, income-tax and STSL rule packages, a private
TypeScript SDK package, private @whattax/docs-content and
@whattax/docs-fumadocs packages, shared testing helpers and shared TypeScript
config. The SDK is implemented for local and downstream validation, but it is
not published yet.
- apps/api: standalone Bun process that owns API
startup, listening config and Effect runtime teardown for
/api/*. - apps/docs: TanStack Start public documentation app that renders MDX through package-owned docs content and reusable Fumadocs helpers.
- apps/web: TanStack Start app that loads health data
from
apps/apithrough server/client runtime boundaries. - packages/api/http: Effect HTTP API contract, generated docs, public calculator routes, thin handler adapters, server handler exports and browser-safe client exports.
- packages/calculators: reusable public calculator orchestration package for catalog metadata, graph construction, calculation dispatch and schema-guided expected error shaping.
- packages/sdk/typescript: private TypeScript SDK package with plain, safe-result, Effect and AU entrypoints.
- packages/docs-content: private source-only content package for docs frontmatter, navigation, validation, generated source access and the docs content service.
- packages/docs-fumadocs: private reusable package for generic Fumadocs configuration, source adapters and MDX render primitives.
- packages/core: deterministic engine primitives, schema-backed facts, rule descriptors, graph validation, trace and ledger contracts and calculation engine service.
packages/rules/au/*: implemented Australian pay, annual income-tax and STSL rule packages with Effect rule layers, official parameter services, calculators and golden tests.- packages/testing: shared test helpers for workspace packages.
- packages/tsconfig: shared TypeScript config presets.
- packages/scripts and packages/ui: documented planned ownership areas without package manifests or runtime code yet.
The architecture docs describe the intended package families for the tax engine: core primitives and facts, domain models, rule packs, API clients, SDKs, docs tooling and supporting app shells. Treat those as planned architecture unless a matching package root and package README say otherwise.
Start with:
bun install
bun run --filter=api dev
bun run --filter=web dev
bun run --filter=docs dev
bun run verification
bun run changeset
bun run version-repobun run --filter=api dev serves the API through portless at
https://api.whattax.localhost. bun run --filter=web dev injects that
portless URL into WHATTAX_API_BASE_URL and VITE_WHATTAX_API_BASE_URL before
serving the web app at https://whattax.localhost. bun run --filter=docs dev
serves the public docs app at https://docs.whattax.localhost. bun run verification is the baseline verification command for documentation, package
wiring and scaffold changes.
Package-facing changes must include a Changeset. Use bun run changeset during
implementation to record the user-facing package impact, and use
bun run version-repo only when intentionally consuming pending Changesets into
fixed release-train package versions and changelogs.
- AGENTS.md: short atlas for agents and task routing.
- CLAUDE.md: Claude-compatible pointer to the canonical root operating rules.
- CHANGELOG.md: root release-train changelog. Package-level changelogs live beside each implemented package, and public app/API changelogs live beside the owning app.
- Engineering conventions start with Effect services, Configuration, Package ownership and Code patterns.
- Product specs: current implementation intent and task lists.
- Exec plans: live and completed rollout plans.
- Design docs: documentation and design conventions.
- Documentation audit: current docs inventory, README coverage, missing docs and migration priorities.
- References: external or imported reference material.
docs/repo-status-outline.html is a local, static status snapshot for a quick visual overview. It is useful for review in a browser, but it is not canonical; refresh it when repo structure or implemented surfaces materially change.
Open it directly at:
file:///Users/cooper/Projects/whattax/docs/repo-status-outline.html
apps/apiis the API runtime owner. It creates one process-lifetimeManagedRuntime, servespackages/api/httpthrough Bun and disposes scoped resources on shutdown.apps/docsis the docs runtime owner. It consumes@whattax/docs-contentand@whattax/docs-fumadocsrather than owning canonical frontmatter, navigation or reusable Fumadocs internals.apps/web/src/lib/runtime.server.tsandapps/web/src/lib/runtime.client.tsown the web SSR and browser client runtimes. They call the standalone API over HTTP.@whattax/api-http/clientand@whattax/api-http/client/liveare browser-safe.@whattax/api-http/client/server,@whattax/api-http/serverand handler exports are server-only and should stay out ofapps/web.