Orchard Tax Architecture
How the docs app, web app, extraction layer, and tax engine fit together.
System map
Orchard Tax is split on purpose:
| Surface | Job |
|---|---|
apps/docs | The wiki, runbooks, and product-facing knowledge base. |
apps/web | The Prepare & Review workspace and operational UI. |
packages/extraction | Document classification and field extraction. |
packages/tax-engine | Deterministic federal math, rule registry, and diagnostics. |
Boundaries that matter
- The engine owns tax math. It accepts verified, typed inputs and returns line
values with
sourcesandcites. - The extractor classifies and extracts documents; it does not decide tax treatment.
- The docs app explains the system; it does not become a second source of truth for rules.
- Production data, file storage, and auth belong in the hosted alpha runbook, not in the engine package.
Data flow
- A document enters
apps/webthrough upload or seed data. - Extraction produces candidate fields, or the preparer fills them manually.
- Verification promotes the fields to engine inputs.
computeDraftreturns line values, source refs, cites, and diagnostics.- The review screen shows deltas, overrides, and a snapshot action.
Core contracts
| Contract | Why it matters |
|---|---|
| Money is integer cents | Prevents rounding drift inside calculators and database rows. |
Every constant has { value, cite } | Keeps tax-year changes auditable. |
| Every line carries sources and cites | Powers click-to-source review. |
| Diagnostics are deterministic | Warnings are repeatable and testable. |
| No hidden math in docs or UI | Keeps tax logic centralized in packages/tax-engine. |