# thakkalisuresh/budget-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/thakkalisuresh/budget-dashboard
- Repository: https://github.com/thakkalisuresh/budget-dashboard

## Overview

Fundient is a household budgeting dashboard whose browser app reads and writes the user-owned Google Sheet. The main workflow is sign in, load a month’s budget and expenses, inspect or update spending, and persist changes to the sheet; receipt and statement imports add capture and reconciliation stages. Separate branches cover household splits, card rewards, AI chat, mobile-wallet capture, offline use, and notifications. Relationships reflect the README and sampled source; some feature wiring is documented but not shown in the excerpts.

Main entry points: [`src/App.jsx`](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/App.jsx) (Dashboard app), [`src/sheetsApi.js`](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/sheetsApi.js) (Sheets access), [`functions/claude.mjs`](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/claude.mjs) (Claude proxy), [`src/CardsTab.jsx`](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/CardsTab.jsx) (Card analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard client"]
  node_app["Dashboard app<br/>[App.jsx]"]
  node_auth["Sign-in and lock<br/>[useAuth.js]"]
  node_budget["Budget views<br/>[BudgetRules.jsx]"]
  node_ledger["Expense ledger<br/>[LedgerTab.jsx]"]
  node_history["History views<br/>[HistoryTab.jsx]"]
  node_split["Household split<br/>[SplitTab.jsx]"]
  node_cards["Card analytics<br/>[CardsTab.jsx]"]
end

subgraph group_sheets["Budget data"]
  node_sheetapi["Sheets access<br/>[sheetsApi.js]"]
  node_sheet[("User budget sheet")]
end

subgraph group_capture["Capture and analysis"]
  node_scanner["Receipt scanner"]
  node_statement["Statement reconciliation"]
  node_parsers["Statement parsers<br/>[csvParsers.js]"]
  node_rewards["Card rewards engine<br/>[cardRewards.js]"]
  node_chat["AI budget chat<br/>[ChatAgent.jsx]"]
end

subgraph group_services["Backend services"]
  node_claude["Claude proxy<br/>[claude.mjs]"]
  node_wallet["Wallet capture webhook<br/>[wallet-webhook.mjs]"]
  node_telegram["Telegram bot"]
  node_botcore["Bot workflows<br/>[_bot-core.mjs]"]
  node_firestore[("Bot and user state<br/>[firestore.mjs]")]
  node_pushservice["Push functions<br/>[push-subscribe.mjs]"]
end

subgraph group_engagement["Access and engagement"]
  node_offline["Offline queue<br/>[offlineQueue.js]"]
  node_push["Push notifications<br/>[usePush.js]"]
end

node_person(("Household user"))
node_bankautomation(("Mobile automation"))
node_telegramuser(("Telegram user"))
node_claudeservice{{"Anthropic Claude"}}
node_google{{"Google OAuth"}}
node_pushprovider{{"Web Push service"}}

node_person -->|"uses"| node_app
node_app -->|"authenticates"| node_auth
node_auth -->|"signs in via"| node_google
node_app -->|"shows"| node_budget
node_app -->|"shows"| node_ledger
node_app -->|"shows"| node_history
node_app -->|"shows"| node_split
node_app -->|"shows"| node_cards
node_budget -->|"loads and updates"| node_sheetapi
node_ledger -->|"reads expenses"| node_sheetapi
node_history -->|"reads history"| node_sheetapi
node_split -->|"reads split data"| node_sheetapi
node_cards -->|"uses"| node_rewards
node_cards -->|"reads card data"| node_sheetapi
node_sheetapi -->|"reads and writes"| node_sheet
node_person -->|"scans receipts"| node_scanner
node_scanner -->|"requests extraction"| node_claude
node_claude -->|"calls"| node_claudeservice
node_scanner -->|"saves expenses"| node_sheetapi
node_person -->|"imports statement"| node_statement
node_statement -->|"parses files"| node_parsers
node_statement -->|"matches and writes"| node_sheetapi
node_person -->|"asks budget questions"| node_chat
node_chat -->|"requests AI response"| node_claude
node_bankautomation -->|"posts transaction"| node_wallet
node_wallet -->|"extracts transaction"| node_claude
node_wallet -->|"categorizes and writes"| node_sheetapi
node_telegramuser -->|"sends updates"| node_telegram
node_telegram -->|"dispatches messages"| node_botcore
node_botcore -->|"reads and writes"| node_sheetapi
node_telegram -->|"stores bot state"| node_firestore
node_app -->|"queues offline expenses"| node_offline
node_app -->|"manages subscriptions"| node_push
node_push -->|"subscribes"| node_pushservice
node_pushservice -->|"stores subscriptions"| node_firestore
node_pushservice -->|"sends notifications"| node_pushprovider

click node_app "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/App.jsx"
click node_auth "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/useAuth.js"
click node_budget "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/BudgetRules.jsx"
click node_ledger "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/LedgerTab.jsx"
click node_history "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/HistoryTab.jsx"
click node_split "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/SplitTab.jsx"
click node_cards "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/CardsTab.jsx"
click node_sheetapi "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/sheetsApi.js"
click node_scanner "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/useReceiptScanner.js"
click node_statement "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/ReconcileDialog.jsx"
click node_parsers "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/csvParsers.js"
click node_rewards "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/cardRewards.js"
click node_chat "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/ChatAgent.jsx"
click node_claude "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/claude.mjs"
click node_wallet "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/wallet-webhook.mjs"
click node_telegram "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/telegram-webhook.mjs"
click node_botcore "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/lib/_bot-core.mjs"
click node_firestore "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/lib/firestore.mjs"
click node_offline "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/offlineQueue.js"
click node_push "https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/usePush.js"
click node_pushservice "https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/push-subscribe.mjs"

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_auth,node_budget,node_ledger,node_history,node_split,node_cards,node_person,node_telegramuser toneBlue
class node_sheetapi,node_sheet toneAmber
class node_scanner,node_statement,node_parsers,node_rewards,node_chat toneMint
class node_claude,node_wallet,node_telegram,node_botcore,node_firestore,node_pushservice toneRose
class node_offline,node_push,node_bankautomation,node_claudeservice,node_google,node_pushprovider toneIndigo
```

## Components

### Dashboard client

- [Dashboard app](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/App.jsx): `src/App.jsx`
- [Sign-in and lock](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/useAuth.js): `src/useAuth.js`
- [Budget views](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/BudgetRules.jsx): `src/BudgetRules.jsx`
- [Expense ledger](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/LedgerTab.jsx): `src/LedgerTab.jsx`
- [History views](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/HistoryTab.jsx): `src/HistoryTab.jsx`
- [Household split](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/SplitTab.jsx): `src/SplitTab.jsx`
- [Card analytics](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/CardsTab.jsx): `src/CardsTab.jsx`

### Budget data

- [Sheets access](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/sheetsApi.js): `src/sheetsApi.js`
- **User budget sheet**

### Capture and analysis

- [Receipt scanner](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/useReceiptScanner.js): `src/useReceiptScanner.js`
- [Statement reconciliation](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/ReconcileDialog.jsx): `src/ReconcileDialog.jsx`
- [Statement parsers](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/csvParsers.js): `src/csvParsers.js`
- [Card rewards engine](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/cardRewards.js): `src/cardRewards.js`
- [AI budget chat](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/ChatAgent.jsx): `src/ChatAgent.jsx`

### Backend services

- [Claude proxy](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/claude.mjs): `functions/claude.mjs`
- [Wallet capture webhook](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/wallet-webhook.mjs): `functions/wallet-webhook.mjs`
- [Telegram bot](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/telegram-webhook.mjs): `functions/telegram-webhook.mjs`
- [Bot workflows](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/lib/_bot-core.mjs): `functions/lib/_bot-core.mjs`
- [Bot and user state](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/lib/firestore.mjs): `functions/lib/firestore.mjs`
- [Push functions](https://github.com/thakkalisuresh/budget-dashboard/blob/main/functions/push-subscribe.mjs): `functions/push-subscribe.mjs`

### Access and engagement

- [Offline queue](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/offlineQueue.js): `src/offlineQueue.js`
- [Push notifications](https://github.com/thakkalisuresh/budget-dashboard/blob/main/src/usePush.js): `src/usePush.js`

### Other components

- **Household user**
- **Mobile automation**
- **Telegram user**
- **Anthropic Claude**
- **Google OAuth**
- **Web Push service**

## Connections

- Household user → Dashboard app: uses
- Dashboard app → Sign-in and lock: authenticates
- Sign-in and lock → Google OAuth: signs in via
- Dashboard app → Budget views: shows
- Dashboard app → Expense ledger: shows
- Dashboard app → History views: shows
- Dashboard app → Household split: shows
- Dashboard app → Card analytics: shows
- Budget views → Sheets access: loads and updates
- Expense ledger → Sheets access: reads expenses
- History views → Sheets access: reads history
- Household split → Sheets access: reads split data
- Card analytics → Card rewards engine: uses
- Card analytics → Sheets access: reads card data
- Sheets access → User budget sheet: reads and writes
- Household user → Receipt scanner: scans receipts
- Receipt scanner → Claude proxy: requests extraction
- Claude proxy → Anthropic Claude: calls
- Receipt scanner → Sheets access: saves expenses
- Household user → Statement reconciliation: imports statement
- Statement reconciliation → Statement parsers: parses files
- Statement reconciliation → Sheets access: matches and writes
- Household user → AI budget chat: asks budget questions
- AI budget chat → Claude proxy: requests AI response
- Mobile automation → Wallet capture webhook: posts transaction
- Wallet capture webhook → Claude proxy: extracts transaction
- Wallet capture webhook → Sheets access: categorizes and writes
- Telegram user → Telegram bot: sends updates
- Telegram bot → Bot workflows: dispatches messages
- Bot workflows → Sheets access: reads and writes
- Telegram bot → Bot and user state: stores bot state
- Dashboard app → Offline queue: queues offline expenses
- Dashboard app → Push notifications: manages subscriptions
- Push notifications → Push functions: subscribes
- Push functions → Bot and user state: stores subscriptions
- Push functions → Web Push service: sends notifications