# jerwingubat/budget-app architecture

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

- Interactive diagram: https://gitdiagram.com/jerwingubat/budget-app
- Repository: https://github.com/jerwingubat/budget-app

## Overview

BudgetFlow is a browser-based personal-finance app. A signed-in user enters through the protected app shell, then uses finance pages to record transactions and manage budgets, cards, and debts; the dashboard and reports present summaries. Pages use shared Firestore hooks for live data, while debt sharing and receipt scanning provide distinct workflows. The README also documents export/import, categories, and installable offline use. Some paths and features are documented or indexed but not fully sampled, so uncertain internal links are omitted.

Main entry points: [`src/App.jsx`](https://github.com/jerwingubat/budget-app/blob/main/src/App.jsx) (Protected app routes), [`src/hooks/useFirestore.js`](https://github.com/jerwingubat/budget-app/blob/main/src/hooks/useFirestore.js) (Collection hooks), [`src/services/firestore.js`](https://github.com/jerwingubat/budget-app/blob/main/src/services/firestore.js) (Firestore service), [`src/pages/Transactions.jsx`](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Transactions.jsx) (Transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_app["Protected app routes<br/>[App.jsx]"]
  node_layout["Navigation layout<br/>[Layout.jsx]"]
  node_login["Google sign-in<br/>[Login.jsx]"]
end

subgraph group_finance["Finance features"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_transactions["Transactions<br/>[Transactions.jsx]"]
  node_budgets["Budgets<br/>[Budgets.jsx]"]
  node_cards["Credit cards<br/>[CreditCards.jsx]"]
  node_debts["Debt tracker<br/>[Debts.jsx]"]
  node_reports["Reports<br/>[Reports.jsx]"]
  node_settings["Settings and backup<br/>[Settings.jsx]"]
end

subgraph group_data["Identity and data"]
  node_auth["Auth context<br/>[AuthContext.jsx]"]
  node_firebase["Firebase client<br/>[firebase.js]"]
  node_collection_hook["Collection hooks<br/>[useFirestore.js]"]
  node_firestore["Firestore service<br/>[firestore.js]"]
  node_store[("Firestore database")]
end

subgraph group_assist["Specialized workflows"]
  node_sharing["Debt sharing dialog"]
  node_receipt_modal["Receipt scan dialog"]
  node_receipt_hook["Receipt scan flow<br/>[useReceiptScan.js]"]
  node_ocr["OCR service<br/>[ocrService.js]"]
  node_parser["Receipt parser<br/>[receiptParser.js]"]
end

subgraph group_platform["Browser platform"]
  node_browser(("Browser"))
  node_service_worker["Offline service worker<br/>[sw.js]"]
end

node_user(("User"))

node_user -->|"opens"| node_app
node_app -->|"checks identity"| node_auth
node_app -->|"wraps protected pages"| node_layout
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_transactions
node_app -->|"routes to"| node_budgets
node_app -->|"routes to"| node_cards
node_app -->|"routes to"| node_debts
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_settings
node_login -->|"signs in"| node_auth
node_auth -->|"uses auth client"| node_firebase
node_dashboard -->|"reads live data"| node_collection_hook
node_transactions -->|"manages entries"| node_collection_hook
node_budgets -->|"manages budgets"| node_collection_hook
node_cards -->|"manages card data"| node_collection_hook
node_debts -->|"manages debt data"| node_collection_hook
node_reports -->|"reads report data"| node_collection_hook
node_settings -->|"manages categories"| node_collection_hook
node_settings -->|"exports and imports"| node_firestore
node_collection_hook -->|"subscribes and writes"| node_firestore
node_collection_hook -->|"reads settings"| node_firebase
node_firestore -->|"uses database client"| node_firebase
node_firestore -->|"queries and updates"| node_store
node_debts -->|"opens sharing"| node_sharing
node_sharing -->|"creates or revokes shares"| node_firestore
node_collection_hook -->|"loads shared debts"| node_firestore
node_transactions -->|"offers receipt scan"| node_receipt_modal
node_receipt_modal -->|"starts scan flow"| node_receipt_hook
node_receipt_hook -->|"prepares and reads image"| node_ocr
node_receipt_hook -->|"parses receipt text"| node_parser
node_user -->|"uses"| node_browser
node_browser -->|"registers for offline use"| node_service_worker

click node_app "https://github.com/jerwingubat/budget-app/blob/main/src/App.jsx"
click node_layout "https://github.com/jerwingubat/budget-app/blob/main/src/components/Layout.jsx"
click node_login "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Login.jsx"
click node_dashboard "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Dashboard.jsx"
click node_transactions "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Transactions.jsx"
click node_budgets "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Budgets.jsx"
click node_cards "https://github.com/jerwingubat/budget-app/blob/main/src/pages/CreditCards.jsx"
click node_debts "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Debts.jsx"
click node_reports "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Reports.jsx"
click node_settings "https://github.com/jerwingubat/budget-app/blob/main/src/pages/Settings.jsx"
click node_auth "https://github.com/jerwingubat/budget-app/blob/main/src/contexts/AuthContext.jsx"
click node_firebase "https://github.com/jerwingubat/budget-app/blob/main/src/firebase.js"
click node_collection_hook "https://github.com/jerwingubat/budget-app/blob/main/src/hooks/useFirestore.js"
click node_firestore "https://github.com/jerwingubat/budget-app/blob/main/src/services/firestore.js"
click node_sharing "https://github.com/jerwingubat/budget-app/blob/main/src/components/ShareDebtsModal.jsx"
click node_receipt_modal "https://github.com/jerwingubat/budget-app/blob/main/src/components/ScanReceiptModal.jsx"
click node_receipt_hook "https://github.com/jerwingubat/budget-app/blob/main/src/hooks/useReceiptScan.js"
click node_ocr "https://github.com/jerwingubat/budget-app/blob/main/src/services/ocrService.js"
click node_parser "https://github.com/jerwingubat/budget-app/blob/main/src/utils/receiptParser.js"
click node_service_worker "https://github.com/jerwingubat/budget-app/blob/main/public/sw.js"

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_layout,node_login,node_user toneBlue
class node_dashboard,node_transactions,node_budgets,node_cards,node_debts,node_reports,node_settings toneAmber
class node_auth,node_firebase,node_collection_hook,node_firestore,node_store toneMint
class node_sharing,node_receipt_modal,node_receipt_hook,node_ocr,node_parser toneRose
class node_browser,node_service_worker toneIndigo
```

## Components

### App shell

- [Protected app routes](https://github.com/jerwingubat/budget-app/blob/main/src/App.jsx): `src/App.jsx`
- [Navigation layout](https://github.com/jerwingubat/budget-app/blob/main/src/components/Layout.jsx): `src/components/Layout.jsx`
- [Google sign-in](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Login.jsx): `src/pages/Login.jsx`

### Finance features

- [Dashboard](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Dashboard.jsx): `src/pages/Dashboard.jsx`
- [Transactions](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Transactions.jsx): `src/pages/Transactions.jsx`
- [Budgets](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Budgets.jsx): `src/pages/Budgets.jsx`
- [Credit cards](https://github.com/jerwingubat/budget-app/blob/main/src/pages/CreditCards.jsx): `src/pages/CreditCards.jsx`
- [Debt tracker](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Debts.jsx): `src/pages/Debts.jsx`
- [Reports](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Reports.jsx): `src/pages/Reports.jsx`
- [Settings and backup](https://github.com/jerwingubat/budget-app/blob/main/src/pages/Settings.jsx): `src/pages/Settings.jsx`

### Identity and data

- [Auth context](https://github.com/jerwingubat/budget-app/blob/main/src/contexts/AuthContext.jsx): `src/contexts/AuthContext.jsx`
- [Firebase client](https://github.com/jerwingubat/budget-app/blob/main/src/firebase.js): `src/firebase.js`
- [Collection hooks](https://github.com/jerwingubat/budget-app/blob/main/src/hooks/useFirestore.js): `src/hooks/useFirestore.js`
- [Firestore service](https://github.com/jerwingubat/budget-app/blob/main/src/services/firestore.js): `src/services/firestore.js`
- **Firestore database**

### Specialized workflows

- [Debt sharing dialog](https://github.com/jerwingubat/budget-app/blob/main/src/components/ShareDebtsModal.jsx): `src/components/ShareDebtsModal.jsx`
- [Receipt scan dialog](https://github.com/jerwingubat/budget-app/blob/main/src/components/ScanReceiptModal.jsx): `src/components/ScanReceiptModal.jsx`
- [Receipt scan flow](https://github.com/jerwingubat/budget-app/blob/main/src/hooks/useReceiptScan.js): `src/hooks/useReceiptScan.js`
- [OCR service](https://github.com/jerwingubat/budget-app/blob/main/src/services/ocrService.js): `src/services/ocrService.js`
- [Receipt parser](https://github.com/jerwingubat/budget-app/blob/main/src/utils/receiptParser.js): `src/utils/receiptParser.js`

### Browser platform

- **Browser**
- [Offline service worker](https://github.com/jerwingubat/budget-app/blob/main/public/sw.js): `public/sw.js`

### Other components

- **User**

## Connections

- User → Protected app routes: opens (evidence: `src/App.jsx`)
- Protected app routes → Auth context: checks identity (evidence: `src/App.jsx`)
- Protected app routes → Navigation layout: wraps protected pages (evidence: `src/App.jsx`)
- Protected app routes → Google sign-in: routes to (evidence: `src/App.jsx`)
- Protected app routes → Dashboard: routes to (evidence: `src/App.jsx`)
- Protected app routes → Transactions: routes to (evidence: `src/App.jsx`)
- Protected app routes → Budgets: routes to (evidence: `src/App.jsx`)
- Protected app routes → Credit cards: routes to (evidence: `src/App.jsx`)
- Protected app routes → Debt tracker: routes to (evidence: `src/App.jsx`)
- Protected app routes → Reports: routes to (evidence: `src/App.jsx`)
- Protected app routes → Settings and backup: routes to (evidence: `src/App.jsx`)
- Google sign-in → Auth context: signs in (evidence: `src/pages/Login.jsx`)
- Auth context → Firebase client: uses auth client (evidence: `src/contexts/AuthContext.jsx`)
- Dashboard → Collection hooks: reads live data (evidence: `src/pages/Dashboard.jsx`)
- Transactions → Collection hooks: manages entries (evidence: `src/pages/Transactions.jsx`)
- Budgets → Collection hooks: manages budgets (evidence: `src/pages/Budgets.jsx`)
- Credit cards → Collection hooks: manages card data (evidence: `src/pages/CreditCards.jsx`)
- Debt tracker → Collection hooks: manages debt data (evidence: `src/pages/Debts.jsx`)
- Reports → Collection hooks: reads report data (evidence: `src/pages/Reports.jsx`)
- Settings and backup → Collection hooks: manages categories (evidence: `src/pages/Settings.jsx`)
- Settings and backup → Firestore service: exports and imports (evidence: `src/pages/Settings.jsx`)
- Collection hooks → Firestore service: subscribes and writes (evidence: `src/hooks/useFirestore.js`)
- Collection hooks → Firebase client: reads settings (evidence: `src/hooks/useFirestore.js`)
- Firestore service → Firebase client: uses database client (evidence: `src/services/firestore.js`)
- Firestore service → Firestore database: queries and updates (evidence: `src/services/firestore.js`)
- Debt tracker → Debt sharing dialog: opens sharing (evidence: `src/pages/Debts.jsx`)
- Debt sharing dialog → Firestore service: creates or revokes shares (evidence: `src/components/ShareDebtsModal.jsx`)
- Collection hooks → Firestore service: loads shared debts (evidence: `src/hooks/useFirestore.js`)
- Transactions → Receipt scan dialog: offers receipt scan (evidence: `src/pages/Transactions.jsx`)
- Receipt scan dialog → Receipt scan flow: starts scan flow (evidence: `src/components/ScanReceiptModal.jsx`)
- Receipt scan flow → OCR service: prepares and reads image (evidence: `src/hooks/useReceiptScan.js`)
- Receipt scan flow → Receipt parser: parses receipt text (evidence: `src/hooks/useReceiptScan.js`)
- User → Browser: uses (evidence: `README.md`)
- Browser → Offline service worker: registers for offline use
