Financial Dashboard and Analytics
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Financial Dashboard and Analytics system provides a real-time, comprehensive overview of a user's financial health. It aggregates data from multiple accounts to visualize balances, spending patterns, and income trends through interactive charts and Key Performance Indicators (KPIs). The system is designed to automate the insights generation process, helping users understand where their money goes and identify potential savings through AI-powered categorization and visual breakdowns.
The module serves as the central landing page for the application, utilizing Next.js Server Components and Server Actions to fetch and process financial data directly from the PostgreSQL database via the Drizzle ORM. It integrates several specialized visualization components, including Sankey flow diagrams for cash flow and bar charts for category-based spending analysis.
Sources: README.md:5-15, frontend/app/(dashboard)/page.tsx:43-60
Core Architecture and Data Flow
The dashboard follows a unified data fetching pattern where filters (account selection, date ranges, or time horizons) are parsed from URL search parameters and passed to a central server-side data aggregator.
Data Fetching Pipeline
The getDashboardData function acts as the primary orchestrator, executing multiple specialized queries in parallel to populate the dashboard's various sections. It calculates a "canonical window" for dates based on user input or a default 30-day horizon relative to the latest transaction.
Key Data Structures
The dashboard relies on specific interfaces to maintain consistency across the server and client components:
| Interface | Description | Key Fields |
|---|---|---|
DashboardFilters | User-defined criteria for data isolation. | accountIds, dateFrom, dateTo, horizon |
SankeyData | Structures nodes and links for flow charts. | nodes, links |
AssetsOverviewData | Summarizes assets by category and account. | total, categories, currency |
CategoryData | Details for category-specific spending. | id, name, amount, color |
Sources: frontend/lib/actions/dashboard.ts:586-593, frontend/lib/actions/dashboard.ts:544-551, frontend/components/charts/spending-by-category-chart.tsx:10-16
Financial Metrics and KPIs
The dashboard displays four primary KPI cards, known as KpiSparkCards, which include sparkline visualizations to show trends over the selected period.
Savings Rate Calculation
The savings rate is derived by calculating the net difference between period income and period spending. For transactions linked together (e.g., bill splits or reimbursements), the system uses a subquery to calculate the net amount of the group rather than the raw transaction amount.
Sources: frontend/lib/actions/dashboard.ts:153-190, frontend/lib/actions/dashboard.ts:637-640
Balance Aggregation
Total balance is calculated by summing the latest balance record for each active account. This ensures that even if accounts have different synchronization dates, the total reflected is the most recent known sum in the user's functional currency.
Sources: frontend/lib/actions/dashboard.ts:114-138
Analytics Visualizations
Cash Flow Sankey
The Sankey visualization provides a "Conservative" view of cash flow. It maps income sources on the left to expense categories on the right. To ensure the diagram balances, the system generates "synthetic" nodes.
- Savings Node: Created when total income exceeds total expenses.
- Funding Gap Node: Created when total expenses exceed total income.
Note: The flow logic distributes income proportionally across all active expense targets based on the adjusted total expense.
Sources: frontend/lib/dashboard/sankey.ts:49-65, frontend/components/charts/sankey-flow-chart.tsx:148-180
Category Spending Analysis
The spending by category chart identifies the top expense areas. It specifically excludes internal transfers by filtering for categories where categoryType is "expense".
- Net Amount Logic: For linked transactions, only the primary transaction's net group amount is counted if it is negative (debit).
- Uncategorized Handling: Transactions without a
categoryIdorcategorySystemIdare aggregated into a specialized "Uncategorized" bucket.
Sources: frontend/lib/actions/dashboard.ts:326-380, frontend/components/charts/spending-by-category-chart.tsx:93-115
Asset Management
The analytics engine categorizes assets into six distinct keys: cash, investment, crypto, property, vehicle, and other.
Asset Mapping Logic
Data is pulled from three separate tables: accounts, properties, and vehicles.
- Bank Accounts: Mapped based on
accountType(e.g., 'checking' maps to 'cash'). - Properties: Location data is extracted from the address for display as the "institution".
- Vehicles: Make and model are combined for identification.
Sources: frontend/lib/actions/dashboard.ts:413-435, frontend/lib/actions/dashboard.ts:480-515
Summary
The Financial Dashboard and Analytics system provides a robust framework for personal finance monitoring by combining multi-source data aggregation with sophisticated visualization. By utilizing server-side processing for complex calculations like linked-transaction net amounts and Sankey flow balancing, the system maintains high performance while delivering deep insights into user spending behavior, asset distribution, and overall financial sustainability.