Investment Tax Treatment Classification#

Overview#

Sure assigns a tax_treatment value to every investment and crypto account subtype at the model layer. These classifications drive the investment gains by tax treatment card on the Reports page and the budget/cashflow exclusion logic that keeps retirement contributions out of spending reports.

There are four treatment values 1:

Investment Accounts — Static Subtype Map#

app/models/investment.rb defines SUBTYPES 2 — a frozen hash of 70+ entries keyed by subtype string, each carrying short, long, region, and tax_treatment. Treatment is statically baked into the map, not stored in the database.

The tax_treatment instance method reads directly from the map — unknown/unrecognized subtypes fall back to :taxable.

Regional breakdown 3:

Crypto Accounts — Persisted Enum#

app/models/crypto.rb stores tax_treatment as a database-backed enum 4 with values taxable (default), tax_deferred, and tax_exempt. Unlike Investment, the treatment on a Crypto account is mutable per-record — useful for edge cases like a self-directed IRA holding crypto 5.

Depository — HSA Special Case#

app/models/depository.rb adds a narrow carve-out: only the hsa subtype returns :tax_advantaged 6. This is required because Plaid routes depository.hsa to Depository (not Investment), so without this override, linked HSA cash accounts would be invisible to tax-advantaged filters 7. All other depository subtypes return nil, which the rest of the system treats as taxable.

TaxTreatable Concern — Account-Level API#

app/models/concerns/tax_treatable.rb is included on Account and delegates to the accountable 8:

• tax_treatment — returns the symbol (:taxable, :tax_deferred, etc.) or nil if unsupported
• tax_treatment_label — i18n string via accounts.tax_treatments.* 9
• tax_advantaged? — true for :tax_deferred, :tax_exempt, or :tax_advantaged 10
• taxable? — true for :taxable or nil 11

How Classification Is Used#

1. Investment Gains Report (ReportsController)#

build_gains_by_tax_treatment groups current holdings and sell trades by treatment, computing unrealized and realized gains per bucket. Unrealized gains use today's FX rates; realized gains use entry-date rates 12. This populates the "Gains by Tax Treatment" breakdown on the investment performance report 13.

2. Budget & Cashflow Exclusion (Family#tax_advantaged_account_ids)#

Family#tax_advantaged_account_ids aggregates IDs from all three accountable types and memoizes the result. It is used to exclude tax-advantaged accounts from the transactions breakdown and income statement :

• Investment: joins investments table, selects subtypes whose tax_treatment is tax_deferred, tax_exempt, or tax_advantaged 16
• Crypto: queries the cryptos.tax_treatment column for tax_deferred or tax_exempt 17
• Depository: delegates to tax_advantaged_depository_account_ids (covers HSA) 18

3. UI Display — Region-Ordered Subtype Picker#

Investment.subtypes_grouped_for_select uses CURRENCY_REGION_MAP to surface the user's likely region first (e.g., USD → "us") in account-creation dropdowns. Tax treatment is not shown in the picker but is set implicitly based on the selected subtype.

Related Topics#

• Account Type Architecture — covers the delegated_type polymorphic structure connecting Account to Investment, Crypto, Depository, etc.
• Investment Activity Labels — covers transaction-level classification (trade kinds, activity types).