# luodi-nate/financial-management architecture

> Architecture diagram of the GitHub repository luodi-nate/financial-management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luodi-nate/financial-management
- Repository: https://github.com/luodi-nate/financial-management

## Overview

Family Ledger is a self-hosted household-finance application centered on monthly or weekly snapshots rather than daily bookkeeping. Members record account balances and cash flows; the application stores period data and turns it into household net-worth, allocation, and investment-return views. Documented branches add holdings valuation and imports, analysis and checkups, goals, expense analysis, and broker sync. The map follows the documented product workflow and sampled core modules; unsampled implementation details are represented only where the README describes the capability.

Main entry points: [`src/main/java/com/family/finance/web/entry/EntryController.java`](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/entry/EntryController.java) (Monthly Entry), [`src/main/java/com/family/finance/factview/FactViewService.java`](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/factview/FactViewService.java) (Fact Views), [`src/main/java/com/family/finance/repository/AccountMapper.java`](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/AccountMapper.java) (Accounts), [`src/main/java/com/family/finance/repository/PeriodMapper.java`](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/PeriodMapper.java) (Reporting Periods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Household Capture"]
  node_members["Family Members<br/>[Member.java]"]
  node_periods["Reporting Periods<br/>[PeriodMapper.java]"]
  node_accounts["Accounts<br/>[AccountMapper.java]"]
  node_entry["Monthly Entry"]
  node_snapshots[("Balance Snapshots")]
end

subgraph group_portfolio["Portfolio Data"]
  node_holdings["Holdings Import"]
  node_valuation["Holdings Valuation"]
  node_broker["Broker Sync"]
  node_prices[("Price Snapshots")]
end

subgraph group_analytics["Financial Analysis"]
  node_facts["Fact Slice<br/>[FactSlice.java]"]
  node_factservice["Fact Views"]
  node_dashboard["Dashboard"]
  node_reports["Reports"]
  node_lens["Asset Lens"]
  node_pivot["Pivot Engine<br/>[PivotEngine.java]"]
  node_expenses["Expense Analysis"]
end

subgraph group_advice["Guidance"]
  node_checkup["Asset Checkup"]
  node_llm["AI Interpretation<br/>[LlmRouter.java]"]
  node_goals["Financial Goals<br/>[GoalService.java]"]
  node_review["Period Review"]
end

subgraph group_platform["Application Core"]
  node_database[("MySQL")]
end

node_family(("Household Member"))
node_external(("Market Data Services"))
node_llmservice(("LLM Provider"))

node_family -->|"records balances"| node_entry
node_entry -->|"files by period"| node_periods
node_entry -->|"enters account data"| node_accounts
node_entry -->|"saves snapshots"| node_snapshots
node_members -->|"submits asynchronously"| node_periods
node_holdings -->|"updates positions"| node_accounts
node_broker -.->|"syncs holdings"| node_prices
node_external -->|"provides quotes"| node_valuation
node_valuation -->|"reads quotes"| node_prices
node_accounts -->|"reads and writes"| node_database
node_periods -->|"reads and writes"| node_database
node_snapshots -.->|"persists balances"| node_database
node_entry -->|"feeds reporting data"| node_facts
node_facts -->|"supports calculations"| node_factservice
node_factservice -.->|"supplies KPIs"| node_dashboard
node_factservice -.->|"supplies metrics"| node_reports
node_factservice -->|"supplies portfolio facts"| node_lens
node_lens -->|"queries pivots"| node_pivot
node_expenses -->|"queries expenses"| node_database
node_checkup -->|"requests interpretation"| node_llm
node_llm -->|"sends analysis"| node_llmservice
node_checkup -.->|"assesses allocation"| node_accounts
node_goals -->|"uses household metrics"| node_factservice
node_review -->|"requests insights"| node_llm

click node_members "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/domain/member/Member.java"
click node_periods "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/PeriodMapper.java"
click node_accounts "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/AccountMapper.java"
click node_entry "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/entry/EntryController.java"
click node_snapshots "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/SnapshotMapper.java"
click node_holdings "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/holdingimport/HoldingImportService.java"
click node_valuation "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/stock/AccountValuationService.java"
click node_broker "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/broker/BrokerSyncService.java"
click node_prices "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/StockHoldingMapper.java"
click node_facts "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/factview/FactSlice.java"
click node_factservice "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/factview/FactViewService.java"
click node_dashboard "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/dashboard/DashboardController.java"
click node_reports "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/report/ReportsController.java"
click node_lens "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/lens/LensQueryService.java"
click node_pivot "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/calc/lens/PivotEngine.java"
click node_expenses "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/expense/ExpenseCatQueryService.java"
click node_checkup "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/checkup/FamilyDiagnose.java"
click node_llm "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/checkup/llm/LlmRouter.java"
click node_goals "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/goal/GoalService.java"
click node_review "https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/review/ReviewInsightService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_members,node_periods,node_accounts,node_entry,node_snapshots toneBlue
class node_holdings,node_valuation,node_broker,node_prices toneAmber
class node_facts,node_factservice,node_dashboard,node_reports,node_lens,node_pivot,node_expenses toneMint
class node_checkup,node_llm,node_goals,node_review toneRose
class node_database,node_family,node_external,node_llmservice toneIndigo
```

## Components

### Household Capture

- [Family Members](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/domain/member/Member.java): `src/main/java/com/family/finance/domain/member/Member.java`
- [Reporting Periods](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/PeriodMapper.java): `src/main/java/com/family/finance/repository/PeriodMapper.java`
- [Accounts](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/AccountMapper.java): `src/main/java/com/family/finance/repository/AccountMapper.java`
- [Monthly Entry](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/entry/EntryController.java): `src/main/java/com/family/finance/web/entry/EntryController.java`
- [Balance Snapshots](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/SnapshotMapper.java): `src/main/java/com/family/finance/repository/SnapshotMapper.java`

### Portfolio Data

- [Holdings Import](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/holdingimport/HoldingImportService.java): `src/main/java/com/family/finance/service/holdingimport/HoldingImportService.java`
- [Holdings Valuation](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/stock/AccountValuationService.java): `src/main/java/com/family/finance/service/stock/AccountValuationService.java`
- [Broker Sync](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/broker/BrokerSyncService.java): `src/main/java/com/family/finance/service/broker/BrokerSyncService.java`
- [Price Snapshots](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/repository/StockHoldingMapper.java): `src/main/java/com/family/finance/repository/StockHoldingMapper.java`

### Financial Analysis

- [Fact Slice](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/factview/FactSlice.java): `src/main/java/com/family/finance/factview/FactSlice.java`
- [Fact Views](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/factview/FactViewService.java): `src/main/java/com/family/finance/factview/FactViewService.java`
- [Dashboard](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/dashboard/DashboardController.java): `src/main/java/com/family/finance/web/dashboard/DashboardController.java`
- [Reports](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/web/report/ReportsController.java): `src/main/java/com/family/finance/web/report/ReportsController.java`
- [Asset Lens](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/lens/LensQueryService.java): `src/main/java/com/family/finance/service/lens/LensQueryService.java`
- [Pivot Engine](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/calc/lens/PivotEngine.java): `src/main/java/com/family/finance/calc/lens/PivotEngine.java`
- [Expense Analysis](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/expense/ExpenseCatQueryService.java): `src/main/java/com/family/finance/service/expense/ExpenseCatQueryService.java`

### Guidance

- [Asset Checkup](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/checkup/FamilyDiagnose.java): `src/main/java/com/family/finance/service/checkup/FamilyDiagnose.java`
- [AI Interpretation](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/checkup/llm/LlmRouter.java): `src/main/java/com/family/finance/service/checkup/llm/LlmRouter.java`
- [Financial Goals](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/goal/GoalService.java): `src/main/java/com/family/finance/service/goal/GoalService.java`
- [Period Review](https://github.com/luodi-nate/financial-management/blob/master/src/main/java/com/family/finance/service/review/ReviewInsightService.java): `src/main/java/com/family/finance/service/review/ReviewInsightService.java`

### Application Core

- **MySQL**

### Other components

- **Household Member**
- **Market Data Services**
- **LLM Provider**

## Connections

- Household Member → Monthly Entry: records balances
- Monthly Entry → Reporting Periods: files by period
- Monthly Entry → Accounts: enters account data
- Monthly Entry → Balance Snapshots: saves snapshots
- Family Members → Reporting Periods: submits asynchronously
- Holdings Import → Accounts: updates positions (evidence: `src/main/java/com/family/finance/service/holdingimport/HoldingImportService.java`)
- Broker Sync → Price Snapshots: syncs holdings (evidence: `src/main/java/com/family/finance/service/broker/BrokerSyncService.java`)
- Market Data Services → Holdings Valuation: provides quotes
- Holdings Valuation → Price Snapshots: reads quotes (evidence: `src/main/java/com/family/finance/service/stock/AccountValuationService.java`)
- Accounts → MySQL: reads and writes (evidence: `src/main/java/com/family/finance/repository/AccountMapper.java`)
- Reporting Periods → MySQL: reads and writes (evidence: `src/main/java/com/family/finance/repository/PeriodMapper.java`)
- Balance Snapshots → MySQL: persists balances
- Monthly Entry → Fact Slice: feeds reporting data
- Fact Slice → Fact Views: supports calculations (evidence: `src/main/java/com/family/finance/factview/FactViewService.java`)
- Fact Views → Dashboard: supplies KPIs
- Fact Views → Reports: supplies metrics
- Fact Views → Asset Lens: supplies portfolio facts (evidence: `src/main/java/com/family/finance/service/lens/LensQueryService.java`)
- Asset Lens → Pivot Engine: queries pivots (evidence: `src/main/java/com/family/finance/service/lens/LensQueryService.java`)
- Expense Analysis → MySQL: queries expenses (evidence: `src/main/java/com/family/finance/service/expense/ExpenseCatQueryService.java`)
- Asset Checkup → AI Interpretation: requests interpretation (evidence: `src/main/java/com/family/finance/service/checkup/llm/LlmDiagnoseService.java`)
- AI Interpretation → LLM Provider: sends analysis
- Asset Checkup → Accounts: assesses allocation
- Financial Goals → Fact Views: uses household metrics
- Period Review → AI Interpretation: requests insights (evidence: `src/main/java/com/family/finance/service/review/ReviewInsightService.java`)
