# adegbalajoshua/financeos architecture

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

- Interactive diagram: https://gitdiagram.com/adegbalajoshua/financeos
- Repository: https://github.com/adegbalajoshua/financeos

## Overview

FinanceOS turns a Google Sheet into a personal-finance dashboard and transaction manager. Users launch the dashboard from the Sheets menu, review cycle KPIs, budgets, accounts and receivables, and manage transactions; the API mediates dashboard requests and the finance engine calculates aggregates from sheet data. Separate menu workflows roll budgets into a new cycle, generate native Sheets analytics, and accept webhook transactions. The excerpts show key backend calls; frontend details and some API operations are documented in the README but not sampled, so those links cite that documentation.

Main entry points: [`src/backend/api.js`](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js) (Dashboard API), [`src/frontend/dashboard.js.html`](https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/dashboard.js.html) (Dashboard UI), [`src/backend/database.js`](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/database.js) (Sheets data access), [`src/backend/menu.js`](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/menu.js) (Sheets menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_menu["Sheets menu<br/>[menu.js]"]
end

subgraph group_dashboard["Dashboard and API"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.js.html]"]
  node_dashboard_parts["Dashboard views<br/>[components.js.html]"]
  node_dashboard_charts["Dashboard charts<br/>[charts.js.html]"]
  node_dashboard_motion["Dashboard motion<br/>[animations.js.html]"]
  node_api["Dashboard API<br/>[api.js]"]
end

subgraph group_finance["Finance workflows"]
  node_engine["Finance engine<br/>[financeEngine.js]"]
  node_transactions["Transaction management<br/>[api.js]"]
  node_accounts_budgets["Accounts and budgets<br/>[api.js]"]
  node_cycle_rollover["Cycle rollover<br/>[automation.js]"]
  node_webhook["Transaction webhook<br/>[gateway.js]"]
end

subgraph group_storage["Persistence and configuration"]
  node_database["Sheets data access<br/>[database.js]"]
  node_config["Application config<br/>[config.js]"]
end

subgraph group_integrations["Google Sheets integrations"]
  node_analytics["Sheets analytics<br/>[analytics.js]"]
  node_sheets[("Google Sheets")]
  node_cache[("Apps Script cache")]
  node_apps_script["Apps Script services"]
end

node_sheets_user(("Sheets user"))
node_webhook_client(("Webhook client"))

node_sheets_user -->|"opens menu"| node_menu
node_menu -->|"launches"| node_dashboard_ui
node_sheets_user -->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"calls endpoints"| node_api
node_dashboard_parts -->|"renders views"| node_dashboard_ui
node_dashboard_charts -->|"renders charts"| node_dashboard_ui
node_dashboard_motion -->|"animates views"| node_dashboard_ui
node_api -->|"requests payload"| node_engine
node_api -->|"reads and writes"| node_database
node_engine -->|"reads sheets"| node_database
node_api -->|"reads and clears"| node_cache
node_api -->|"builds trends"| node_engine
node_transactions -->|"persists changes"| node_database
node_accounts_budgets -->|"manages records"| node_database
node_menu -->|"starts workflow"| node_cycle_rollover
node_cycle_rollover -->|"submits salary"| node_api
node_cycle_rollover -->|"rolls budgets"| node_database
node_cycle_rollover -->|"clears cache"| node_api
node_menu -->|"starts analytics"| node_analytics
node_analytics -->|"requests dashboard data"| node_engine
node_analytics -->|"writes charts"| node_sheets
node_webhook_client -->|"posts transaction"| node_webhook
node_webhook -->|"submits transaction"| node_api
node_database -->|"reads and writes"| node_sheets
node_menu -->|"uses UI services"| node_apps_script
node_webhook -->|"returns JSON"| node_apps_script
node_config -->|"configures caching"| node_api

click node_menu "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/menu.js"
click node_dashboard_ui "https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/dashboard.js.html"
click node_dashboard_parts "https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/components.js.html"
click node_dashboard_charts "https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/charts.js.html"
click node_dashboard_motion "https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/animations.js.html"
click node_api "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js"
click node_engine "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/financeEngine.js"
click node_transactions "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js"
click node_accounts_budgets "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js"
click node_cycle_rollover "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/automation.js"
click node_webhook "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/gateway.js"
click node_analytics "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/analytics.js"
click node_database "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/database.js"
click node_config "https://github.com/adegbalajoshua/financeos/blob/main/src/backend/config.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_menu,node_sheets_user,node_webhook_client toneBlue
class node_dashboard_ui,node_dashboard_parts,node_dashboard_charts,node_dashboard_motion,node_api toneAmber
class node_engine,node_transactions,node_accounts_budgets,node_cycle_rollover,node_webhook toneMint
class node_database,node_config toneRose
class node_analytics,node_sheets,node_cache,node_apps_script toneIndigo
```

## Components

### User entry points

- [Sheets menu](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/menu.js): `src/backend/menu.js`

### Dashboard and API

- [Dashboard UI](https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/dashboard.js.html): `src/frontend/dashboard.js.html`
- [Dashboard views](https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/components.js.html): `src/frontend/components.js.html`
- [Dashboard charts](https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/charts.js.html): `src/frontend/charts.js.html`
- [Dashboard motion](https://github.com/adegbalajoshua/financeos/blob/main/src/frontend/animations.js.html): `src/frontend/animations.js.html`
- [Dashboard API](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js): `src/backend/api.js`

### Finance workflows

- [Finance engine](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/financeEngine.js): `src/backend/financeEngine.js`
- [Transaction management](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js): `src/backend/api.js`
- [Accounts and budgets](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/api.js): `src/backend/api.js`
- [Cycle rollover](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/automation.js): `src/backend/automation.js`
- [Transaction webhook](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/gateway.js): `src/backend/gateway.js`

### Persistence and configuration

- [Sheets data access](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/database.js): `src/backend/database.js`
- [Application config](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/config.js): `src/backend/config.js`

### Google Sheets integrations

- [Sheets analytics](https://github.com/adegbalajoshua/financeos/blob/main/src/backend/analytics.js): `src/backend/analytics.js`
- **Google Sheets**
- **Apps Script cache**
- **Apps Script services**

### Other components

- **Sheets user**
- **Webhook client**

## Connections

- Sheets user → Sheets menu: opens menu (evidence: `src/backend/menu.js`)
- Sheets menu → Dashboard UI: launches (evidence: `src/backend/menu.js`)
- Sheets user → Dashboard UI: uses (evidence: `README.md`)
- Dashboard UI → Dashboard API: calls endpoints (evidence: `README.md`)
- Dashboard views → Dashboard UI: renders views (evidence: `README.md`)
- Dashboard charts → Dashboard UI: renders charts (evidence: `README.md`)
- Dashboard motion → Dashboard UI: animates views (evidence: `README.md`)
- Dashboard API → Finance engine: requests payload (evidence: `src/backend/api.js`)
- Dashboard API → Sheets data access: reads and writes (evidence: `src/backend/api.js`)
- Finance engine → Sheets data access: reads sheets (evidence: `src/backend/financeEngine.js`)
- Dashboard API → Apps Script cache: reads and clears (evidence: `src/backend/api.js`)
- Dashboard API → Finance engine: builds trends (evidence: `src/backend/api.js`)
- Transaction management → Sheets data access: persists changes (evidence: `src/backend/api.js`)
- Accounts and budgets → Sheets data access: manages records (evidence: `src/backend/api.js`)
- Sheets menu → Cycle rollover: starts workflow (evidence: `src/backend/menu.js`)
- Cycle rollover → Dashboard API: submits salary (evidence: `src/backend/automation.js`)
- Cycle rollover → Sheets data access: rolls budgets (evidence: `src/backend/automation.js`)
- Cycle rollover → Dashboard API: clears cache (evidence: `src/backend/automation.js`)
- Sheets menu → Sheets analytics: starts analytics (evidence: `src/backend/menu.js`)
- Sheets analytics → Finance engine: requests dashboard data (evidence: `src/backend/analytics.js`)
- Sheets analytics → Google Sheets: writes charts (evidence: `src/backend/analytics.js`)
- Webhook client → Transaction webhook: posts transaction (evidence: `README.md`)
- Transaction webhook → Dashboard API: submits transaction (evidence: `src/backend/gateway.js`)
- Sheets data access → Google Sheets: reads and writes (evidence: `src/backend/database.js`)
- Sheets menu → Apps Script services: uses UI services (evidence: `src/backend/menu.js`)
- Transaction webhook → Apps Script services: returns JSON (evidence: `src/backend/gateway.js`)
- Application config → Dashboard API: configures caching (evidence: `src/backend/api.js`)
