# magnus009/budget-tracker architecture

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

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

## Overview

Budget Tracker is a local-first browser app for budgeting by cutoff (budget cycle). Users create and manage cutoffs, inspect dashboard totals, drill into category plans and transactions, then save changes locally or share cutoff data as JSON. The graph shows the app controller routing views and coordinating state, the distinct dashboard/cutoff/category stages, query and normalization layers, and IndexedDB/localStorage persistence. The README documents responsive use and cutoff JSON sharing; source excerpts show those modules and their controller connections. Other UI details are omitted where excerpts do not establish their wiring.

Main entry points: [`app.js`](https://github.com/magnus009/budget-tracker/blob/main/app.js) (App controller), [`modules/storage.js`](https://github.com/magnus009/budget-tracker/blob/main/modules/storage.js) (Storage adapter), [`modules/import-export.js`](https://github.com/magnus009/budget-tracker/blob/main/modules/import-export.js) (Cutoff JSON sharing), [`modules/queries.js`](https://github.com/magnus009/budget-tracker/blob/main/modules/queries.js) (Budget queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Budget views"]
  node_controller["App controller<br/>[app.js]"]
  node_dashboard["Cutoff dashboard<br/>[dashboard-page.js]"]
  node_cutoff_view["Cutoff overview<br/>[cutoff-page.js]"]
  node_category_view["Category plans<br/>[category-page.js]"]
end

subgraph group_domain["Budget domain"]
  node_queries["Budget queries<br/>[queries.js]"]
  node_state["State normalization<br/>[state.js]"]
  node_formatters["Display formatting<br/>[formatters.js]"]
end

subgraph group_persistence["Local persistence"]
  node_storage["Storage adapter<br/>[storage.js]"]
  node_indexeddb[("IndexedDB")]
  node_localstorage[("localStorage")]
end

subgraph group_sharing["JSON sharing"]
  node_sharing["Cutoff JSON sharing<br/>[import-export.js]"]
  node_json_file["JSON file"]
end

node_user(("Budget user"))

node_user -->|"uses"| node_controller
node_controller -->|"routes rendering"| node_dashboard
node_controller -->|"routes rendering"| node_cutoff_view
node_controller -->|"routes rendering"| node_category_view
node_controller -->|"calls"| node_queries
node_controller -->|"formats values"| node_formatters
node_dashboard -->|"gets totals"| node_queries
node_cutoff_view -->|"gets ledger totals"| node_queries
node_category_view -.->|"renders edits"| node_controller
node_controller -->|"loads and saves"| node_storage
node_storage -->|"reads and writes"| node_indexeddb
node_storage -->|"fallback reads and writes"| node_localstorage
node_storage -->|"normalizes state"| node_state
node_controller -->|"normalizes data"| node_state
node_controller -->|"imports and exports"| node_sharing
node_sharing -->|"normalizes packages"| node_state
node_sharing -->|"downloads or reads"| node_json_file
node_user -->|"shares cutoff"| node_json_file

click node_controller "https://github.com/magnus009/budget-tracker/blob/main/app.js"
click node_dashboard "https://github.com/magnus009/budget-tracker/blob/main/modules/dashboard-page.js"
click node_cutoff_view "https://github.com/magnus009/budget-tracker/blob/main/modules/cutoff-page.js"
click node_category_view "https://github.com/magnus009/budget-tracker/blob/main/modules/category-page.js"
click node_queries "https://github.com/magnus009/budget-tracker/blob/main/modules/queries.js"
click node_state "https://github.com/magnus009/budget-tracker/blob/main/modules/state.js"
click node_formatters "https://github.com/magnus009/budget-tracker/blob/main/modules/formatters.js"
click node_storage "https://github.com/magnus009/budget-tracker/blob/main/modules/storage.js"
click node_sharing "https://github.com/magnus009/budget-tracker/blob/main/modules/import-export.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_controller,node_dashboard,node_cutoff_view,node_category_view,node_user toneBlue
class node_queries,node_state,node_formatters toneAmber
class node_storage,node_indexeddb,node_localstorage toneMint
class node_sharing,node_json_file toneRose
```

## Components

### Budget views

- [App controller](https://github.com/magnus009/budget-tracker/blob/main/app.js): `app.js`
- [Cutoff dashboard](https://github.com/magnus009/budget-tracker/blob/main/modules/dashboard-page.js): `modules/dashboard-page.js`
- [Cutoff overview](https://github.com/magnus009/budget-tracker/blob/main/modules/cutoff-page.js): `modules/cutoff-page.js`
- [Category plans](https://github.com/magnus009/budget-tracker/blob/main/modules/category-page.js): `modules/category-page.js`

### Budget domain

- [Budget queries](https://github.com/magnus009/budget-tracker/blob/main/modules/queries.js): `modules/queries.js`
- [State normalization](https://github.com/magnus009/budget-tracker/blob/main/modules/state.js): `modules/state.js`
- [Display formatting](https://github.com/magnus009/budget-tracker/blob/main/modules/formatters.js): `modules/formatters.js`

### Local persistence

- [Storage adapter](https://github.com/magnus009/budget-tracker/blob/main/modules/storage.js): `modules/storage.js`
- **IndexedDB**
- **localStorage**

### JSON sharing

- [Cutoff JSON sharing](https://github.com/magnus009/budget-tracker/blob/main/modules/import-export.js): `modules/import-export.js`
- **JSON file**

### Other components

- **Budget user**

## Connections

- Budget user → App controller: uses (evidence: `README.md`)
- App controller → Cutoff dashboard: routes rendering (evidence: `app.js`)
- App controller → Cutoff overview: routes rendering (evidence: `app.js`)
- App controller → Category plans: routes rendering (evidence: `app.js`)
- App controller → Budget queries: calls (evidence: `app.js`)
- App controller → Display formatting: formats values (evidence: `app.js`)
- Cutoff dashboard → Budget queries: gets totals (evidence: `modules/dashboard-page.js`)
- Cutoff overview → Budget queries: gets ledger totals (evidence: `modules/cutoff-page.js`)
- Category plans → App controller: renders edits (evidence: `app.js`)
- App controller → Storage adapter: loads and saves (evidence: `app.js`)
- Storage adapter → IndexedDB: reads and writes (evidence: `modules/storage.js`)
- Storage adapter → localStorage: fallback reads and writes (evidence: `modules/storage.js`)
- Storage adapter → State normalization: normalizes state (evidence: `modules/storage.js`)
- App controller → State normalization: normalizes data (evidence: `app.js`)
- App controller → Cutoff JSON sharing: imports and exports (evidence: `app.js`)
- Cutoff JSON sharing → State normalization: normalizes packages (evidence: `modules/import-export.js`)
- Cutoff JSON sharing → JSON file: downloads or reads (evidence: `modules/import-export.js`)
- Budget user → JSON file: shares cutoff (evidence: `README.md`)