Net Worth Balance Sheet#

The balance sheet module computes a family's net worth — assets minus liabilities — both as a current snapshot and as a monthly time series for charting. It lives in the BalanceSheet namespace and is distinct from Financial Reporting (income statement / Sankey) and from the per-account Balance History system (which produces the individual Balance rows consumed here).

Entry Point: BalanceSheet#

BalanceSheet is the top-level model. It exposes:

• assets / liabilities — current-snapshot ClassificationGroup objects built from AccountTotals
• net_worth — assets.total - liabilities.total
• net_worth_series(period:) — delegates to NetWorthSeriesBuilder for the simple dashboard time series

Both BalanceSheet and its sub-builders accept an optional user: argument so shared-account families can scope results to the accounts visible to a specific user.

Account Scoping: HistoricalAccountScope#

BalanceSheet::HistoricalAccountScope defines which accounts feed the balance sheet:

family.accounts.historical.included_in_reports[.included_in_finances_for(user)]

• historical — includes both active and disabled accounts (i.e., VISIBLE_STATUSES + ["disabled"]), so closed accounts still appear in historical charts 1
• included_in_reports — excludes accounts where the user has set exclude_from_reports: true 1
• included_in_finances_for(user) — applied only when a user is passed; filters to accounts shared with or owned by that user

Monthly Chart: NetWorthBreakdownSeriesBuilder#

BalanceSheet::NetWorthBreakdownSeriesBuilder is the primary chart-data builder. It produces a monthly series (INTERVAL = "1 month", 2) with per-account-group breakdown for chart tooltips.

breakdown_series(period:) pipeline 3:

1. Calls Balance::ChartSeriesBuilder#balance_series for all historical accounts combined — this gives the aggregate net worth line.
2. Calls Balance::ChartSeriesBuilder#balance_series once per (classification, accountable_type) group — one series per account type (e.g., Depository assets, Loan liabilities).
3. Groups are sorted: assets before liabilities, then in canonical Accountable::TYPES order 4.
4. Groups with all-zero values are dropped 5.
5. Each monthly point is assembled into a breakdown_value hash 6 containing:
   • value — aggregate net worth at that date
   • trend — month-over-month change (current vs. previous point's value)
   • assets / liabilities — classification subtotals
   • groups — per-account-type name, color, classification, and value

Disabled accounts are handled via account_active_until_dates: a disabled account's Balance data is capped at disabled_at - 1 day so it doesn't contribute a stale zero balance to later months 7.

Caching: results are memoized in Rails cache keyed on (family, user, period, shares_version) with invalidate_on_data_updates: true 8.

Underlying SQL: Balance::ChartSeriesBuilder#

NetWorthBreakdownSeriesBuilder delegates all SQL to Balance::ChartSeriesBuilder 9, passing:

• account_ids — the filtered account set
• currency — family currency for FX conversion
• period / interval — date range and monthly bucketing
• favorable_direction — "up" for assets, "down" for liabilities (controls trend coloring)

ChartSeriesBuilder executes a lateral-join SQL query against the balances table with dual-direction FX conversion 10, reading end_balance for each monthly sample date. It reads from pre-computed Balance rows; it does not recalculate balances on the fly.

Controller Integration#

ReportsController constructs the builder and feeds the result into the net_worth report payload:

breakdown_series = BalanceSheet::NetWorthBreakdownSeriesBuilder
  .new(Current.family, user: Current.user)
  .breakdown_series(period: @period)

The payload also includes current-snapshot asset_groups and liability_groups (from BalanceSheet#assets/liabilities), and the overall trend.

Key Source Files#

See also:

• Account Type Architecture — asset vs. liability classification, Accountable::TYPES order
• Balance History System — how Balance rows are produced (the upstream data source)
• Multi-Currency Exchange Rates — FX handling in ChartSeriesBuilder