# spkchalla/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/spkchalla/expense-tracker
- Repository: https://github.com/spkchalla/expense-tracker

## Overview

Pocket Ledger is a mobile-first personal expense and reserve-planning PWA. Users authenticate, capture and review discretionary expenses, manage separate mandatory-need reserves and budgets, and inspect reports; offline captures queue locally and sync to the API. The backend routes requests through controllers and domain services to MongoDB models. The README documents CSV export, undo, PWA installation, and admin privacy/privilege management; several of these implementations were not sampled, so their internal links are not inferred.

Main entry points: [`client/src/app/App.jsx`](https://github.com/spkchalla/expense-tracker/blob/main/client/src/app/App.jsx) (App router), [`server/src/config/db.js`](https://github.com/spkchalla/expense-tracker/blob/main/server/src/config/db.js) (MongoDB), [`client/src/lib/api.js`](https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/api.js) (API client), [`server/src/services/dashboardService.js`](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/dashboardService.js) (Dashboard calculations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA client"]
  node_app["App router<br/>[App.jsx]"]
  node_authui["Authentication UI<br/>[AuthContext.jsx]"]
  node_dashboard["Dashboard"]
  node_needsui["Needs and reserves<br/>[NeedsPage.jsx]"]
  node_transactionsui["Transactions"]
  node_budgetsui["Budget settings"]
  node_reports["Reports and export<br/>[ReportsPage.jsx]"]
  node_adminui["Admin management"]
  node_profile["Profile and PWA<br/>[ProfilePage.jsx]"]
  node_format["Currency formatting<br/>[formatters.js]"]
  node_apiclient["API client<br/>[api.js]"]
end

subgraph group_server["API and domain"]
  node_express["Express app<br/>[app.js]"]
  node_routes["API routes<br/>[index.js]"]
  node_authservice["Authentication<br/>[authService.js]"]
  node_needservice["Reserve planning<br/>[needService.js]"]
  node_dashboardservice["Dashboard calculations"]
  node_transactionservice["Expense processing"]
  node_adminservice["Admin controls<br/>[adminService.js]"]
end

subgraph group_data["Persistent data"]
  node_mongo[("MongoDB<br/>[db.js]")]
  node_user_model["User records<br/>[User.js]"]
  node_category_model["Categories<br/>[Category.js]"]
  node_need_model["Need records<br/>[Need.js]"]
  node_contribution_model["Contributions"]
  node_transaction_model["Transactions<br/>[Transaction.js]"]
  node_budget_model["Monthly budgets<br/>[MonthlyBudget.js]"]
  node_audit_model["Admin audit logs<br/>[AdminAuditLog.js]"]
end

subgraph group_offline["Offline capture"]
  node_offlinehook["Offline sync<br/>[useOfflineSync.js]"]
  node_localdb[("Pending transaction store<br/>[db.js]")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"checks session"| node_authui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_needsui
node_app -->|"routes to"| node_transactionsui
node_app -->|"routes to"| node_budgetsui
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_adminui
node_app -->|"routes to"| node_profile
node_authui -->|"requests auth"| node_apiclient
node_transactionsui -->|"fetches and edits"| node_apiclient
node_needsui -->|"loads reserves"| node_apiclient
node_budgetsui -->|"requests budgets"| node_apiclient
node_reports -->|"requests reports"| node_apiclient
node_adminui -->|"requests admin data"| node_apiclient
node_needsui -->|"formats amounts"| node_format
node_app -->|"starts sync"| node_offlinehook
node_offlinehook -->|"queues and clears"| node_localdb
node_offlinehook -->|"syncs queued items"| node_apiclient
node_apiclient -->|"sends API requests"| node_express
node_express -->|"mounts"| node_routes
node_authservice -->|"reads and writes"| node_user_model
node_authservice -->|"seeds categories"| node_category_model
node_needservice -->|"uses records"| node_need_model
node_needservice -->|"uses records"| node_contribution_model
node_needservice -->|"uses records"| node_transaction_model
node_dashboardservice -->|"reads"| node_need_model
node_dashboardservice -->|"reads"| node_contribution_model
node_dashboardservice -->|"reads"| node_transaction_model
node_dashboardservice -->|"reads"| node_category_model
node_dashboardservice -->|"reads"| node_budget_model
node_transactionservice -.->|"processes expenses"| node_transaction_model
node_adminservice -.->|"manages audit data"| node_audit_model
node_mongo -.->|"persists"| node_user_model
node_mongo -.->|"persists"| node_category_model
node_mongo -.->|"persists"| node_need_model
node_mongo -.->|"persists"| node_contribution_model
node_mongo -.->|"persists"| node_transaction_model
node_mongo -.->|"persists"| node_budget_model
node_mongo -.->|"persists"| node_audit_model

click node_app "https://github.com/spkchalla/expense-tracker/blob/main/client/src/app/App.jsx"
click node_authui "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/auth/AuthContext.jsx"
click node_dashboard "https://github.com/spkchalla/expense-tracker/tree/main/client/src/features/dashboard"
click node_needsui "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/needs/NeedsPage.jsx"
click node_transactionsui "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/transactions/TransactionListPage.jsx"
click node_budgetsui "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/budgets/BudgetSettingsPage.jsx"
click node_reports "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/reports/ReportsPage.jsx"
click node_adminui "https://github.com/spkchalla/expense-tracker/tree/main/client/src/features/admin"
click node_profile "https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/profile/ProfilePage.jsx"
click node_format "https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/formatters.js"
click node_offlinehook "https://github.com/spkchalla/expense-tracker/blob/main/client/src/hooks/useOfflineSync.js"
click node_localdb "https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/db.js"
click node_apiclient "https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/api.js"
click node_express "https://github.com/spkchalla/expense-tracker/blob/main/server/src/app.js"
click node_routes "https://github.com/spkchalla/expense-tracker/blob/main/server/src/routes/index.js"
click node_authservice "https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/authService.js"
click node_needservice "https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/needService.js"
click node_dashboardservice "https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/dashboardService.js"
click node_transactionservice "https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/transactionService.js"
click node_adminservice "https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/adminService.js"
click node_mongo "https://github.com/spkchalla/expense-tracker/blob/main/server/src/config/db.js"
click node_user_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/User.js"
click node_category_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Category.js"
click node_need_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Need.js"
click node_contribution_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/NeedContribution.js"
click node_transaction_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Transaction.js"
click node_budget_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/MonthlyBudget.js"
click node_audit_model "https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/AdminAuditLog.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_authui,node_dashboard,node_needsui,node_transactionsui,node_budgetsui,node_reports,node_adminui,node_profile,node_format,node_apiclient,node_user toneBlue
class node_express,node_routes,node_authservice,node_needservice,node_dashboardservice,node_transactionservice,node_adminservice toneAmber
class node_mongo,node_user_model,node_category_model,node_need_model,node_contribution_model,node_transaction_model,node_budget_model,node_audit_model toneMint
class node_offlinehook,node_localdb toneRose
```

## Components

### PWA client

- [App router](https://github.com/spkchalla/expense-tracker/blob/main/client/src/app/App.jsx): `client/src/app/App.jsx`
- [Authentication UI](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/auth/AuthContext.jsx): `client/src/features/auth/AuthContext.jsx`
- [Dashboard](https://github.com/spkchalla/expense-tracker/tree/main/client/src/features/dashboard): `client/src/features/dashboard`
- [Needs and reserves](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/needs/NeedsPage.jsx): `client/src/features/needs/NeedsPage.jsx`
- [Transactions](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/transactions/TransactionListPage.jsx): `client/src/features/transactions/TransactionListPage.jsx`
- [Budget settings](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/budgets/BudgetSettingsPage.jsx): `client/src/features/budgets/BudgetSettingsPage.jsx`
- [Reports and export](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/reports/ReportsPage.jsx): `client/src/features/reports/ReportsPage.jsx`
- [Admin management](https://github.com/spkchalla/expense-tracker/tree/main/client/src/features/admin): `client/src/features/admin`
- [Profile and PWA](https://github.com/spkchalla/expense-tracker/blob/main/client/src/features/profile/ProfilePage.jsx): `client/src/features/profile/ProfilePage.jsx`
- [Currency formatting](https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/formatters.js): `client/src/lib/formatters.js`
- [API client](https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/api.js): `client/src/lib/api.js`

### API and domain

- [Express app](https://github.com/spkchalla/expense-tracker/blob/main/server/src/app.js): `server/src/app.js`
- [API routes](https://github.com/spkchalla/expense-tracker/blob/main/server/src/routes/index.js): `server/src/routes/index.js`
- [Authentication](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/authService.js): `server/src/services/authService.js`
- [Reserve planning](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/needService.js): `server/src/services/needService.js`
- [Dashboard calculations](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/dashboardService.js): `server/src/services/dashboardService.js`
- [Expense processing](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/transactionService.js): `server/src/services/transactionService.js`
- [Admin controls](https://github.com/spkchalla/expense-tracker/blob/main/server/src/services/adminService.js): `server/src/services/adminService.js`

### Persistent data

- [MongoDB](https://github.com/spkchalla/expense-tracker/blob/main/server/src/config/db.js): `server/src/config/db.js`
- [User records](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/User.js): `server/src/models/User.js`
- [Categories](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Category.js): `server/src/models/Category.js`
- [Need records](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Need.js): `server/src/models/Need.js`
- [Contributions](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/NeedContribution.js): `server/src/models/NeedContribution.js`
- [Transactions](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/Transaction.js): `server/src/models/Transaction.js`
- [Monthly budgets](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/MonthlyBudget.js): `server/src/models/MonthlyBudget.js`
- [Admin audit logs](https://github.com/spkchalla/expense-tracker/blob/main/server/src/models/AdminAuditLog.js): `server/src/models/AdminAuditLog.js`

### Offline capture

- [Offline sync](https://github.com/spkchalla/expense-tracker/blob/main/client/src/hooks/useOfflineSync.js): `client/src/hooks/useOfflineSync.js`
- [Pending transaction store](https://github.com/spkchalla/expense-tracker/blob/main/client/src/lib/db.js): `client/src/lib/db.js`

### Other components

- **User**

## Connections

- User → App router: uses (evidence: `README.md`)
- App router → Authentication UI: checks session (evidence: `client/src/app/App.jsx`)
- App router → Dashboard: routes to (evidence: `client/src/app/App.jsx`)
- App router → Needs and reserves: routes to (evidence: `client/src/app/App.jsx`)
- App router → Transactions: routes to (evidence: `client/src/app/App.jsx`)
- App router → Budget settings: routes to (evidence: `client/src/app/App.jsx`)
- App router → Reports and export: routes to (evidence: `client/src/app/App.jsx`)
- App router → Admin management: routes to (evidence: `client/src/app/App.jsx`)
- App router → Profile and PWA: routes to (evidence: `client/src/app/App.jsx`)
- Authentication UI → API client: requests auth (evidence: `client/src/features/auth/AuthContext.jsx`)
- Transactions → API client: fetches and edits (evidence: `client/src/features/transactions/TransactionListPage.jsx`)
- Needs and reserves → API client: loads reserves (evidence: `client/src/features/needs/NeedsPage.jsx`)
- Budget settings → API client: requests budgets (evidence: `client/src/features/budgets/BudgetSettingsPage.jsx`)
- Reports and export → API client: requests reports (evidence: `client/src/features/reports/ReportsPage.jsx`)
- Admin management → API client: requests admin data (evidence: `client/src/features/admin/AdminPage.jsx`)
- Needs and reserves → Currency formatting: formats amounts (evidence: `client/src/features/needs/NeedsPage.jsx`)
- App router → Offline sync: starts sync (evidence: `client/src/app/App.jsx`)
- Offline sync → Pending transaction store: queues and clears (evidence: `client/src/hooks/useOfflineSync.js`)
- Offline sync → API client: syncs queued items (evidence: `client/src/hooks/useOfflineSync.js`)
- API client → Express app: sends API requests (evidence: `README.md`)
- Express app → API routes: mounts (evidence: `server/src/app.js`)
- Authentication → User records: reads and writes (evidence: `server/src/services/authService.js`)
- Authentication → Categories: seeds categories (evidence: `server/src/services/authService.js`)
- Reserve planning → Need records: uses records (evidence: `server/src/services/needService.js`)
- Reserve planning → Contributions: uses records (evidence: `server/src/services/needService.js`)
- Reserve planning → Transactions: uses records (evidence: `server/src/services/needService.js`)
- Dashboard calculations → Need records: reads (evidence: `server/src/services/dashboardService.js`)
- Dashboard calculations → Contributions: reads (evidence: `server/src/services/dashboardService.js`)
- Dashboard calculations → Transactions: reads (evidence: `server/src/services/dashboardService.js`)
- Dashboard calculations → Categories: reads (evidence: `server/src/services/dashboardService.js`)
- Dashboard calculations → Monthly budgets: reads (evidence: `server/src/services/dashboardService.js`)
- Expense processing → Transactions: processes expenses
- Admin controls → Admin audit logs: manages audit data
- MongoDB → User records: persists
- MongoDB → Categories: persists
- MongoDB → Need records: persists
- MongoDB → Contributions: persists
- MongoDB → Transactions: persists
- MongoDB → Monthly budgets: persists
- MongoDB → Admin audit logs: persists
