# jusail-dev/personal-budget-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/jusail-dev/personal-budget-tracker
- Repository: https://github.com/jusail-dev/personal-budget-tracker

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is a **single-page, front-end-only web application** (vanilla HTML/CSS/JS) called **Personal Budget Tracker**. There is **no backend** and **no server-side database**. Persistence is handled via the **browser’s localStorage**, and import/export is done via **JSON files**.

So your “system” is primarily:
- A **Browser UI (DOM)** + styling
- A **client-side application layer (script.js)** that manages state, calculations, and persistence
- A **persistence layer (localStorage)** and **file import/export (JSON)**

##### File structure analysis (map files to components)
Top-level files:
- `index.html` → UI shell / DOM structure / entry point
- `style.css` → presentation layer
- `script.js` → application logic (state, event handling, calculations, storage, import/export)
- `README.md` → feature intent and constraints (no backend)
- `Structure and Concept.txt` → likely internal notes describing conceptual design (use this to validate modules/responsibilities if it outlines them)

##### What the README implies architecturally
Key architectural signals:
- “DOM manipulation” → event-driven UI updates
- “JSON / localStorage” → state serialization/deserialization
- “Automatic balance calculation” → derived/computed state
- “Export budget data as JSON / Import JSON data” → file I/O via browser APIs (Blob, FileReader, download link, etc.)

- **UI events** (add entry, import, export)
- **State model** (list of transactions, totals)
- **Computation pipeline** (recompute totals/balance on changes)
- **Persistence pipeline** (save/load to localStorage)
- **Import/export pipeline** (JSON parse/stringify; file read/write)

##### Browser / Runtime
- Hosts the app, DOM, localStorage, File APIs

##### UI Layer (index.html + style.css)
- Screens/sections: entry form, transaction list/table, totals/balance display
- Buttons/actions: add, delete/edit (if present), export, import

- **Event Handlers / Controller-ish functions**
- Handle user clicks/submits, file selection, etc.
- **State Model**
- In-memory representation of entries (income/expense items)
- **Computation / Budget Engine**
- Calculate total income, total expenses, balance
- **Rendering / View Update functions**
- Update DOM list + totals display
- **Persistence Adapter**
- Serialize/deserialize to/from localStorage (JSON)
- **Import/Export Adapter**
- Export: state → JSON string → downloadable file
- Import: file → JSON parse → state restore → persist → rerender

##### External Artifact: JSON file
- Represents exported data and imported input

**Startup / Load**
- Browser loads `index.html` → loads `style.css` + `script.js`
- `script.js` → reads localStorage → deserializes JSON → initializes in-memory state → renders UI

**Add Entry flow**
- User submits “Add income/expense” form → Event handler
- Event handler → validates input → updates state model
- State model update → triggers recompute totals/balance
- Then → rerender UI
- Then → persist state to localStorage (JSON stringify)

**Import flow**
- User selects JSON file → FileReader → JSON parse
- Parsed data → state model replace/merge
- Then → recompute → rerender → persist to localStorage

**Export flow**
- User clicks Export → state model → JSON stringify
- JSON string → Blob/download → produces JSON file

**Optional flows (only include if present in script.js)**
- Delete/edit entry: UI action → event handler → state change → recompute → render → persist
- Clear all: same pattern

##### Architectural patterns/design principles actually used here
- **Event-driven UI** (DOM events drive state changes)
- **Unidirectional update loop** (User Action → State Update → Compute → Render → Persist)
- **Local persistence** via **localStorage** (client-side “database”)
- **Serialization boundary** (in-memory objects ↔ JSON string ↔ localStorage / file)

- View: HTML/CSS + render functions
- Controller: event handlers
- Model: in-memory transactions + totals

