Financial Reporting#

Sure's financial reporting pipeline centers on two components: IncomeStatement — the Ruby model that aggregates transactions by category into income and expense totals — and the Cashflow Sankey chart — a D3-based dashboard widget that visualizes those flows. Everything from budget analytics, trends reports, and financial insights draws from IncomeStatement.

Key source files:

IncomeStatement Model#

IncomeStatement is instantiated per family (Current.family.income_statement) and optionally scoped to a single user's accounts. Its public API returns value objects rather than ActiveRecord relations:

• expense_totals(period:) / income_totals(period:) — return a PeriodTotal struct with a total and category_totals array, one entry per category.
• net_category_totals(period:) — computes a per-category net (expense − income) and returns a NetCategoryTotals with separate net_expense_categories and net_income_categories lists. This is what drives the Sankey and outflows donut.
• median_expense / median_income — historical medians used by financial insights (e.g., cash-flow warning, spending anomaly generators).

Results are memoized per period within a single instance and the underlying SQL results are Rails-cached against family.entries_cache_version and accounts.maximum(:updated_at) 1.

Pending transactions are always excluded 2 — family.transactions.visible.excluding_pending is the default scope.

Category Breakdown#

build_period_total maps each persisted category plus the two synthetic categories — Uncategorized and Other Investments — into a CategoryTotal with a weight (percentage of classification total). Parent categories aggregate their children's totals 3.

SQL Layer: IncomeStatement::Totals#

Totals#call runs a single SQL query and returns TotalsRow structs. The query routes through two paths 4:

• combined_query_sql (default, include_trades: true): UNION ALL of transactions_subquery_sql and trades_subquery_sql 5.
• transactions_only_query_sql: legacy path for backward-compatibility.

In practice, trades_subquery_sql always returns an empty result set (WHERE false) because trades represent portfolio rebalancing with no cash-flow significance 6.

Transaction Filtering (what gets excluded)#

Four layers of exclusion are applied inside the SQL WHERE clause 7:

1. BUDGET_EXCLUDED_KINDS — funds_movement, one_time, cc_payment transactions are dropped 8. loan_payment and investment_contribution pass through and are forced to expense classification 9.
2. INTERNAL_MOVEMENT_LABELS — investment transactions with investment_activity_label IN ('Transfer', 'Sweep In', 'Sweep Out', 'Exchange') are excluded 10. These are brokerage cash-management events with no budgeting significance.
3. Tax-advantaged accounts — accounts with subtypes like 401k, IRA, HSA are excluded via exclude_tax_advantaged_sql. See Account Reporting Controls for details.
4. exclude_from_reports flag — accounts with this flag set are filtered at the SQL level 11.

Classification Logic#

Amounts are classified as income when ae.amount < 0 (credits) and expense otherwise, with the special override that investment_contribution and loan_payment are always expense 12. All totals are converted to the family's currency via a join on exchange_rates 13.

Cashflow Sankey Chart#

The Sankey is built and rendered as follows:

1. Data assembly (PagesController#build_cashflow_sankey_data) 14

All three IncomeStatement totals are fetched in PagesController#dashboard 15 and passed to build_cashflow_sankey_data. The output is a { nodes: [], links: [], currency_symbol: } hash.

The central node is "Cash Flow" 16. Income categories flow into it; expense categories flow out of it. A Surplus node is appended when total_income > total_expense 17.

Node/link construction uses net category values from net_category_totals — each category's total is expense − income, so categories that appear on both sides of the ledger are correctly netted 18. Subcategory netting is handled by build_net_subcategories, which groups by parent_id and assigns a net_direction per subcategory. process_net_category_nodes then places subcategories on the same side as their parent (or the opposite side if their net flips direction).

2. View layer

The _cashflow_sankey partial checks for non-empty sankey_data[:links]; if empty, it renders an empty-state with a "Add transaction" link 19. When data is present, it renders the chart partial and also mounts a full-screen expandable dialog at #cashflow-expanded-dialog 20.

The _cashflow_sankey_chart partial mounts the sankey-chart Stimulus controller and passes data, currencySymbol, startDate, and endDate as Stimulus values. The zoom-out button is hidden by default and surfaced by the controller on drill-down 21.

3. sankey_chart_controller.js 22

A ~631-line D3 Stimulus controller that handles layout calculation, gradient-filled link rendering, label overlap prevention, zoom/drill-down, and interactive hover tooltips. Clicking a category node drills into its subcategories. Node colors use the category's stored color or Category::UNCATEGORIZED_COLOR as fallback 23.

Dashboard layout: the cashflow_sankey section is col_span: "full", non-growing, with a 384px min-height. Users can toggle between single/full column width 24. The section is visible only when @accounts.any? 25.

Downstream Consumers#

IncomeStatement is used beyond the dashboard:

• Trends & Insights report — month-over-month income/expense/savings table and summary cards. See app/views/reports/_trends_insights.html.erb 26.
• Financial Insights generators — SavingsRateChangeGenerator, CashFlowWarningGenerator, and SpendingAnomalyGenerator all pull from IncomeStatement#income_totals, expense_totals, median_expense, and category_totals 26.
• Outflows donut chart — built by build_outflows_donut_data from the same net_category_totals result as the Sankey.
• Reports controller — ReportsController#build_transactions_breakdown uses Account.included_in_reports but does not apply the tax-advantaged exclusion, creating a known inconsistency vs. IncomeStatement::Totals 27.