# tks18/personal-finance-etl architecture

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

- Interactive diagram: https://gitdiagram.com/tks18/personal-finance-etl
- Repository: https://github.com/tks18/personal-finance-etl

## Overview

Personal Finance ETL is a local-first financial evidence and analytics platform. Users launch runs through the CLI or desktop, which invoke the application facade and pipeline orchestrator; the pipeline acquires and transforms financial evidence, reconstructs investment and household state, reconciles it, and publishes analytics for tax, wealth, FIRE, and BI decisions. The README documents capabilities broader than the sampled implementation excerpts; those branches are represented at supported source-directory paths. Edges are limited to explicit README claims or SOURCE INDEX references, so some internal handoffs remain unshown.

Main entry points: [`src/personal_finance_etl/application/investments`](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/investments) (Investment accounting), [`src/personal_finance_etl/infrastructure/warehouse/gold.py`](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/gold.py) (Gold decision marts), [`src/personal_finance_etl/application/ingestion`](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/ingestion) (Evidence ingestion), [`src/personal_finance_etl/domain/household`](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/household) (Household finance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[app.py]"]
  node_desktop["Desktop app<br/>[app.py]"]
  node_facade["Engine facade<br/>[facade.py]"]
end

subgraph group_pipeline["Evidence pipeline"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.py]"]
  node_executor["Pipeline executor<br/>[execution.py]"]
  node_ingestion["Evidence ingestion"]
  node_providers["File and market providers"]
  node_bronze[("Bronze evidence<br/>[bronze.py]")]
  node_transforms["Canonical transforms"]
  node_silver[("Silver facts<br/>[silver.py]")]
end

subgraph group_finance["Financial analysis"]
  node_household["Household finance"]
  node_investments["Investment accounting"]
  node_reconciliation["Investment reconciliation<br/>[engine.py]"]
  node_market["Market and FX analytics"]
  node_tax["Tax evidence<br/>[tax_service.py]"]
  node_wealth["Wealth analytics<br/>[wealth_service.py]"]
  node_fire["FIRE forecasting"]
  node_rules["Financial rules"]
end

subgraph group_operations["Operational state"]
  node_control[("Run and artifact records")]
end

subgraph group_publication["Analytics publication"]
  node_gold[("Gold decision marts<br/>[gold.py]")]
end

node_user(("Finance user"))
node_bi["BI and analytics"]

node_user -->|"runs"| node_cli
node_user -->|"runs"| node_desktop
node_cli -->|"invokes"| node_facade
node_desktop -->|"invokes"| node_facade
node_facade -.->|"starts run"| node_orchestrator
node_orchestrator -->|"delegates phases"| node_executor
node_executor -->|"acquires evidence"| node_ingestion
node_ingestion -->|"uses providers"| node_providers
node_ingestion -->|"records runs"| node_control
node_ingestion -->|"synchronizes evidence"| node_bronze
node_bronze -->|"feeds"| node_transforms
node_transforms -->|"canonicalizes"| node_silver
node_silver -->|"supports reconstruction"| node_household
node_silver -->|"supports reconstruction"| node_investments
node_investments -->|"compares state"| node_reconciliation
node_investments -->|"provides realized economics"| node_tax
node_household -->|"provides context"| node_tax
node_household -->|"contributes state"| node_wealth
node_investments -->|"contributes state"| node_wealth
node_market -.->|"supplies market data"| node_investments
node_wealth -->|"models uncertainty"| node_fire
node_household -->|"publishes analytics"| node_gold
node_investments -->|"publishes analytics"| node_gold
node_tax -->|"publishes evidence"| node_gold
node_fire -->|"publishes forecasts"| node_gold
node_gold -->|"serves marts"| node_bi
node_rules -.->|"configures analysis"| node_investments

click node_cli "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/presentation/cli/app.py"
click node_desktop "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/presentation/desktop/app.py"
click node_facade "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/facade.py"
click node_orchestrator "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/pipeline/orchestrator.py"
click node_executor "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/pipeline/execution.py"
click node_ingestion "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/ingestion"
click node_providers "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/infrastructure/providers"
click node_bronze "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/bronze.py"
click node_transforms "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/household/transforms"
click node_silver "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/silver.py"
click node_control "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/infrastructure/control_plane"
click node_household "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/household"
click node_investments "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/investments"
click node_reconciliation "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/domain/investments/reconciliation/engine.py"
click node_market "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/market"
click node_tax "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/tax/tax_service.py"
click node_wealth "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/wealth/wealth_service.py"
click node_fire "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/fire"
click node_gold "https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/gold.py"
click node_rules "https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/config/financial_rules"

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_cli,node_desktop,node_facade,node_user toneBlue
class node_orchestrator,node_executor,node_ingestion,node_providers,node_bronze,node_transforms,node_silver toneAmber
class node_household,node_investments,node_reconciliation,node_market,node_tax,node_wealth,node_fire,node_rules toneMint
class node_control toneRose
class node_gold,node_bi toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/presentation/cli/app.py): `src/personal_finance_etl/presentation/cli/app.py`
- [Desktop app](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/presentation/desktop/app.py): `src/personal_finance_etl/presentation/desktop/app.py`
- [Engine facade](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/facade.py): `src/personal_finance_etl/application/facade.py`

