TaxInsights: Engineering the Scenario-First Tax Platform

Partnership context

TaxInsights is a Maigha–Upsilon partnership project: Maigha builds and operates the engineering platform (monorepo, APIs, formula engine, Template Studio, infra); Upsilon brings domain ownership and go-to-market for the tax vertical. The repo and internal materials still say TaxInsights—that name is a placeholder. A market brand lands before serious marketing; the engineering surface stays under the codename until cutover.

Soft launch: November

We plan a soft launch in November: limited firm cohort, production-shaped traffic, and ops hardening—not a marketing blast.

• Stress scenario create/copy/PDF paths under real firm data
• Validate FTR provisioning + calculation SLOs
• Prove backup/restore and audit trails under partner ops
• Keep the public brand out of the critical path until the soft-launch signal is clean

Serious marketing follows once the product name is locked.

The technical problem

CPA workflows need one coherent system for prep, what-if comparison, prior-year PDF import, firm templates, and advisory. The pre-cutover model encoded that incorrectly in storage and API shape.

Domain mismatch

Requirement	Pre-cutover behavior
First-class Scenario	No TaxScenario row; scenario identity lived in worksheet columnsData
One scenario = one tax year	One “scenario” spanned multiple years via previewYears[] / numberOfYears
Comparison unit	Year sub-columns under a scenario group, not one column per plan
Form storage	Shared global Worksheet / WorksheetRow for all form kinds
Create semantics	Combinable options; partial multi-form state possible on failure

CPAs compare plans (“2025 Base” vs “2025 Amended”). The schema compared years inside a fake scenario.

Adjacent hard problems

• Template drift — firm forms needed versioned releases (bundles → sandboxes → FTR)
• PDF import trust — extraction without verify dumps bad line values into calc
• AI on tax data — raw PII to LLMs fails compliance; unbounded calls fail cost control
• Multi-tenant boundaries — every query path must stay firm-scoped

The technical solution

Stack (production surface)

Layer	Choice
Monorepo	npm workspaces (apps/api, apps/web, packages/*)
API	Node ≥22 · Express 5 · TypeScript · Prisma 6 · PostgreSQL 17
Web	React 19 · Vite 7 · MUI 7
Auth	Firebase JWT on /v1/*; firm RBAC at route, service, and query
Jobs	BullMQ + Redis
Shared calc	@taxpro/formula-engine
PDF	Schema-driven extraction + split-view preview
AI	OpenAI behind Tax Insights (triggers → recommendations → copilot)

Desktop/mobile shells exist in-tree; web + API are the production path for November.

Correct hierarchy

Firm
 └── FirmClient
      └── TaxFile          (filing container; FTR release pinned)
           └── TaxScenario (1..10 per file; scalar taxYear)
                └── Scenario worksheet values (per form kind)
                     rowsData: { rowId → cell record }

• One year per scenario — taxYear on TaxScenario
• Same year allowed across scenarios — e.g. Original vs Amended for 2025
• Atomic create — BLANK | PDF | COPY in one transaction or none
• Values-only storage — legacy global Worksheet retired

Formula engine + Firm Template Releases

Template Studio authors bundles; sandboxes exercise them; publishing produces a Firm Template Release (FTR) per tax year. Scenario create provisions from active FTR defaults, then calculates.

PDF import pipeline

• Upload Form 1040 PDF
• Parse via declarative extraction config
• Split preview: source PDF ↔ extracted lines
• Preparer approve → atomic scenario provision

Tax Insights AI module (layered)

Layer	Responsibility	LLM?
1 Trigger detection	Rule anomalies (balance due, refund, tax increase, withholding drop)	No
2 Recommendations	Contextual tips per trigger; token metering	Yes
3 Copilot	Multi-turn sessions bound to file; 30-day expiry	Yes

Cutover decisions

Rejected	Shipped
Scenario-as-columns in worksheet JSONB	TaxScenario + values-per-form
Multi-year scenario create	Scalar taxYear + N scenarios per file
Shared Worksheet for all forms	Kind-scoped values; FTR provision
LLM-first advisory	Triggers first; then recommendations/copilot
Raw PII to OpenAI	Anonymize → call → meter → audit
Partial multi-form creates	Single DB transaction per create mode

What’s next

• November soft launch — limited cohort; watch create/calc/PDF/AI quotas
• Brand rename — replace TaxInsights placeholder before serious marketing
• Near-term backlog — PDF confidence beyond 1040; e-file after backup SLOs; client portal e-sign

Summary

Problem: Scenario and year were presentation artifacts; templates, PDF, and AI sat outside a coherent multi-tenant model.

Solution: Scenario-first schema and APIs, FTR-driven provision, verifiable PDF import, and a gated AI stack—on a Maigha-built monorepo for the Maigha × Upsilon partnership.

Name: TaxInsights is internal-only until the launch brand ships. Date: soft launch targeted for November.

← Back to Posts