# barbieri/local-openfinance architecture

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

- Interactive diagram: https://gitdiagram.com/barbieri/local-openfinance
- Repository: https://github.com/barbieri/local-openfinance

## Overview

local-openfinance is a local-first Brazilian Open Finance application: the CLI syncs Banco MCP data into SQLite, while a localhost web UI supports transaction review, classification, household account/investment browsing, and AI-assisted reports. The principal workflow is bank sync → persistent local records → browser filtering and classification → reports and chat. The graph preserves documented product branches; source excerpts directly support sync, transaction querying/editing, and report routes, while other README features are represented at their established module paths without asserting unshown call wiring.

Main entry points: [`src/web/client/App.tsx`](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/App.tsx) (Web application), [`src/db/connection.ts`](https://github.com/barbieri/local-openfinance/blob/master/src/db/connection.ts) (SQLite database), [`src/web/server/server.ts`](https://github.com/barbieri/local-openfinance/blob/master/src/web/server/server.ts) (Web server), [`src/web/server/intelligence-routes.ts`](https://github.com/barbieri/local-openfinance/blob/master/src/web/server/intelligence-routes.ts) (Intelligence routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_ingest["Bank synchronization"]
  node_cli["CLI commands<br/>[sync.ts]"]
  node_sync["Sync engine<br/>[engine.ts]"]
  node_api_client["Banco MCP client<br/>[client.ts]"]
end

subgraph group_g_data["Local finance data"]
  node_sqlite[("SQLite database<br/>[connection.ts]")]
  node_transaction_query["Transaction queries"]
  node_annotation["Classification service"]
  node_transfer["Transfer detection<br/>[detect.ts]"]
end

subgraph group_g_review["Web review"]
  node_app["Web application<br/>[App.tsx]"]
  node_tx_page["Transactions page"]
  node_tx_controller["Transactions controller"]
  node_http_tx["Transaction routes"]
  node_cards["Credit cards"]
  node_investments["Investments"]
  node_triage["Classification review"]
  node_sync_ui["Sync progress UI<br/>[SyncPage.tsx]"]
  node_server["Web server<br/>[server.ts]"]
end

subgraph group_g_intel["Reports and intelligence"]
  node_report_page["Reports interface<br/>[ReportsPage.tsx]"]
  node_chat_page["Report chat<br/>[ReportChat.tsx]"]
  node_intelligence_routes["Intelligence routes"]
  node_report_runner["Report runner<br/>[report-runner.ts]"]
  node_intelligence_tools["Scoped analysis tools<br/>[tools.ts]"]
end

node_person(("Household user"))
node_banco{{"Banco MCP"}}
node_llm{{"Model provider"}}
node_email{{"Email service"}}

node_person -->|"starts sync"| node_cli
node_cli -->|"runs sync"| node_sync
node_sync -->|"fetches pages"| node_api_client
node_api_client -->|"posts requests"| node_banco
node_sync -->|"upserts records"| node_sqlite
node_sqlite -->|"reads records"| node_transaction_query
node_person -->|"browses locally"| node_app
node_app -->|"opens transactions"| node_tx_page
node_tx_page -->|"controls filters"| node_tx_controller
node_tx_controller -->|"requests data"| node_server
node_server -->|"dispatches routes"| node_http_tx
node_http_tx -->|"lists transactions"| node_transaction_query
node_transaction_query -->|"queries records"| node_sqlite
node_http_tx -->|"saves classification"| node_annotation
node_annotation -->|"writes classification"| node_sqlite
node_app -->|"opens card views"| node_cards
node_app -->|"opens positions"| node_investments
node_app -->|"opens suggestions"| node_triage
node_app -->|"opens sync status"| node_sync_ui
node_person -->|"reads reports"| node_report_page
node_report_page -->|"requests reports"| node_server
node_server -->|"dispatches analysis"| node_intelligence_routes
node_intelligence_routes -->|"previews regeneration"| node_report_runner
node_report_runner -.->|"generates report"| node_llm
node_report_runner -->|"persists report"| node_sqlite
node_person -->|"asks follow-ups"| node_chat_page
node_chat_page -->|"sends chat request"| node_intelligence_routes
node_intelligence_routes -->|"executes scoped tool"| node_intelligence_tools
node_intelligence_tools -->|"reads financial facts"| node_sqlite
node_cli -.->|"sends scheduled reports"| node_email

click node_cli "https://github.com/barbieri/local-openfinance/blob/master/src/commands/sync.ts"
click node_sync "https://github.com/barbieri/local-openfinance/blob/master/src/openfinance/sync/engine.ts"
click node_api_client "https://github.com/barbieri/local-openfinance/blob/master/src/openfinance/client.ts"
click node_sqlite "https://github.com/barbieri/local-openfinance/blob/master/src/db/connection.ts"
click node_transaction_query "https://github.com/barbieri/local-openfinance/blob/master/src/db/transaction-query.ts"
click node_annotation "https://github.com/barbieri/local-openfinance/blob/master/src/annotation/save-transaction-classification.ts"
click node_transfer "https://github.com/barbieri/local-openfinance/blob/master/src/transfers/detect.ts"
click node_app "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/App.tsx"
click node_tx_page "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/TransactionsPage.tsx"
click node_tx_controller "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/use-transactions-page-controller.ts"
click node_http_tx "https://github.com/barbieri/local-openfinance/blob/master/src/web/server/transaction-routes.ts"
click node_cards "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/credit-cards/CreditCardsPage.tsx"
click node_investments "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/investments/InvestmentsPage.tsx"
click node_triage "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ClassifyTriagePage.tsx"
click node_sync_ui "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/SyncPage.tsx"
click node_server "https://github.com/barbieri/local-openfinance/blob/master/src/web/server/server.ts"
click node_report_page "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ReportsPage.tsx"
click node_chat_page "https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ReportChat.tsx"
click node_intelligence_routes "https://github.com/barbieri/local-openfinance/blob/master/src/web/server/intelligence-routes.ts"
click node_report_runner "https://github.com/barbieri/local-openfinance/blob/master/src/intelligence/report-runner.ts"
click node_intelligence_tools "https://github.com/barbieri/local-openfinance/blob/master/src/intelligence/tools.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_cli,node_sync,node_api_client,node_person toneBlue
class node_sqlite,node_transaction_query,node_annotation,node_transfer toneAmber
class node_app,node_tx_page,node_tx_controller,node_http_tx,node_cards,node_investments,node_triage,node_sync_ui,node_server toneMint
class node_report_page,node_chat_page,node_intelligence_routes,node_report_runner,node_intelligence_tools toneRose
class node_banco,node_llm,node_email toneIndigo
```

## Components

### Bank synchronization

- [CLI commands](https://github.com/barbieri/local-openfinance/blob/master/src/commands/sync.ts): `src/commands/sync.ts`
- [Sync engine](https://github.com/barbieri/local-openfinance/blob/master/src/openfinance/sync/engine.ts): `src/openfinance/sync/engine.ts`
- [Banco MCP client](https://github.com/barbieri/local-openfinance/blob/master/src/openfinance/client.ts): `src/openfinance/client.ts`

### Local finance data

- [SQLite database](https://github.com/barbieri/local-openfinance/blob/master/src/db/connection.ts): `src/db/connection.ts`
- [Transaction queries](https://github.com/barbieri/local-openfinance/blob/master/src/db/transaction-query.ts): `src/db/transaction-query.ts`
- [Classification service](https://github.com/barbieri/local-openfinance/blob/master/src/annotation/save-transaction-classification.ts): `src/annotation/save-transaction-classification.ts`
- [Transfer detection](https://github.com/barbieri/local-openfinance/blob/master/src/transfers/detect.ts): `src/transfers/detect.ts`

### Web review

- [Web application](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/App.tsx): `src/web/client/App.tsx`
- [Transactions page](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/TransactionsPage.tsx): `src/web/client/pages/TransactionsPage.tsx`
- [Transactions controller](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/use-transactions-page-controller.ts): `src/web/client/pages/use-transactions-page-controller.ts`
- [Transaction routes](https://github.com/barbieri/local-openfinance/blob/master/src/web/server/transaction-routes.ts): `src/web/server/transaction-routes.ts`
- [Credit cards](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/credit-cards/CreditCardsPage.tsx): `src/web/client/pages/credit-cards/CreditCardsPage.tsx`
- [Investments](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/investments/InvestmentsPage.tsx): `src/web/client/pages/investments/InvestmentsPage.tsx`
- [Classification review](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ClassifyTriagePage.tsx): `src/web/client/pages/ClassifyTriagePage.tsx`
- [Sync progress UI](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/SyncPage.tsx): `src/web/client/pages/SyncPage.tsx`
- [Web server](https://github.com/barbieri/local-openfinance/blob/master/src/web/server/server.ts): `src/web/server/server.ts`

### Reports and intelligence

- [Reports interface](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ReportsPage.tsx): `src/web/client/pages/ReportsPage.tsx`
- [Report chat](https://github.com/barbieri/local-openfinance/blob/master/src/web/client/pages/ReportChat.tsx): `src/web/client/pages/ReportChat.tsx`
- [Intelligence routes](https://github.com/barbieri/local-openfinance/blob/master/src/web/server/intelligence-routes.ts): `src/web/server/intelligence-routes.ts`
- [Report runner](https://github.com/barbieri/local-openfinance/blob/master/src/intelligence/report-runner.ts): `src/intelligence/report-runner.ts`
- [Scoped analysis tools](https://github.com/barbieri/local-openfinance/blob/master/src/intelligence/tools.ts): `src/intelligence/tools.ts`

### Other components

- **Household user**
- **Banco MCP**
- **Model provider**
- **Email service**

## Connections

- Household user → CLI commands: starts sync
- CLI commands → Sync engine: runs sync
- Sync engine → Banco MCP client: fetches pages
- Banco MCP client → Banco MCP: posts requests
- Sync engine → SQLite database: upserts records
- SQLite database → Transaction queries: reads records
- Household user → Web application: browses locally
- Web application → Transactions page: opens transactions
- Transactions page → Transactions controller: controls filters
- Transactions controller → Web server: requests data
- Web server → Transaction routes: dispatches routes
- Transaction routes → Transaction queries: lists transactions
- Transaction queries → SQLite database: queries records
- Transaction routes → Classification service: saves classification
- Classification service → SQLite database: writes classification
- Web application → Credit cards: opens card views
- Web application → Investments: opens positions
- Web application → Classification review: opens suggestions
- Web application → Sync progress UI: opens sync status
- Household user → Reports interface: reads reports
- Reports interface → Web server: requests reports
- Web server → Intelligence routes: dispatches analysis
- Intelligence routes → Report runner: previews regeneration
- Report runner → Model provider: generates report
- Report runner → SQLite database: persists report
- Household user → Report chat: asks follow-ups
- Report chat → Intelligence routes: sends chat request
- Intelligence routes → Scoped analysis tools: executes scoped tool
- Scoped analysis tools → SQLite database: reads financial facts
- CLI commands → Email service: sends scheduled reports