# tomfunk/fungible architecture

> Architecture diagram of the GitHub repository tomfunk/fungible, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tomfunk/fungible
- Repository: https://github.com/tomfunk/fungible

## Overview

Fungible is a local-first personal-finance application with terminal and desktop interfaces, plus MCP and HTTP access. The user workflow is to connect accounts or import statements, categorize and tag transactions, then inspect spending, net worth, trends, and financial-health analyses. The shared tool executor exposes finance operations to external clients; the local database holds the common state. README capabilities are included even where implementation excerpts were unavailable. Connections for unsampled modules are limited to documented relationships or SOURCE INDEX references.

Main entry points: [`core/db.ts`](https://github.com/tomfunk/fungible/blob/dev/core/db.ts) (Local database), [`core/tools.ts`](https://github.com/tomfunk/fungible/blob/dev/core/tools.ts) (Shared tool executor), [`core/sync.ts`](https://github.com/tomfunk/fungible/blob/dev/core/sync.ts) (Plaid sync), [`mcp/create-server.ts`](https://github.com/tomfunk/fungible/blob/dev/mcp/create-server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_tui["Terminal UI<br/>[App.tsx]"]
  node_desktop["Desktop UI<br/>[App.tsx]"]
  node_desktopmain["Electron main<br/>[app.ts]"]
end

subgraph group_ingestion["Data ingestion"]
  node_sync["Plaid sync<br/>[sync.ts]"]
  node_plaid["Plaid client<br/>[plaid.ts]"]
  node_csvimport["CSV imports<br/>[imports.ts]"]
  node_balanceimport["Balance import<br/>[balance-import.ts]"]
end

subgraph group_finance["Finance operations"]
  node_rules["Category and name rules<br/>[rules.ts]"]
  node_tags["Tags<br/>[tags.ts]"]
  node_transactions["Transactions<br/>[transactions.ts]"]
  node_analytics["Finance queries<br/>[queries.ts]"]
  node_health["Financial health<br/>[health.ts]"]
  node_agentcontext["Agent finance context<br/>[agent-context.ts]"]
  node_canvas["Canvas history<br/>[canvas-history.ts]"]
end

subgraph group_access["External access"]
  node_tools["Shared tool executor<br/>[tools.ts]"]
  node_mcp["MCP server<br/>[create-server.ts]"]
  node_mcphttp["MCP HTTP transport<br/>[http.ts]"]
  node_api["HTTP API<br/>[server.ts]"]
end

subgraph group_storage["Local state"]
  node_db[("Local database<br/>[db.ts]")]
  node_backups["Daily backups<br/>[backup.ts]"]
  node_datadir["Data directory<br/>[paths.ts]"]
end

node_user(("Finance user"))

node_user -->|"uses"| node_tui
node_user -->|"uses"| node_desktop
node_user -->|"asks Claude"| node_mcp
node_user -->|"calls"| node_api
node_tui -->|"shares local data"| node_db
node_desktop -->|"shares local data"| node_db
node_desktopmain -->|"initializes"| node_db
node_desktopmain -->|"starts sync"| node_sync
node_sync -->|"fetches accounts and transactions"| node_plaid
node_sync -->|"loads categorization rules"| node_rules
node_sync -->|"applies tag rules"| node_tags
node_sync -->|"writes synced data"| node_db
node_user -->|"imports statements"| node_csvimport
node_user -->|"imports balances"| node_balanceimport
node_tools -->|"queries finance data"| node_analytics
node_tools -->|"previews balance imports"| node_balanceimport
node_tools -->|"manages rules"| node_rules
node_tools -->|"manages transactions"| node_transactions
node_tools -->|"manages tags"| node_tags
node_agentcontext -->|"uses health metrics"| node_health
node_agentcontext -->|"reads balances"| node_db
node_mcp -->|"executes tools"| node_tools
node_mcp -->|"builds Canvas context"| node_canvas
node_mcphttp -->|"hosts server"| node_mcp
node_api -->|"executes tools"| node_tools
node_api -->|"initializes"| node_db
node_backups -->|"backs up"| node_db
node_backups -->|"stores backups under"| node_datadir
node_db -->|"stores database under"| node_datadir

click node_tui "https://github.com/tomfunk/fungible/blob/dev/tui/App.tsx"
click node_desktop "https://github.com/tomfunk/fungible/blob/dev/gui/renderer/src/App.tsx"
click node_desktopmain "https://github.com/tomfunk/fungible/blob/dev/gui/main/app.ts"
click node_sync "https://github.com/tomfunk/fungible/blob/dev/core/sync.ts"
click node_plaid "https://github.com/tomfunk/fungible/blob/dev/core/plaid.ts"
click node_csvimport "https://github.com/tomfunk/fungible/blob/dev/core/imports.ts"
click node_balanceimport "https://github.com/tomfunk/fungible/blob/dev/core/balance-import.ts"
click node_rules "https://github.com/tomfunk/fungible/blob/dev/core/rules.ts"
click node_tags "https://github.com/tomfunk/fungible/blob/dev/core/tags.ts"
click node_transactions "https://github.com/tomfunk/fungible/blob/dev/core/transactions.ts"
click node_analytics "https://github.com/tomfunk/fungible/blob/dev/core/queries.ts"
click node_health "https://github.com/tomfunk/fungible/blob/dev/core/health.ts"
click node_agentcontext "https://github.com/tomfunk/fungible/blob/dev/core/agent-context.ts"
click node_canvas "https://github.com/tomfunk/fungible/blob/dev/core/canvas-history.ts"
click node_tools "https://github.com/tomfunk/fungible/blob/dev/core/tools.ts"
click node_mcp "https://github.com/tomfunk/fungible/blob/dev/mcp/create-server.ts"
click node_mcphttp "https://github.com/tomfunk/fungible/blob/dev/mcp/http.ts"
click node_api "https://github.com/tomfunk/fungible/blob/dev/api/server.ts"
click node_db "https://github.com/tomfunk/fungible/blob/dev/core/db.ts"
click node_backups "https://github.com/tomfunk/fungible/blob/dev/core/backup.ts"
click node_datadir "https://github.com/tomfunk/fungible/blob/dev/core/paths.ts"

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_tui,node_desktop,node_desktopmain,node_user toneBlue
class node_sync,node_plaid,node_csvimport,node_balanceimport toneAmber
class node_rules,node_tags,node_transactions,node_analytics,node_health,node_agentcontext,node_canvas toneMint
class node_tools,node_mcp,node_mcphttp,node_api toneRose
class node_db,node_backups,node_datadir toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/tomfunk/fungible/blob/dev/tui/App.tsx): `tui/App.tsx`
- [Desktop UI](https://github.com/tomfunk/fungible/blob/dev/gui/renderer/src/App.tsx): `gui/renderer/src/App.tsx`
- [Electron main](https://github.com/tomfunk/fungible/blob/dev/gui/main/app.ts): `gui/main/app.ts`

### Data ingestion

- [Plaid sync](https://github.com/tomfunk/fungible/blob/dev/core/sync.ts): `core/sync.ts`
- [Plaid client](https://github.com/tomfunk/fungible/blob/dev/core/plaid.ts): `core/plaid.ts`
- [CSV imports](https://github.com/tomfunk/fungible/blob/dev/core/imports.ts): `core/imports.ts`
- [Balance import](https://github.com/tomfunk/fungible/blob/dev/core/balance-import.ts): `core/balance-import.ts`

### Finance operations

- [Category and name rules](https://github.com/tomfunk/fungible/blob/dev/core/rules.ts): `core/rules.ts`
- [Tags](https://github.com/tomfunk/fungible/blob/dev/core/tags.ts): `core/tags.ts`
- [Transactions](https://github.com/tomfunk/fungible/blob/dev/core/transactions.ts): `core/transactions.ts`
- [Finance queries](https://github.com/tomfunk/fungible/blob/dev/core/queries.ts): `core/queries.ts`
- [Financial health](https://github.com/tomfunk/fungible/blob/dev/core/health.ts): `core/health.ts`
- [Agent finance context](https://github.com/tomfunk/fungible/blob/dev/core/agent-context.ts): `core/agent-context.ts`
- [Canvas history](https://github.com/tomfunk/fungible/blob/dev/core/canvas-history.ts): `core/canvas-history.ts`

### External access

- [Shared tool executor](https://github.com/tomfunk/fungible/blob/dev/core/tools.ts): `core/tools.ts`
- [MCP server](https://github.com/tomfunk/fungible/blob/dev/mcp/create-server.ts): `mcp/create-server.ts`
- [MCP HTTP transport](https://github.com/tomfunk/fungible/blob/dev/mcp/http.ts): `mcp/http.ts`
- [HTTP API](https://github.com/tomfunk/fungible/blob/dev/api/server.ts): `api/server.ts`

### Local state

- [Local database](https://github.com/tomfunk/fungible/blob/dev/core/db.ts): `core/db.ts`
- [Daily backups](https://github.com/tomfunk/fungible/blob/dev/core/backup.ts): `core/backup.ts`
- [Data directory](https://github.com/tomfunk/fungible/blob/dev/core/paths.ts): `core/paths.ts`

### Other components

- **Finance user**

## Connections

- Finance user → Terminal UI: uses (evidence: `README.md`)
- Finance user → Desktop UI: uses (evidence: `README.md`)
- Finance user → MCP server: asks Claude (evidence: `README.md`)
- Finance user → HTTP API: calls (evidence: `README.md`)
- Terminal UI → Local database: shares local data (evidence: `README.md`)
- Desktop UI → Local database: shares local data (evidence: `README.md`)
- Electron main → Local database: initializes (evidence: `gui/main/app.ts`)
- Electron main → Plaid sync: starts sync (evidence: `gui/main/app.ts`)
- Plaid sync → Plaid client: fetches accounts and transactions (evidence: `core/sync.ts`)
- Plaid sync → Category and name rules: loads categorization rules (evidence: `core/sync.ts`)
- Plaid sync → Tags: applies tag rules (evidence: `core/sync.ts`)
- Plaid sync → Local database: writes synced data (evidence: `core/sync.ts`)
- Finance user → CSV imports: imports statements (evidence: `README.md`)
- Finance user → Balance import: imports balances (evidence: `README.md`)
- Shared tool executor → Finance queries: queries finance data (evidence: `core/tools.ts`)
- Shared tool executor → Balance import: previews balance imports (evidence: `core/tools.ts`)
- Shared tool executor → Category and name rules: manages rules (evidence: `core/tools.ts`)
- Shared tool executor → Transactions: manages transactions (evidence: `core/tools.ts`)
- Shared tool executor → Tags: manages tags (evidence: `core/tools.ts`)
- Agent finance context → Financial health: uses health metrics (evidence: `core/agent-context.ts`)
- Agent finance context → Local database: reads balances (evidence: `core/agent-context.ts`)
- MCP server → Shared tool executor: executes tools (evidence: `mcp/create-server.ts`)
- MCP server → Canvas history: builds Canvas context (evidence: `mcp/create-server.ts`)
- MCP HTTP transport → MCP server: hosts server (evidence: `mcp/http.ts`)
- HTTP API → Shared tool executor: executes tools (evidence: `api/server.ts`)
- HTTP API → Local database: initializes (evidence: `api/server.ts`)
- Daily backups → Local database: backs up (evidence: `core/backup.ts`)
- Daily backups → Data directory: stores backups under (evidence: `core/backup.ts`)
- Local database → Data directory: stores database under (evidence: `core/db.ts`)
