# bladureau/budget-app architecture

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

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

## Overview

Budget is a local-first, single-user personal budgeting app: users maintain monthly income, subscriptions, expenses and envelopes, then review available funds and forecasts. The browser persists locally and can synchronize to a self-hosted server, with conflict handling; optional read-only bank sync imports classified card transactions. The graph preserves those domain stages and the bank authorization/import path. Evidence is limited to the README and SOURCE INDEX references plus shown excerpts; unsampled UI and sync details are represented only where documented.

Main entry points: [`src/features/budget/budget-provider.tsx`](https://github.com/bladureau/budget-app/blob/master/src/features/budget/budget-provider.tsx) (Budget state), [`src/features/banking/client.ts`](https://github.com/bladureau/budget-app/blob/master/src/features/banking/client.ts) (Bank API client), [`src/app/api/banking/connect/route.ts`](https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/connect/route.ts) (Bank authorization flow), [`src/app/api/banking/operations/route.ts`](https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/operations/route.ts) (Operation retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_budget["Budget workspace"]
  node_app["Budget interface<br/>[page.tsx]"]
  node_provider["Budget state"]
  node_calculations["Budget calculations<br/>[calculs.ts]"]
  node_budget_views["Monthly views"]
  node_income_subscriptions["Income and subscriptions"]
  node_expense_journal["Expense journal"]
  node_envelopes["Spending envelopes<br/>[envelopes.ts]"]
  node_transfer["Import and export<br/>[transfer.ts]"]
end

subgraph group_clientdata["Client data"]
  node_local_storage[("Browser persistence<br/>[storage.ts]")]
  node_document_validation["Document validation<br/>[budget-document.ts]"]
  node_sync_client["Sync client<br/>[sync.ts]"]
  node_sync_metadata["Sync metadata<br/>[sync-metadata.ts]"]
end

subgraph group_serverdata["Self-hosted storage"]
  node_budget_api["Budget API<br/>[route.ts]"]
  node_authorization["Device authorization<br/>[authorization.ts]"]
  node_budget_store[("Server budget store<br/>[budget-store.ts]")]
  node_atomic_file["Atomic file writes<br/>[atomic-file.ts]"]
end

subgraph group_banking["Bank sync"]
  node_bank_panel["Bank controls<br/>[bank-panel.tsx]"]
  node_bank_client["Bank API client<br/>[client.ts]"]
  node_bank_routes["Bank API routes"]
  node_bank_connect["Bank authorization flow<br/>[route.ts]"]
  node_bank_callback["Bank callback<br/>[route.ts]"]
  node_pending_auth["Pending authorization<br/>[pending-auth.ts]"]
  node_enable_banking["Enable Banking<br/>[enable-banking.ts]"]
  node_bank_operations["Operation retrieval<br/>[route.ts]"]
  node_bank_store[("Bank state store<br/>[banking-store.ts]")]
  node_bank_inbox["Unclassified transactions<br/>[inbox.tsx]"]
  node_bank_rules["Transaction rules<br/>[rules.ts]"]
  node_bank_status["Bank status<br/>[bank-status.ts]"]
end

node_user(("Budget user"))
node_bank(("Connected bank"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_provider
node_provider -->|"supplies state"| node_budget_views
node_user -->|"maintains"| node_income_subscriptions
node_user -->|"records expenses"| node_expense_journal
node_user -->|"sets limits"| node_envelopes
node_provider -->|"uses"| node_calculations
node_provider -->|"loads and saves"| node_local_storage
node_local_storage -->|"validates documents"| node_document_validation
node_provider -->|"reads and writes"| node_sync_metadata
node_provider -->|"pushes and pulls"| node_sync_client
node_user -->|"backs up or restores"| node_transfer
node_sync_client -->|"requests sync"| node_budget_api
node_budget_api -->|"checks access"| node_authorization
node_budget_api -->|"reads and writes"| node_budget_store
node_budget_store -->|"writes atomically"| node_atomic_file
node_user -->|"connects and syncs"| node_bank_panel
node_bank_panel -->|"requests bank actions"| node_bank_client
node_bank_client -->|"starts connection"| node_bank_connect
node_bank_client -->|"fetches operations"| node_bank_operations
node_bank_connect -->|"checks access"| node_authorization
node_bank_connect -->|"creates state"| node_pending_auth
node_bank_connect -->|"requests authorization"| node_enable_banking
node_bank -->|"returns authorization"| node_bank_callback
node_bank_callback -->|"consumes state"| node_pending_auth
node_bank_callback -->|"completes connection"| node_enable_banking
node_bank_operations -->|"checks access"| node_authorization
node_bank_operations -->|"fetches transactions"| node_enable_banking
node_bank_operations -->|"reads and updates"| node_bank_store
node_bank_client -.->|"provides transactions"| node_bank_inbox
node_bank_inbox -.->|"classifies transactions"| node_bank_rules
node_bank_panel -->|"displays status"| node_bank_status
node_provider -->|"imports operations"| node_bank_client

click node_app "https://github.com/bladureau/budget-app/blob/master/src/app/page.tsx"
click node_provider "https://github.com/bladureau/budget-app/blob/master/src/features/budget/budget-provider.tsx"
click node_calculations "https://github.com/bladureau/budget-app/blob/master/src/features/budget/calculs.ts"
click node_budget_views "https://github.com/bladureau/budget-app/tree/master/src/features/budget/components"
click node_income_subscriptions "https://github.com/bladureau/budget-app/tree/master/src/features/budget/components"
click node_expense_journal "https://github.com/bladureau/budget-app/blob/master/src/features/budget/components/expense-journal.tsx"
click node_envelopes "https://github.com/bladureau/budget-app/blob/master/src/features/budget/envelopes.ts"
click node_transfer "https://github.com/bladureau/budget-app/blob/master/src/features/budget/transfer.ts"
click node_local_storage "https://github.com/bladureau/budget-app/blob/master/src/lib/storage.ts"
click node_document_validation "https://github.com/bladureau/budget-app/blob/master/src/lib/budget-document.ts"
click node_sync_client "https://github.com/bladureau/budget-app/blob/master/src/features/budget/sync.ts"
click node_sync_metadata "https://github.com/bladureau/budget-app/blob/master/src/lib/sync-metadata.ts"
click node_budget_api "https://github.com/bladureau/budget-app/blob/master/src/app/api/budget/route.ts"
click node_authorization "https://github.com/bladureau/budget-app/blob/master/src/lib/server/authorization.ts"
click node_budget_store "https://github.com/bladureau/budget-app/blob/master/src/lib/server/budget-store.ts"
click node_atomic_file "https://github.com/bladureau/budget-app/blob/master/src/lib/server/atomic-file.ts"
click node_bank_panel "https://github.com/bladureau/budget-app/blob/master/src/features/banking/components/bank-panel.tsx"
click node_bank_client "https://github.com/bladureau/budget-app/blob/master/src/features/banking/client.ts"
click node_bank_routes "https://github.com/bladureau/budget-app/tree/master/src/app/api/banking"
click node_bank_connect "https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/connect/route.ts"
click node_bank_callback "https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/callback/route.ts"
click node_pending_auth "https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/pending-auth.ts"
click node_enable_banking "https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/enable-banking.ts"
click node_bank_operations "https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/operations/route.ts"
click node_bank_store "https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/banking-store.ts"
click node_bank_inbox "https://github.com/bladureau/budget-app/blob/master/src/features/banking/components/inbox.tsx"
click node_bank_rules "https://github.com/bladureau/budget-app/blob/master/src/features/banking/rules.ts"
click node_bank_status "https://github.com/bladureau/budget-app/blob/master/src/features/banking/bank-status.ts"

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_provider,node_calculations,node_budget_views,node_income_subscriptions,node_expense_journal,node_envelopes,node_transfer,node_user toneBlue
class node_local_storage,node_document_validation,node_sync_client,node_sync_metadata toneAmber
class node_budget_api,node_authorization,node_budget_store,node_atomic_file toneMint
class node_bank_panel,node_bank_client,node_bank_routes,node_bank_connect,node_bank_callback,node_pending_auth,node_enable_banking,node_bank_operations,node_bank_store,node_bank_inbox,node_bank_rules,node_bank_status toneRose
class node_bank toneIndigo
```

## Components

### Budget workspace

- [Budget interface](https://github.com/bladureau/budget-app/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [Budget state](https://github.com/bladureau/budget-app/blob/master/src/features/budget/budget-provider.tsx): `src/features/budget/budget-provider.tsx`
- [Budget calculations](https://github.com/bladureau/budget-app/blob/master/src/features/budget/calculs.ts): `src/features/budget/calculs.ts`
- [Monthly views](https://github.com/bladureau/budget-app/tree/master/src/features/budget/components): `src/features/budget/components`
- [Income and subscriptions](https://github.com/bladureau/budget-app/tree/master/src/features/budget/components): `src/features/budget/components`
- [Expense journal](https://github.com/bladureau/budget-app/blob/master/src/features/budget/components/expense-journal.tsx): `src/features/budget/components/expense-journal.tsx`
- [Spending envelopes](https://github.com/bladureau/budget-app/blob/master/src/features/budget/envelopes.ts): `src/features/budget/envelopes.ts`
- [Import and export](https://github.com/bladureau/budget-app/blob/master/src/features/budget/transfer.ts): `src/features/budget/transfer.ts`

### Client data

- [Browser persistence](https://github.com/bladureau/budget-app/blob/master/src/lib/storage.ts): `src/lib/storage.ts`
- [Document validation](https://github.com/bladureau/budget-app/blob/master/src/lib/budget-document.ts): `src/lib/budget-document.ts`
- [Sync client](https://github.com/bladureau/budget-app/blob/master/src/features/budget/sync.ts): `src/features/budget/sync.ts`
- [Sync metadata](https://github.com/bladureau/budget-app/blob/master/src/lib/sync-metadata.ts): `src/lib/sync-metadata.ts`

### Self-hosted storage

- [Budget API](https://github.com/bladureau/budget-app/blob/master/src/app/api/budget/route.ts): `src/app/api/budget/route.ts`
- [Device authorization](https://github.com/bladureau/budget-app/blob/master/src/lib/server/authorization.ts): `src/lib/server/authorization.ts`
- [Server budget store](https://github.com/bladureau/budget-app/blob/master/src/lib/server/budget-store.ts): `src/lib/server/budget-store.ts`
- [Atomic file writes](https://github.com/bladureau/budget-app/blob/master/src/lib/server/atomic-file.ts): `src/lib/server/atomic-file.ts`

### Bank sync

- [Bank controls](https://github.com/bladureau/budget-app/blob/master/src/features/banking/components/bank-panel.tsx): `src/features/banking/components/bank-panel.tsx`
- [Bank API client](https://github.com/bladureau/budget-app/blob/master/src/features/banking/client.ts): `src/features/banking/client.ts`
- [Bank API routes](https://github.com/bladureau/budget-app/tree/master/src/app/api/banking): `src/app/api/banking`
- [Bank authorization flow](https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/connect/route.ts): `src/app/api/banking/connect/route.ts`
- [Bank callback](https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/callback/route.ts): `src/app/api/banking/callback/route.ts`
- [Pending authorization](https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/pending-auth.ts): `src/lib/server/banking/pending-auth.ts`
- [Enable Banking](https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/enable-banking.ts): `src/lib/server/banking/enable-banking.ts`
- [Operation retrieval](https://github.com/bladureau/budget-app/blob/master/src/app/api/banking/operations/route.ts): `src/app/api/banking/operations/route.ts`
- [Bank state store](https://github.com/bladureau/budget-app/blob/master/src/lib/server/banking/banking-store.ts): `src/lib/server/banking/banking-store.ts`
- [Unclassified transactions](https://github.com/bladureau/budget-app/blob/master/src/features/banking/components/inbox.tsx): `src/features/banking/components/inbox.tsx`
- [Transaction rules](https://github.com/bladureau/budget-app/blob/master/src/features/banking/rules.ts): `src/features/banking/rules.ts`
- [Bank status](https://github.com/bladureau/budget-app/blob/master/src/features/banking/bank-status.ts): `src/features/banking/bank-status.ts`

### Other components

- **Budget user**
- **Connected bank**

## Connections

- Budget user → Budget interface: uses (evidence: `README.md`)
- Budget interface → Budget state: renders (evidence: `src/app/page.tsx`)
- Budget state → Monthly views: supplies state (evidence: `src/features/budget/budget-provider.tsx`)
- Budget user → Income and subscriptions: maintains (evidence: `README.md`)
- Budget user → Expense journal: records expenses (evidence: `README.md`)
- Budget user → Spending envelopes: sets limits (evidence: `README.md`)
- Budget state → Budget calculations: uses (evidence: `src/features/budget/budget-provider.tsx`)
- Budget state → Browser persistence: loads and saves (evidence: `src/features/budget/budget-provider.tsx`)
- Browser persistence → Document validation: validates documents (evidence: `src/lib/storage.ts`)
- Budget state → Sync metadata: reads and writes (evidence: `src/features/budget/budget-provider.tsx`)
- Budget state → Sync client: pushes and pulls (evidence: `src/features/budget/budget-provider.tsx`)
- Budget user → Import and export: backs up or restores (evidence: `README.md`)
- Sync client → Budget API: requests sync
- Budget API → Device authorization: checks access (evidence: `src/app/api/budget/route.ts`)
- Budget API → Server budget store: reads and writes (evidence: `src/app/api/budget/route.ts`)
- Server budget store → Atomic file writes: writes atomically (evidence: `src/lib/server/budget-store.ts`)
- Budget user → Bank controls: connects and syncs (evidence: `README.md`)
- Bank controls → Bank API client: requests bank actions (evidence: `src/features/banking/components/bank-panel.tsx`)
- Bank API client → Bank authorization flow: starts connection (evidence: `src/features/banking/client.ts`)
- Bank API client → Operation retrieval: fetches operations (evidence: `src/features/banking/client.ts`)
- Bank authorization flow → Device authorization: checks access (evidence: `src/app/api/banking/connect/route.ts`)
- Bank authorization flow → Pending authorization: creates state (evidence: `src/app/api/banking/connect/route.ts`)
- Bank authorization flow → Enable Banking: requests authorization (evidence: `src/app/api/banking/connect/route.ts`)
- Connected bank → Bank callback: returns authorization (evidence: `README.md`)
- Bank callback → Pending authorization: consumes state (evidence: `src/app/api/banking/callback/route.ts`)
- Bank callback → Enable Banking: completes connection (evidence: `src/app/api/banking/callback/route.ts`)
- Operation retrieval → Device authorization: checks access (evidence: `src/app/api/banking/operations/route.ts`)
- Operation retrieval → Enable Banking: fetches transactions (evidence: `src/app/api/banking/operations/route.ts`)
- Operation retrieval → Bank state store: reads and updates (evidence: `src/app/api/banking/operations/route.ts`)
- Bank API client → Unclassified transactions: provides transactions
- Unclassified transactions → Transaction rules: classifies transactions
- Bank controls → Bank status: displays status (evidence: `src/features/banking/components/bank-panel.tsx`)
- Budget state → Bank API client: imports operations (evidence: `src/features/budget/budget-provider.tsx`)
