How jusail-dev/personal-budget-tracker works
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