# kotaroison/finbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/kotaroison/finbuddy
- Repository: https://github.com/kotaroison/finbuddy

## Overview

FinBuddy is a Streamlit personal-finance dashboard. Users record expenses, then review spending, check monthly budget progress, request AI tips, or export transaction and report files. These workflows are implemented together in main.py rather than split into separate modules. The graph reflects the explicit CSV and export-file operations and the optional Gemini integration; requirements.txt lists dependencies but does not establish additional runtime components.

Main entry points: [`main.py`](https://github.com/kotaroison/finbuddy/blob/main/main.py) (Streamlit dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Streamlit dashboard<br/>[main.py]"]
end

subgraph group_finance["Finance features"]
  node_expenses["Expense entry<br/>[main.py]"]
  node_dashboard["Spending dashboard<br/>[main.py]"]
  node_budget["Budget planner<br/>[main.py]"]
  node_insights["AI insights<br/>[main.py]"]
  node_export["Export reports<br/>[main.py]"]
end

subgraph group_storage["Persistence"]
  node_transaction_store["Transaction storage<br/>[main.py]"]
  node_transaction_csv[("Transactions CSV<br/>[main.py]")]
  node_report_file["Report files<br/>[main.py]"]
end

subgraph group_integrations["Integrations"]
  node_gemini["Gemini API"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_expenses
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_budget
node_app -->|"renders"| node_insights
node_app -->|"renders"| node_export
node_app -->|"loads data"| node_transaction_store
node_transaction_store -->|"reads/writes"| node_transaction_csv
node_expenses -->|"saves"| node_transaction_store
node_dashboard -->|"uses loaded data"| node_transaction_store
node_budget -->|"uses loaded data"| node_transaction_store
node_insights -->|"summarizes loaded data"| node_transaction_store
node_insights -.->|"requests tips"| node_gemini
node_export -->|"uses loaded data"| node_transaction_store
node_export -->|"writes report"| node_report_file
node_app -->|"shows results"| node_user

click node_app "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_expenses "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_dashboard "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_budget "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_insights "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_export "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_transaction_store "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_transaction_csv "https://github.com/kotaroison/finbuddy/blob/main/main.py"
click node_report_file "https://github.com/kotaroison/finbuddy/blob/main/main.py"

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_app,node_user toneBlue
class node_expenses,node_dashboard,node_budget,node_insights,node_export toneAmber
class node_transaction_store,node_transaction_csv,node_report_file toneMint
class node_gemini toneRose
```

## Components

### User interface

- [Streamlit dashboard](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`

### Finance features

- [Expense entry](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [Spending dashboard](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [Budget planner](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [AI insights](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [Export reports](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`

### Persistence

- [Transaction storage](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [Transactions CSV](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`
- [Report files](https://github.com/kotaroison/finbuddy/blob/main/main.py): `main.py`

### Integrations

- **Gemini API**

### Other components

- **User**

## Connections

- User → Streamlit dashboard: uses
- Streamlit dashboard → Expense entry: renders
- Streamlit dashboard → Spending dashboard: renders
- Streamlit dashboard → Budget planner: renders
- Streamlit dashboard → AI insights: renders
- Streamlit dashboard → Export reports: renders
- Streamlit dashboard → Transaction storage: loads data
- Transaction storage → Transactions CSV: reads/writes
- Expense entry → Transaction storage: saves
- Spending dashboard → Transaction storage: uses loaded data
- Budget planner → Transaction storage: uses loaded data
- AI insights → Transaction storage: summarizes loaded data
- AI insights → Gemini API: requests tips
- Export reports → Transaction storage: uses loaded data
- Export reports → Report files: writes report
- Streamlit dashboard → User: shows results