##### Relevant technologies explicitly
- Vanilla JS (no framework)
- Browser DOM APIs
- localStorage API
- JSON (stringify/parse)
- File APIs (FileReader / Blob / download link) for import/export

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External actor
  %% =========================
  U["User"]:::external

  %% =========================
  %% Client runtime boundary
  %% =========================
  subgraph "User's Browser (Client Runtime)"
    direction TB

    DOM["Browser DOM + Event System"]:::runtime
    FileAPI["Browser File APIs (FileReader / Blob / Download Link)"]:::runtime
    JSONAPI["JSON (parse/stringify)"]:::runtime

    subgraph "UI Layer"
      direction TB
      HTML["index.html (UI Shell / DOM Structure)"]:::ui
      CSS["style.css (Presentation / Styling)"]:::ui
      UIViews["UI Sections (Entry Form / Transaction List / Totals Display)"]:::ui
    end

    subgraph "App Logic Layer (Vanilla JS)"
      direction TB
      JS["script.js (Application Logic)"]:::code

      EH["Event Handlers (submit/click/change)"]:::code
      VAL["Validation + Normalization"]:::code
      STATE["Transaction State (in-memory array of entries)"]:::state
      CALC["Budget Engine (income/expense totals + balance)"]:::code
      RENDER["Renderer (DOM updates)"]:::code
      STORE["Storage Adapter (localStorage read/write)"]:::adapter
      IMEX["Import/Export Adapter (JSON file)"]:::adapter
    end

    DOCS["Project Docs / Intent"]:::docs
    README["README.md (Constraints: no backend; localStorage/JSON)"]:::docs
    NOTES["Structure and Concept.txt (Design notes / responsibilities)"]:::docs
  end

  %% =========================
  %% Persistence + artifacts (outside code modules)
  %% =========================
  LS[("localStorage (Persistent in-browser key/value store)")]:::storage
  JSONFILE["JSON File (portable import/export artifact)"]:::file

  %% =========================
  %% Startup / boot sequence
  %% =========================
  U -->|"opens_page"| HTML
  HTML -->|"loads"| CSS
  HTML -->|"loads"| JS

  JS -->|"registers_listeners"| EH
  EH -->|"binds_to"| DOM

  JS -->|"startup_load"| STORE
  STORE -->|"read"| LS
  STORE -->|"deserialize"| JSONAPI
  JSONAPI -->|"init_state"| STATE
  STATE -->|"recalculate_totals"| CALC
  CALC -->|"computed_values"| RENDER
  RENDER -->|"render_to_DOM"| UIViews

  %% =========================
  %% Unidirectional update loop (core pattern)
  %% =========================
  UIViews -->|"dispatch_event"| DOM
  DOM -->|"event_callback"| EH
  EH -->|"validate_input"| VAL
  VAL -->|"update_model"| STATE
  STATE -->|"recalculate_totals"| CALC
  CALC -->|"render_update"| RENDER
  RENDER -->|"update_UI"| UIViews
  STATE -->|"persist_state"| STORE
  STORE -->|"stringify"| JSONAPI
  STORE -->|"write"| LS

  %% =========================
  %% Import flow
  %% =========================
  UIViews -->|"select_file(import)"| EH
  EH -->|"read_file"| FileAPI
  FileAPI -->|"file_text"| IMEX
  IMEX -->|"parse"| JSONAPI
  JSONAPI -->|"replace_or_merge_state"| STATE
  STATE -->|"recalculate_totals"| CALC
  CALC -->|"rerender"| RENDER
  RENDER -->|"update_UI"| UIViews
  STATE -->|"persist_state"| STORE
  STORE -->|"write"| LS

  %% =========================
  %% Export flow
  %% =========================
  UIViews -->|"click_export"| EH
  EH -->|"export_request"| IMEX
  IMEX -->|"stringify"| JSONAPI
  JSONAPI -->|"json_string"| IMEX
  IMEX -->|"create_download(Blob/link)"| FileAPI
  FileAPI -->|"save_as"| JSONFILE

  %% =========================
  %% Documentation relationships (intent/constraints)
  %% =========================
  DOCS -->|"documents_constraints"| README
  DOCS -->|"documents_design_notes"| NOTES
  README -->|"guides_architecture"| JS
  NOTES -->|"guides_module_split"| JS

  %% =========================
  %% Legend (vertical)
  %% =========================
  subgraph "Legend"
    direction TB
    L1["Blue = Code / Modules"]:::code
    L2["Green = UI (HTML/CSS/Views)"]:::ui
    L3["Purple = In-memory State"]:::state
    L4["Gray Cylinder = Persistence (localStorage)"]:::storage
    L5["White Document = JSON File Artifact"]:::file
    L6["Yellow = Browser Runtime APIs"]:::runtime
    L7["Light = Documentation"]:::docs
  end

  %% =========================
  %% Click events (mapped components)
  %% =========================
  click HTML "https://github.com/jusail-dev/personal-budget-tracker/blob/main/index.html"
  click CSS "https://github.com/jusail-dev/personal-budget-tracker/blob/main/style.css"
  click JS "https://github.com/jusail-dev/personal-budget-tracker/blob/main/script.js"
  click README "https://github.com/jusail-dev/personal-budget-tracker/blob/main/README.md"
  click NOTES "https://github.com/jusail-dev/personal-budget-tracker/blob/main/Structure and Concept.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffffff,stroke:#111827,stroke-width:1.5,color:#111827
  classDef runtime fill:#fef3c7,stroke:#b45309,stroke-width:1.5,color:#111827
  classDef ui fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5,color:#0b1220
  classDef code fill:#bfdbfe,stroke:#1e40af,stroke-width:1.5,color:#0b1220
  classDef adapter fill:#93c5fd,stroke:#1e3a8a,stroke-width:1.5,color:#0b1220
  classDef state fill:#e9d5ff,stroke:#7c3aed,stroke-width:1.5,color:#0b1220
  classDef storage fill:#e5e7eb,stroke:#374151,stroke-width:1.5,color:#111827
  classDef file fill:#ffffff,stroke:#6b7280,stroke-width:1.5,color:#111827
  classDef docs fill:#f3f4f6,stroke:#6b7280,stroke-width:1.5,color:#111827
```
