Wealth Module
Relevant source files
The following files were used as context for generating this wiki page:
The Wealth Module tracks household assets, including equities, cryptocurrencies, and other investments. It aggregates values from various modules to present a comprehensive net worth view. The module provides live price fetching for shares and crypto, computes cost basis from trade history, and supports document attachments for financial records.
Sources: PRODUCT.md:10-15, GLOSSARY.md:94-102, src/app/(app)/wealth/page.tsx:32-35
Architecture and Data Flow
The Wealth module operates as an opt-in component within the Hearth ecosystem. It relies on a centralized pricing system that fetches data from Yahoo Finance for equities and CoinGecko for cryptocurrencies. Prices are cached locally and refreshed every 15 minutes to ensure accuracy without excessive API calls.
Sources: PRODUCT.md:57-59, tests/unit/wealth-pricing.test.ts:46-52
Net Worth Calculation Flow
The following diagram illustrates how the system aggregates data from multiple modules to calculate the total household net worth.
The system calculates net worth by summing investments (Shares/Crypto), Property valuations, and Inventory item values.
Sources: src/app/(app)/wealth/page.tsx:32-45, ios-shell/www/app.js:527-535
Key Components
Portfolio Management
The module organizes assets into Portfolios. Each portfolio contains one or more Holdings. A holding represents a specific asset (e.g., AAPL or BTC). The system does not store the current cost basis; instead, it recomputes it using trade history (First-In-First-Out or Average Cost methods).
Sources: PRODUCT.md:57-59, GLOSSARY.md:94-102, ios-shell/www/app.js:1450-1460
Pricing Engine
The engine routes ticker lookups to specific providers based on the asset class and exchange metadata.
| Asset Class | Exchange | Provider |
|---|---|---|
| CRYPTO | Null / Blank | CoinGecko |
| SHARE / ETF | Any | Yahoo Finance |
| Any | "CRYPTO" | CoinGecko |
Sources: tests/unit/wealth-pricing.test.ts:54-68, ios-shell/www/app.js:1415-1425
Data Models
The Wealth module uses several interconnected entities in the database.
The relationship between portfolios, holdings, trades, and associated documents.
Sources: ios-shell/www/app.js:148-185, e2e/specs/20-wealth-module.spec.ts:88-100
External Tools and Integrations
AI Assistant Tools
The Wealth module exposes tools to the optional AI assistant, allowing users to query their net worth through natural language.
net_worth: Returns the household's total value, including share/crypto portfolio value, property value, and inventory value, along with per-holding gain/loss.
Sources: src/lib/chat/tools.ts:192-200
CSV Import
Users can import trade history from external brokers. The module supports several predefined formats:
- CommSec: Detects "Trade Date" and "Settlement Date" headers.
- SelfWealth: Detects "Transaction Date" and "Market" headers.
- Stake: Detects "order_type" headers.
- Generic: Requires standard columns like Date, Ticker, Type, Units, and Price.
Sources: ios-shell/www/app.js:1340-1365, e2e/specs/22-import-extraction.spec.ts:88-105
Net Worth Components
The net worth view categorizes assets into three primary parts, provided the relevant modules are enabled:
- Shares, ETFs and crypto: Derived from Wealth module holdings and trade history.
- Property: Derived from the Home module's property valuations.
- Items: Derived from the Inventory module's item purchase prices.
If an asset lacks a live price feed or an exchange rate for the household's default currency, it is excluded from the total and listed in an "Exclusions" note.
Sources: src/app/(app)/wealth/page.tsx:64-75, tests/unit/wealth-pricing.test.ts:375-385
Conclusion
The Wealth Module serves as the financial aggregate for the Hearth platform. By combining live market data for liquid assets with user-provided valuations for property and inventory, it offers a real-time snapshot of household net worth. Its architecture ensures privacy by recomputing cost basis locally and allowing for self-hosted price fetching.