# cedzzzzzzzzz/budget-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/cedzzzzzzzzz/budget-tracker
- Repository: https://github.com/cedzzzzzzzzz/budget-tracker

## Overview

Budget Tracker is a full-stack personal-finance app. Users authenticate, configure weekly allowances and categories, record expenses manually or by scanning receipts, then review spending and savings analytics or export reports. The React pages call the Flask API; route handlers own backend operations and use database and domain services. The README documents major capabilities not fully visible in the excerpts; those are included, with edges omitted where implementation wiring was not shown.

Main entry points: [`api/routes.py`](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/routes.py) (API routes), [`frontend/src/api.js`](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/App.jsx) (React routes), [`frontend/src/pages/Dashboard.jsx`](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React routes<br/>[App.jsx]"]
  node_clientapi["API client<br/>[api.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_budgetui["Budget setup<br/>[BudgetSetup.jsx]"]
  node_savingsui["Savings view<br/>[Savings.jsx]"]
  node_adminui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_reportsui["Reports view<br/>[Reports.jsx]"]
  node_categoriesui["Category context"]
  node_receiptui["Receipt scanner<br/>[ReceiptScanner.jsx]"]
end

subgraph group_api["API and identity"]
  node_app["Flask app<br/>[app.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_auth["Authentication and security<br/>[security.py]"]
  node_email["Email service<br/>[email_service.py]"]
end

subgraph group_spending["Budget and spending"]
  node_database[("User and expense store<br/>[database.py]")]
  node_category["Category services"]
  node_categorizer["Category rules<br/>[categorize.py]"]
end

subgraph group_receipt["Receipt processing"]
  node_receiptservice["Receipt extraction<br/>[receipt_service.py]"]
  node_provider["Gemini OCR provider<br/>[gemini.py]"]
  node_schema["Receipt normalization<br/>[receipt_schema.py]"]
end

subgraph group_reporting["Insights and exports"]
  node_insights["Spending insights<br/>[insights.py]"]
  node_anomalies["Spending anomalies<br/>[anomalies.py]"]
  node_pdf["PDF reports<br/>[pdf_report.py]"]
  node_account["Account export<br/>[account_export.py]"]
end

node_user(("Budget user"))
node_gemini{{"Gemini API"}}

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_dashboard
node_web -->|"routes to"| node_budgetui
node_web -->|"routes to"| node_savingsui
node_web -->|"routes to"| node_adminui
node_web -->|"routes to"| node_reportsui
node_dashboard -->|"requests through"| node_clientapi
node_budgetui -->|"requests through"| node_clientapi
node_savingsui -->|"requests through"| node_clientapi
node_adminui -->|"requests through"| node_clientapi
node_reportsui -.->|"requests through"| node_clientapi
node_categoriesui -->|"fetches categories"| node_clientapi
node_dashboard -->|"opens scanner"| node_receiptui
node_receiptui -->|"uploads receipt"| node_clientapi
node_clientapi -->|"HTTP requests"| node_routes
node_app -->|"registers blueprint"| node_routes
node_app -->|"initializes"| node_database
node_routes -->|"reads and writes"| node_database
node_routes -->|"resolves categories"| node_category
node_category -->|"uses category rules"| node_categorizer
node_routes -->|"extracts receipts"| node_receiptservice
node_receiptservice -->|"requests extraction"| node_provider
node_receiptservice -->|"normalizes result"| node_schema
node_provider -->|"uses receipt schema"| node_schema
node_provider -.->|"calls OCR"| node_gemini
node_routes -->|"builds insights"| node_insights
node_routes -->|"checks anomalies"| node_anomalies
node_routes -->|"generates reports"| node_pdf
node_routes -->|"exports account"| node_account
node_routes -->|"sends account email"| node_email
node_routes -->|"enforces security"| node_auth
node_insights -.->|"summarizes spending"| node_gemini
node_pdf -.->|"optional analysis"| node_gemini

click node_app "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/app.py"
click node_web "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/App.jsx"
click node_clientapi "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/api.js"
click node_dashboard "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Dashboard.jsx"
click node_budgetui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/BudgetSetup.jsx"
click node_savingsui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Savings.jsx"
click node_adminui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_reportsui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Reports.jsx"
click node_categoriesui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/components/CategoriesContext.jsx"
click node_routes "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/routes.py"
click node_auth "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/security.py"
click node_database "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/database.py"
click node_category "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/category_service.py"
click node_categorizer "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/categorize.py"
click node_receiptui "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/components/ReceiptScanner.jsx"
click node_receiptservice "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_service.py"
click node_provider "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_providers/gemini.py"
click node_schema "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_schema.py"
click node_insights "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/insights.py"
click node_anomalies "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/anomalies.py"
click node_pdf "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/pdf_report.py"
click node_account "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/account_export.py"
click node_email "https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/email_service.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_web,node_clientapi,node_dashboard,node_budgetui,node_savingsui,node_adminui,node_reportsui,node_categoriesui,node_receiptui,node_user toneBlue
class node_app,node_routes,node_auth,node_email toneAmber
class node_database,node_category,node_categorizer,node_gemini toneMint
class node_receiptservice,node_provider,node_schema toneRose
class node_insights,node_anomalies,node_pdf,node_account toneIndigo
```

## Components

### Web client

- [React routes](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Dashboard](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Budget setup](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/BudgetSetup.jsx): `frontend/src/pages/BudgetSetup.jsx`
- [Savings view](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Savings.jsx): `frontend/src/pages/Savings.jsx`
- [Admin dashboard](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [Reports view](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`
- [Category context](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/components/CategoriesContext.jsx): `frontend/src/components/CategoriesContext.jsx`
- [Receipt scanner](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/frontend/src/components/ReceiptScanner.jsx): `frontend/src/components/ReceiptScanner.jsx`

### API and identity

- [Flask app](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/app.py): `app.py`
- [API routes](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/routes.py): `api/routes.py`
- [Authentication and security](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/security.py): `api/security.py`
- [Email service](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/email_service.py): `api/email_service.py`

### Budget and spending

- [User and expense store](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/database.py): `database.py`
- [Category services](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/category_service.py): `api/category_service.py`
- [Category rules](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/categorize.py): `api/categorize.py`

### Receipt processing

- [Receipt extraction](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_service.py): `api/receipt_service.py`
- [Gemini OCR provider](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_providers/gemini.py): `api/receipt_providers/gemini.py`
- [Receipt normalization](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/receipt_schema.py): `api/receipt_schema.py`

### Insights and exports

- [Spending insights](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/insights.py): `api/insights.py`
- [Spending anomalies](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/anomalies.py): `api/anomalies.py`
- [PDF reports](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/pdf_report.py): `api/pdf_report.py`
- [Account export](https://github.com/cedzzzzzzzzz/budget-tracker/blob/main/api/account_export.py): `api/account_export.py`

### Other components

- **Budget user**
- **Gemini API**

## Connections

- Budget user → React routes: uses
- React routes → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React routes → Budget setup: routes to (evidence: `frontend/src/App.jsx`)
- React routes → Savings view: routes to (evidence: `frontend/src/App.jsx`)
- React routes → Admin dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React routes → Reports view: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard → API client: requests through (evidence: `frontend/src/pages/Dashboard.jsx`)
- Budget setup → API client: requests through (evidence: `frontend/src/pages/BudgetSetup.jsx`)
- Savings view → API client: requests through (evidence: `frontend/src/pages/Savings.jsx`)
- Admin dashboard → API client: requests through (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- Reports view → API client: requests through
- Category context → API client: fetches categories (evidence: `frontend/src/components/CategoriesContext.jsx`)
- Dashboard → Receipt scanner: opens scanner (evidence: `frontend/src/pages/Dashboard.jsx`)
- Receipt scanner → API client: uploads receipt (evidence: `frontend/src/components/ReceiptScanner.jsx`)
- API client → API routes: HTTP requests (evidence: `frontend/src/api.js`)
- Flask app → API routes: registers blueprint (evidence: `app.py`)
- Flask app → User and expense store: initializes (evidence: `app.py`)
- API routes → User and expense store: reads and writes (evidence: `api/routes.py`)
- API routes → Category services: resolves categories (evidence: `api/routes.py`)
- Category services → Category rules: uses category rules (evidence: `api/category_service.py`)
- API routes → Receipt extraction: extracts receipts (evidence: `api/routes.py`)
- Receipt extraction → Gemini OCR provider: requests extraction (evidence: `api/receipt_service.py`)
- Receipt extraction → Receipt normalization: normalizes result (evidence: `api/receipt_service.py`)
- Gemini OCR provider → Receipt normalization: uses receipt schema (evidence: `api/receipt_providers/gemini.py`)
- Gemini OCR provider → Gemini API: calls OCR
- API routes → Spending insights: builds insights (evidence: `api/routes.py`)
- API routes → Spending anomalies: checks anomalies (evidence: `api/routes.py`)
- API routes → PDF reports: generates reports (evidence: `api/routes.py`)
- API routes → Account export: exports account (evidence: `api/routes.py`)
- API routes → Email service: sends account email (evidence: `api/routes.py`)
- API routes → Authentication and security: enforces security (evidence: `api/routes.py`)
- Spending insights → Gemini API: summarizes spending
- PDF reports → Gemini API: optional analysis