### Evidence pipeline

- [Run orchestrator](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/pipeline/orchestrator.py): `src/personal_finance_etl/application/pipeline/orchestrator.py`
- [Pipeline executor](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/pipeline/execution.py): `src/personal_finance_etl/application/pipeline/execution.py`
- [Evidence ingestion](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/ingestion): `src/personal_finance_etl/application/ingestion`
- [File and market providers](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/infrastructure/providers): `src/personal_finance_etl/infrastructure/providers`
- [Bronze evidence](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/bronze.py): `src/personal_finance_etl/infrastructure/warehouse/bronze.py`
- [Canonical transforms](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/household/transforms): `src/personal_finance_etl/domain/household/transforms`
- [Silver facts](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/silver.py): `src/personal_finance_etl/infrastructure/warehouse/silver.py`

### Financial analysis

- [Household finance](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/household): `src/personal_finance_etl/domain/household`
- [Investment accounting](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/application/investments): `src/personal_finance_etl/application/investments`
- [Investment reconciliation](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/domain/investments/reconciliation/engine.py): `src/personal_finance_etl/domain/investments/reconciliation/engine.py`
- [Market and FX analytics](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/market): `src/personal_finance_etl/domain/market`
- [Tax evidence](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/tax/tax_service.py): `src/personal_finance_etl/application/tax/tax_service.py`
- [Wealth analytics](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/application/wealth/wealth_service.py): `src/personal_finance_etl/application/wealth/wealth_service.py`
- [FIRE forecasting](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/domain/fire): `src/personal_finance_etl/domain/fire`
- [Financial rules](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/config/financial_rules): `src/personal_finance_etl/config/financial_rules`

### Operational state

- [Run and artifact records](https://github.com/tks18/personal-finance-etl/tree/master/src/personal_finance_etl/infrastructure/control_plane): `src/personal_finance_etl/infrastructure/control_plane`

### Analytics publication

- [Gold decision marts](https://github.com/tks18/personal-finance-etl/blob/master/src/personal_finance_etl/infrastructure/warehouse/gold.py): `src/personal_finance_etl/infrastructure/warehouse/gold.py`

### Other components

- **Finance user**
- **BI and analytics**

## Connections

- Finance user → CLI: runs (evidence: `README.md`)
- Finance user → Desktop app: runs (evidence: `README.md`)
- CLI → Engine facade: invokes (evidence: `src/personal_finance_etl/presentation/cli/app.py`)
- Desktop app → Engine facade: invokes (evidence: `src/personal_finance_etl/presentation/desktop/app.py`)
- Engine facade → Run orchestrator: starts run (evidence: `src/personal_finance_etl/application/facade.py`)
- Run orchestrator → Pipeline executor: delegates phases (evidence: `src/personal_finance_etl/application/pipeline/orchestrator.py`)
- Pipeline executor → Evidence ingestion: acquires evidence (evidence: `README.md`)
- Evidence ingestion → File and market providers: uses providers (evidence: `README.md`)
- Evidence ingestion → Run and artifact records: records runs (evidence: `README.md`)
- Evidence ingestion → Bronze evidence: synchronizes evidence (evidence: `README.md`)
- Bronze evidence → Canonical transforms: feeds (evidence: `README.md`)
- Canonical transforms → Silver facts: canonicalizes (evidence: `README.md`)
- Silver facts → Household finance: supports reconstruction (evidence: `README.md`)
- Silver facts → Investment accounting: supports reconstruction (evidence: `README.md`)
- Investment accounting → Investment reconciliation: compares state (evidence: `README.md`)
- Investment accounting → Tax evidence: provides realized economics (evidence: `README.md`)
- Household finance → Tax evidence: provides context (evidence: `README.md`)
- Household finance → Wealth analytics: contributes state (evidence: `README.md`)
- Investment accounting → Wealth analytics: contributes state (evidence: `README.md`)
- Market and FX analytics → Investment accounting: supplies market data (evidence: `src/personal_finance_etl/application/investments/isin_service/pipeline.py`)
- Wealth analytics → FIRE forecasting: models uncertainty (evidence: `README.md`)
- Household finance → Gold decision marts: publishes analytics (evidence: `README.md`)
- Investment accounting → Gold decision marts: publishes analytics (evidence: `README.md`)
- Tax evidence → Gold decision marts: publishes evidence (evidence: `README.md`)
- FIRE forecasting → Gold decision marts: publishes forecasts (evidence: `README.md`)
- Gold decision marts → BI and analytics: serves marts (evidence: `README.md`)
- Financial rules → Investment accounting: configures analysis (evidence: `src/personal_finance_etl/application/investments/isin_service/pipeline.py`)
