nkrameshkrishnan/expense-tracker

Purpose and Entry Points

Ledger is a zero-build, static expense-tracking SPA hosted on GitHub Pages. It uses a Google Sheet as the authoritative database through a Google Apps Script web app; browser seed data supports an unconnected demo mode.

Primary entry points:

• index.html loads the application shell and CDN dependencies.

• assets/app.js owns UI routing, views, forms, and user actions.

• google-apps-script/Code.gs is separately deployed as the Sheet-facing API.

• .github/workflows/deploy.yml produces the Pages deployment.

Client Application Shell

The frontend is ES-module JavaScript with no server runtime or package build. assets/app.js coordinates navigation between dashboard, transactions, budget, charts, and data-management flows, then renders against state supplied by the store.

• index.html

• assets/app.js

• assets/styles.css

Charts are browser-rendered through Chart.js, while spreadsheet import/export uses SheetJS loaded from CDNs.

State, Persistence, and Data Source Boundary

assets/store.js defines the data abstraction: a Sheets-backed store when configured, plus IndexedDB and memory/seed-backed behavior for local use. The configured endpoint/token may be injected at deployment or entered at runtime and retained in browser localStorage.

The key boundary is that the UI talks to a store API rather than directly assuming Google Sheets. On load or explicit reload, transaction and budget state is refreshed from the remote Sheet; failed writes are surfaced rather than queued offline.

• assets/store.js

• assets/config.js

• data/seed.json

Transaction and Budget Flow

Transactions use a normalized model with positive amount values; type determines whether a row represents expense or income. Client actions add, update, or delete transactions through the Sheets store, then refresh/render dependent dashboard and chart data.

Budget data is category-by-month and is maintained separately from transactions. Aggregation, CSV/XLSX-oriented transformations, and flat-table imports are handled in the browser.

• assets/app.js

• assets/store.js

• assets/xlsxio.js

Google Sheets API and Workbook Safety

google-apps-script/Code.gs is the authoritative mutation adapter. It exposes GET/POST handlers because Apps Script web apps do not support other verbs. Client mutations are POSTed as text/plain;charset=utf-8 to avoid an unanswerable CORS preflight.

The script validates the Transactions header layout before writing. It preserves the workbook’s established formulas and reports: dates are real Sheet Date objects; formula-backed Month/Year columns are not overwritten; deletes clear rows rather than removing them; inserts reuse cleared slots. Budget writes target only allowed month columns.

• google-apps-script/Code.gs

• assets/store.js

External Services and Security Boundary

GitHub Pages hosts public static assets. GitHub Actions can inject SHEETS_ENDPOINT and SHEETS_TOKEN into generated assets/config.js; this avoids committing them but does not hide them from deployed-page visitors. Runtime entry is the only option that keeps those values out of published assets.

Google Apps Script executes as the Sheet owner and accesses the Google Spreadsheet. A shared token protects API calls only when it is not shipped with the static client.

• .github/workflows/deploy.yml

• assets/config.js

• google-apps-script/Code.gs

Deployment Pipeline

The Pages workflow validates and publishes the static repository, overwriting endpoint configuration from optional GitHub secrets. No application compilation occurs. The Apps Script deployment is manual and independent: code changes require creating a new web-app deployment version.

• .github/workflows/deploy.yml

• assets/config.js

• index.html