# fuzailsami/budger-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/fuzailsami/budger-tracker
- Repository: https://github.com/fuzailsami/budger-tracker

## Overview

Budget Tracker is a shared household budget app: household members sign in or join with an invite code, then manage a common expense ledger, budget settings and categories, and review spending through history, analytics and Excel export. The client coordinates authentication and data loading, calls the API, and presents those distinct views. The API routes authenticate requests and use PostgreSQL for household data. The README documents several user-facing capabilities whose route internals were not sampled; those connections are shown only where documented or supported by the source index.

Main entry points: [`Budget_Tracker/client/src/App.jsx`](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/App.jsx) (App coordinator), [`Budget_Tracker/api/index.js`](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/api/index.js) (Express API app), [`Budget_Tracker/server/src/db.js`](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/db.js) (PostgreSQL), [`Budget_Tracker/server/src/middleware/requireAuth.js`](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/middleware/requireAuth.js) (Auth middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_authscreen["Sign-in screen<br/>[AuthScreen.jsx]"]
  node_ledger["Expense ledger<br/>[LedgerTab.jsx]"]
  node_history["History and export<br/>[HistoryTab.jsx]"]
  node_analytics["Spending analytics<br/>[AnalyticsTab.jsx]"]
  node_settings["Budget settings<br/>[SettingsTab.jsx]"]
  node_shared["Shared UI and periods<br/>[shared.jsx]"]
end

subgraph group_identity["Identity and access"]
  node_authcontext["Session context<br/>[AuthContext.jsx]"]
  node_authroutes["Account routes<br/>[auth.js]"]
  node_tokens["JWT services<br/>[auth.js]"]
  node_guard["Auth middleware<br/>[requireAuth.js]"]
end

subgraph group_api["Budget API"]
  node_clientapi["API client<br/>[api.js]"]
  node_apiapp["Express API app<br/>[index.js]"]
  node_expenses["Expense routes<br/>[expenses.js]"]
  node_categories["Category routes<br/>[categories.js]"]
  node_config["Budget and invites<br/>[config.js]"]
  node_export["Excel export<br/>[export.js]"]
  node_period["Period calculations<br/>[period.js]"]
end

subgraph group_storage["Persistence"]
  node_database[("PostgreSQL<br/>[db.js]")]
end

node_member(("Household member"))

node_member -->|"uses"| node_app
node_app -->|"shows"| node_authscreen
node_app -->|"shows"| node_ledger
node_app -->|"shows"| node_history
node_app -->|"shows"| node_analytics
node_app -->|"shows"| node_settings
node_app -->|"reads session"| node_authcontext
node_app -->|"loads and updates"| node_clientapi
node_authscreen -->|"submits credentials"| node_authcontext
node_authcontext -->|"requests identity"| node_clientapi
node_app -->|"uses period and UI helpers"| node_shared
node_ledger -->|"uses display helpers"| node_shared
node_history -->|"uses display helpers"| node_shared
node_analytics -->|"uses display helpers"| node_shared
node_settings -->|"uses display helpers"| node_shared
node_clientapi -->|"calls API"| node_apiapp
node_apiapp -->|"mounts"| node_authroutes
node_apiapp -->|"mounts"| node_config
node_apiapp -->|"mounts"| node_categories
node_apiapp -->|"mounts"| node_expenses
node_apiapp -->|"mounts"| node_export
node_authroutes -->|"signs tokens"| node_tokens
node_authroutes -->|"reads and writes accounts"| node_database
node_authroutes -->|"protects identity lookup"| node_guard
node_guard -->|"verifies tokens"| node_tokens
node_guard -->|"loads household membership"| node_database
node_expenses -->|"requires authentication"| node_guard
node_expenses -->|"reads and writes expenses"| node_database
node_categories -->|"requires authentication"| node_guard
node_categories -->|"manages categories"| node_database
node_config -->|"reads and updates settings"| node_database
node_export -->|"requires authentication"| node_guard
node_export -->|"reads expenses"| node_database
node_export -->|"groups export periods"| node_period
node_apiapp -->|"initializes when configured"| node_database

click node_app "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/App.jsx"
click node_authscreen "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/AuthScreen.jsx"
click node_ledger "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/LedgerTab.jsx"
click node_history "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/HistoryTab.jsx"
click node_analytics "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/AnalyticsTab.jsx"
click node_settings "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/SettingsTab.jsx"
click node_shared "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/shared.jsx"
click node_authcontext "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/context/AuthContext.jsx"
click node_clientapi "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/api.js"
click node_apiapp "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/api/index.js"
click node_authroutes "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/auth.js"
click node_tokens "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/auth.js"
click node_guard "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/middleware/requireAuth.js"
click node_expenses "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/expenses.js"
click node_categories "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/categories.js"
click node_config "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/config.js"
click node_export "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/export.js"
click node_period "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/period.js"
click node_database "https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/db.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_authscreen,node_ledger,node_history,node_analytics,node_settings,node_shared toneBlue
class node_authcontext,node_authroutes,node_tokens,node_guard toneAmber
class node_clientapi,node_apiapp,node_expenses,node_categories,node_config,node_export,node_period toneMint
class node_database toneRose
class node_member toneIndigo
```

## Components

### Client experience

- [App coordinator](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/App.jsx): `Budget_Tracker/client/src/App.jsx`
- [Sign-in screen](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/AuthScreen.jsx): `Budget_Tracker/client/src/components/AuthScreen.jsx`
- [Expense ledger](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/LedgerTab.jsx): `Budget_Tracker/client/src/components/LedgerTab.jsx`
- [History and export](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/HistoryTab.jsx): `Budget_Tracker/client/src/components/HistoryTab.jsx`
- [Spending analytics](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/AnalyticsTab.jsx): `Budget_Tracker/client/src/components/AnalyticsTab.jsx`
- [Budget settings](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/components/SettingsTab.jsx): `Budget_Tracker/client/src/components/SettingsTab.jsx`
- [Shared UI and periods](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/shared.jsx): `Budget_Tracker/client/src/shared.jsx`

### Identity and access

- [Session context](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/context/AuthContext.jsx): `Budget_Tracker/client/src/context/AuthContext.jsx`
- [Account routes](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/auth.js): `Budget_Tracker/server/src/routes/auth.js`
- [JWT services](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/auth.js): `Budget_Tracker/server/src/auth.js`
- [Auth middleware](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/middleware/requireAuth.js): `Budget_Tracker/server/src/middleware/requireAuth.js`

### Budget API

- [API client](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/client/src/api.js): `Budget_Tracker/client/src/api.js`
- [Express API app](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/api/index.js): `Budget_Tracker/api/index.js`
- [Expense routes](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/expenses.js): `Budget_Tracker/server/src/routes/expenses.js`
- [Category routes](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/categories.js): `Budget_Tracker/server/src/routes/categories.js`
- [Budget and invites](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/config.js): `Budget_Tracker/server/src/routes/config.js`
- [Excel export](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/routes/export.js): `Budget_Tracker/server/src/routes/export.js`
- [Period calculations](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/period.js): `Budget_Tracker/server/src/period.js`

### Persistence

- [PostgreSQL](https://github.com/fuzailsami/budger-tracker/blob/master/Budget_Tracker/server/src/db.js): `Budget_Tracker/server/src/db.js`

### Other components

- **Household member**

## Connections

- Household member → App coordinator: uses (evidence: `README.md`)
- App coordinator → Sign-in screen: shows (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → Expense ledger: shows (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → History and export: shows (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → Spending analytics: shows (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → Budget settings: shows (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → Session context: reads session (evidence: `Budget_Tracker/client/src/App.jsx`)
- App coordinator → API client: loads and updates (evidence: `Budget_Tracker/client/src/App.jsx`)
- Sign-in screen → Session context: submits credentials (evidence: `Budget_Tracker/client/src/components/AuthScreen.jsx`)
- Session context → API client: requests identity (evidence: `Budget_Tracker/client/src/context/AuthContext.jsx`)
- App coordinator → Shared UI and periods: uses period and UI helpers (evidence: `Budget_Tracker/client/src/App.jsx`)
- Expense ledger → Shared UI and periods: uses display helpers (evidence: `Budget_Tracker/client/src/components/LedgerTab.jsx`)
- History and export → Shared UI and periods: uses display helpers (evidence: `Budget_Tracker/client/src/components/HistoryTab.jsx`)
- Spending analytics → Shared UI and periods: uses display helpers (evidence: `Budget_Tracker/client/src/components/AnalyticsTab.jsx`)
- Budget settings → Shared UI and periods: uses display helpers (evidence: `Budget_Tracker/client/src/components/SettingsTab.jsx`)
- API client → Express API app: calls API (evidence: `README.md`)
- Express API app → Account routes: mounts (evidence: `Budget_Tracker/api/index.js`)
- Express API app → Budget and invites: mounts (evidence: `Budget_Tracker/api/index.js`)
- Express API app → Category routes: mounts (evidence: `Budget_Tracker/api/index.js`)
- Express API app → Expense routes: mounts (evidence: `Budget_Tracker/api/index.js`)
- Express API app → Excel export: mounts (evidence: `Budget_Tracker/api/index.js`)
- Account routes → JWT services: signs tokens (evidence: `Budget_Tracker/server/src/routes/auth.js`)
- Account routes → PostgreSQL: reads and writes accounts (evidence: `Budget_Tracker/server/src/routes/auth.js`)
- Account routes → Auth middleware: protects identity lookup (evidence: `Budget_Tracker/server/src/routes/auth.js`)
- Auth middleware → JWT services: verifies tokens (evidence: `Budget_Tracker/server/src/middleware/requireAuth.js`)
- Auth middleware → PostgreSQL: loads household membership (evidence: `Budget_Tracker/server/src/middleware/requireAuth.js`)
- Expense routes → Auth middleware: requires authentication (evidence: `Budget_Tracker/server/src/routes/expenses.js`)
- Expense routes → PostgreSQL: reads and writes expenses (evidence: `Budget_Tracker/server/src/routes/expenses.js`)
- Category routes → Auth middleware: requires authentication (evidence: `Budget_Tracker/server/src/routes/categories.js`)
- Category routes → PostgreSQL: manages categories (evidence: `Budget_Tracker/server/src/routes/categories.js`)
- Budget and invites → PostgreSQL: reads and updates settings (evidence: `Budget_Tracker/server/src/routes/config.js`)
- Excel export → Auth middleware: requires authentication (evidence: `Budget_Tracker/server/src/routes/export.js`)
- Excel export → PostgreSQL: reads expenses (evidence: `Budget_Tracker/server/src/routes/export.js`)
- Excel export → Period calculations: groups export periods (evidence: `Budget_Tracker/server/src/routes/export.js`)
- Express API app → PostgreSQL: initializes when configured (evidence: `Budget_Tracker/api/index.js`)
