Tax pillar

Summary

Tax is the deterministic engine — a single AY-keyed route with a state machine (locked → empty → review → (ca-invited → with-ca → filed) | past-ay) that computes a regime pick, a claimed-vs-available donut, an old-vs-new bars comparison, a salary-to-refund waterfall, a 5-AY tax journey line, and a 19-question return checklist. It never files. Filing happens via a CA (Invite your own or Hire a CA) or, for closed AYs, becomes a read-only archive with escapes only for notices/revisions/audits.

Why it matters

Tax is the pillar the whole product monetises around. If the state machine, the checklist, or the CA-hand-off dichotomy drift from the wireframe, an LLM will hallucinate a "submit return" button or misremember the tax-journey chart as YoY bars. Both errors compound: one exposes us to legal risk we've explicitly ruled out (2026-07-26-self-file-permanently-out-of-scope), the other misrepresents the whole point of the pillar (five-year trajectory, not year-over-year delta).

Implications

• AY pivot is Tax-only. Current AY is editable/interactive; past AYs are read-only archives. AY selector exists only on this pillar — Expense and Portfolio don't get one. See 2026-06-11-ay-selector-tax-only.

• One route, data-driven states. /tax renders one of locked · empty · review · ca-invited · with-ca · filed · past-ay (+ family variants). State is a function of filing_state, workspace scope, and current AY.

• Review is six canonical widgets. Main column, top to bottom:

  1. "What you claimed" donut (HRA · §80C · Std ded · §80D) with "You claimed ₹X of ₹Y available" callout, paired side by side with:
  2. "Old vs new regime · new saves more" bars — winner marked New regime ✓ (chosen).
  3. "From your salary to your refund" waterfall (gross → exemptions → 80C/80D → taxable → slab tax → cess → TDS → refund), paired side by side with:
  4. "Return checklist · 19 questions" — interactive Quick Check that drives completeness.
  5. "What you missed this year" callout cards (deduction / regime / documentation misses) → link to Hire-CA consultation.

  Sidebar (not part of the main column flow): AY pivot row + 5-AY "Your tax journey" line chart (income + tax, absolute — not YoY), then the Pick-your-CA-path card. The journey chart lives in the sidebar by design — .context/designs/web/tax/tax.html explicitly annotates it "belongs in aside". See 2026-08-03-correct-widget-order-entity-drift.

• Regime is computed and marked, never user-set. The engine picks the winner; the UI shows both and marks ✓ chosen. The user's CA can override before filing.

• Review-only. Tax computes and cites; it never files. Corollary of read-only-review and 2026-07-26-self-file-permanently-out-of-scope.

• Hand-off-to-CA dichotomy — the aside "Pick your path · How would you like to file?" offers exactly two paths: (a) Invite your own CA (Free — links tax-invite-ca); (b) Hire a CA (From ₹599 — links ca-marketplace-browse). The user shares their Tax Review with the CA directly — no separate handoff-packet PDF (removed 2026-07-28 · 2026-07-28-remove-ca-handoff-surface). Marketplace CA keeps 90%, Chitragupt keeps 10%. See ask-ca-stream, marketplace-economics.

• Filed state is an archive with a rating. Chat drawer becomes read-only; a star-rating widget replaces further messaging. filing_state ∈ {not_filed, itr_v_acknowledged} per 2026-07-26-self-file-permanently-out-of-scope.

• Past-AY is read-only with narrow escapes. No filing UI on a closed AY. Notices (§143(1) etc.), revisions, and audits are the only reasons to open help — routed to the CA who filed, or the marketplace. Past AYs are always free (2026-05-30-past-ay-free).

• Family variant adds household optimisation moves. Per-member refund tiles, per-member regime chooser ("2 of 3 New"), and cross-PAN reassignments (e.g. "Move Ravi's mediclaim → your §80D (₹7,800 saved)"). Tax filings themselves stay per-PAN — Family stacks, doesn't merge. See family-workspace.

• Ask-CA entry lives inside Tax, not as a floating pill anywhere else. See ask-ca-stream and four-pillars.

Related

• four-pillars — Tax is the deterministic engine of the four
• read-only-review — the parent invariant (Tax never files)
• ask-ca-stream — CA marketplace + engagement lives inside Tax
• freemium-per-ay — engine unlock is one-time per AY
• what-we-sell — right ITR + right regime + forward actions
• family-workspace — reshapes review with per-member tiles + reassignments
• pillar-tax — entity: canonical chart + widget keys
• pillar-dashboard — Tax journey chart shared with dashboard
• 2026-07-26-self-file-permanently-out-of-scope — the platform never files; filing goes through a CA
• 2026-07-28-remove-ca-handoff-surface — CA-handoff packet PDF removed; Tax Review is the shared artefact
• tier-self · tier-ai-self · tier-pro-family — unlock gates
• ca-category-itr-filing · ca-category-consultation · ca-category-notice-defence — CA service categories the review routes to
• marketplace-economics — 90/10 split on Hire-a-CA path
• 2026-06-11-ay-selector-tax-only — AY pivot is Tax-only
• 2026-05-30-past-ay-free — past AYs always free
• 2026-06-01-v1-inbox-tax-only — V1 launch gate on Inbox + Tax
• tax-locked · tax-empty · tax-review · tax-ca-invited · tax-with-ca · tax-filed · tax-past-ay · tax-family-stacked · tax-family-locked · tax-invite-ca · tax-concern
• copy-strings — Tax pillar CTA + callout copy

Sources

• .context/designs/web/tax/tax-empty.html
• .context/designs/web/tax/tax.html
• .context/designs/web/tax/filed.html
• .context/designs/web/tax/with-ca.html
• .context/designs/web/tax/ca-invited.html
• .context/designs/web/tax/past-ay.html
• .context/designs/web/tax/tax-locked.html
• .context/designs/web/tax/family.html
• .context/designs/web/tax/family-locked.html
• .context/designs/web/tax/invite-ca.html
• .context/designs/web/tax/concern.html