# sachinadk2011/finledge-app architecture

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

- Interactive diagram: https://gitdiagram.com/sachinadk2011/finledge-app
- Repository: https://github.com/sachinadk2011/finledge-app

## Overview

1. FinLedge is a three-runtime desktop finance application: an Electron shell hosts a React UI, and the UI talks to a Python FastAPI backend running as a local sidecar process. The product is desktop-first, with local file storage rather than a remote database.

2. The main user-facing UI lives in `frontendwebapp/`. It is a Vite/React single-page app with pages for Home, Bank, Share, and Summary. The page layer is thin; most screens are composed from reusable form, table, chart, dialog, and status components.

3. The frontend is split by domain. `BankPage` and `SharePage` handle module-specific workflows, while `Summary` aggregates overall position. Supporting API clients in `frontendwebapp/src/api/` separate browser calls from UI components.

4. The backend lives in `backend/` and is organized as a FastAPI service with route modules and service modules. The route layer exposes domain endpoints for bank, share, and summary; the service layer contains the business logic and data transformation.

5. The backend is the system-of-record layer for app behavior. `backend/models.py` defines the data contracts, while services such as `bank_service`, `share_service`, and `summary_graph_service` likely handle validation, persistence, calculations, and chart-ready aggregation before data is returned to the UI.

6. Persistence is local and file-based. The README and service layout indicate Excel workbooks stored in the user profile area, not a database server. `path_utils.py` centralizes file location handling so the app writes into the OS-managed user-data directory, which keeps data portable and avoids hardcoded paths.

7. The two primary data domains are bank transactions and share transactions. The bank side tracks income and several expense/investment categories; the share side tracks IPO, buy, sell, dividend, edit, and IPO allotment updates. These are separate flows until the summary layer combines them.

8. The summary experience is a cross-domain aggregation boundary. Summary routes/services collect bank and share data, compute comparative metrics, and prepare graph data. On the frontend, this shows up as dashboards, interactive timelines, bar charts, stat grids, and transaction tables.

9. Visualization is split by responsibility. The backend includes Matplotlib for generating graph-related artifacts or calculations, while the frontend uses Recharts for interactive in-app charts. That suggests a clear division between server-side summary generation and client-side presentation.

10. The Electron app in `desktop/` provides the packaged Windows experience. `main.js` and `preload.js` define the shell and secure bridge to the frontend/backend, while build scripts and `package.json` support local desktop development and packaging.

11. The root-level scripts coordinate the multi-runtime workflow. npm and Node scripts synchronize versions, start releases, and manage packaging, while Python dependency management is handled separately through `requirements.txt` and a virtual environment. This is a coordinated monorepo, not a single build system.

12. Release engineering is a first-class concern. The repository includes GitHub Actions, SignPath code-signing policy, and Electron Builder/PyInstaller references, which means the backend is frozen into a distributable executable and shipped with the desktop app. GitHub Releases also appear to drive update notifications.

13. For architecture diagram purposes, the key trust and data boundaries are: user interface in React/Electron, local API boundary to FastAPI, and file storage boundary to Excel workbooks in the user profile. There is no evidence of a central cloud datastore in the app’s core runtime path.

Main entry points: [`backend/routes`](https://github.com/sachinadk2011/finledge-app/tree/main/backend/routes) (Routes), [`frontendwebapp/src/pages`](https://github.com/sachinadk2011/finledge-app/tree/main/frontendwebapp/src/pages) (Pages), [`backend/services/bank_service.py`](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/bank_service.py) (Bank service), [`backend/services/share_service.py`](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/share_service.py) (Share service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_desktop["Desktop shell"]
  node_n_desktop_main["Electron main<br/>electron-shell<br/>[main.js]"]
  node_n_desktop_preload["Preload bridge<br/>secure-bridge<br/>[preload.js]"]
end

subgraph group_g_frontend["React app"]
  node_n_frontend_app["App shell<br/>react-entry<br/>[App.jsx]"]
  node_n_frontend_pages["Pages"]
  node_n_frontend_components["UI components<br/>ui-library"]
  node_n_frontend_api_client["API client<br/>http-client<br/>[client.js]"]
  node_n_frontend_bank_api["Bank API<br/>domain-client<br/>[bankApi.js]"]
  node_n_frontend_share_api["Share API<br/>domain-client<br/>[shareApi.js]"]
  node_n_frontend_charts(("Charts<br/>visualization<br/>[BarChart.jsx]"))
end

subgraph group_g_backend["FastAPI backend"]
  node_n_backend_main["FastAPI app<br/>api-server<br/>[main.py]"]
  node_n_backend_routes["Routes"]
  node_n_backend_bank_service["Bank service<br/>domain-service<br/>[bank_service.py]"]
  node_n_backend_share_service["Share service<br/>domain-service<br/>[share_service.py]"]
  node_n_backend_summary_service["Summary service<br/>aggregation-service"]
  node_n_backend_models["Data models<br/>contracts<br/>[models.py]"]
  node_n_backend_paths["Path utils<br/>storage-paths<br/>[path_utils.py]"]
end

subgraph group_g_release["Release"]
  node_n_release_scripts["Release scripts<br/>automation"]
  node_n_release_ci["CI signing<br/>ci-cd<br/>[release-signed.yml]"]
end

node_n_desktop_main -->|"loads bridge"| node_n_desktop_preload
node_n_desktop_main -->|"hosts UI"| node_n_frontend_app
node_n_frontend_app -->|"composes"| node_n_frontend_pages
node_n_frontend_pages -->|"uses"| node_n_frontend_components
node_n_frontend_pages -->|"bank flows"| node_n_frontend_bank_api
node_n_frontend_pages -->|"share flows"| node_n_frontend_share_api
node_n_frontend_bank_api -->|"requests"| node_n_frontend_api_client
node_n_frontend_share_api -->|"requests"| node_n_frontend_api_client
node_n_frontend_components -->|"renders"| node_n_frontend_charts
node_n_frontend_api_client -->|"HTTP API"| node_n_backend_routes
node_n_backend_main -->|"mounts"| node_n_backend_routes
node_n_backend_routes -->|"bank endpoints"| node_n_backend_bank_service
node_n_backend_routes -->|"share endpoints"| node_n_backend_share_service
node_n_backend_routes -->|"summary endpoints"| node_n_backend_summary_service
node_n_backend_bank_service -->|"uses contracts"| node_n_backend_models
node_n_backend_share_service -->|"uses contracts"| node_n_backend_models
node_n_backend_summary_service -->|"uses contracts"| node_n_backend_models
node_n_backend_bank_service -->|"stores files"| node_n_backend_paths
node_n_backend_share_service -->|"stores files"| node_n_backend_paths
node_n_backend_summary_service -->|"reads files"| node_n_backend_paths
node_n_release_scripts -->|"packages"| node_n_desktop_main
node_n_release_scripts -->|"freezes"| node_n_backend_main
node_n_release_ci -->|"runs"| node_n_release_scripts

click node_n_desktop_main "https://github.com/sachinadk2011/finledge-app/blob/main/desktop/main.js"
click node_n_desktop_preload "https://github.com/sachinadk2011/finledge-app/blob/main/desktop/preload.js"
click node_n_frontend_app "https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/App.jsx"
click node_n_frontend_pages "https://github.com/sachinadk2011/finledge-app/tree/main/frontendwebapp/src/pages"
click node_n_frontend_components "https://github.com/sachinadk2011/finledge-app/tree/main/frontendwebapp/src/components"
click node_n_frontend_api_client "https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/client.js"
click node_n_frontend_bank_api "https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/bankApi.js"
click node_n_frontend_share_api "https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/shareApi.js"
click node_n_frontend_charts "https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/components/BarChart.jsx"
click node_n_backend_main "https://github.com/sachinadk2011/finledge-app/blob/main/backend/main.py"
click node_n_backend_routes "https://github.com/sachinadk2011/finledge-app/tree/main/backend/routes"
click node_n_backend_bank_service "https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/bank_service.py"
click node_n_backend_share_service "https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/share_service.py"
click node_n_backend_summary_service "https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/summary_graph_service.py"
click node_n_backend_models "https://github.com/sachinadk2011/finledge-app/blob/main/backend/models.py"
click node_n_backend_paths "https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/path_utils.py"
click node_n_release_scripts "https://github.com/sachinadk2011/finledge-app/tree/main/scripts"
click node_n_release_ci "https://github.com/sachinadk2011/finledge-app/blob/main/.github/workflows/release-signed.yml"

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_n_desktop_main,node_n_desktop_preload toneBlue
class node_n_frontend_app,node_n_frontend_pages,node_n_frontend_components,node_n_frontend_api_client,node_n_frontend_bank_api,node_n_frontend_share_api,node_n_frontend_charts toneAmber
class node_n_backend_main,node_n_backend_routes,node_n_backend_bank_service,node_n_backend_share_service,node_n_backend_summary_service,node_n_backend_models,node_n_backend_paths toneMint
class node_n_release_scripts,node_n_release_ci toneRose
```

## Components

### Desktop shell

Electron packaging and secure bridge for the local app

- [Electron main](https://github.com/sachinadk2011/finledge-app/blob/main/desktop/main.js): electron-shell · Bootstraps the desktop app and manages the packaged runtime · `desktop/main.js`
- [Preload bridge](https://github.com/sachinadk2011/finledge-app/blob/main/desktop/preload.js): secure-bridge · Exposes a controlled IPC surface between Electron and the web UI · `desktop/preload.js`

### React app

User-facing UI and client-side data access

- [App shell](https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/App.jsx): react-entry · Top-level React application entry and routing composition · `frontendwebapp/src/App.jsx`
- [Pages](https://github.com/sachinadk2011/finledge-app/tree/main/frontendwebapp/src/pages): ui-pages · Home, bank, share, and summary screens · `frontendwebapp/src/pages`
- [UI components](https://github.com/sachinadk2011/finledge-app/tree/main/frontendwebapp/src/components): ui-library · Reusable forms, tables, charts, dialogs, and status panels · `frontendwebapp/src/components`
- [API client](https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/client.js): http-client · Browser-side request helpers for the local backend · `frontendwebapp/src/api/client.js`
- [Bank API](https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/bankApi.js): domain-client · Frontend calls for bank workflows · `frontendwebapp/src/api/bankApi.js`
- [Share API](https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/api/shareApi.js): domain-client · Frontend calls for share workflows · `frontendwebapp/src/api/shareApi.js`
- [Charts](https://github.com/sachinadk2011/finledge-app/blob/main/frontendwebapp/src/components/BarChart.jsx): visualization · Interactive timelines, bar charts, and summary visuals · `frontendwebapp/src/components/BarChart.jsx`

### FastAPI backend

Local sidecar API, business logic, and persistence

- [FastAPI app](https://github.com/sachinadk2011/finledge-app/blob/main/backend/main.py): api-server · Local sidecar server and application startup · `backend/main.py`
- [Routes](https://github.com/sachinadk2011/finledge-app/tree/main/backend/routes): http-routes · Domain HTTP endpoints for bank, share, and summary · `backend/routes`
- [Bank service](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/bank_service.py): domain-service · Bank workflow logic, validation, and persistence coordination · `backend/services/bank_service.py`
- [Share service](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/share_service.py): domain-service · Share workflow logic, validation, and persistence coordination · `backend/services/share_service.py`
- [Summary service](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/summary_graph_service.py): aggregation-service · Cross-domain metrics and chart-ready aggregation · `backend/services/summary_graph_service.py`
- [Data models](https://github.com/sachinadk2011/finledge-app/blob/main/backend/models.py): contracts · Shared backend data contracts and schemas · `backend/models.py`
- [Path utils](https://github.com/sachinadk2011/finledge-app/blob/main/backend/services/path_utils.py): storage-paths · Resolves user-profile file locations for local workbooks · `backend/services/path_utils.py`

### Release

Build, versioning, and signing automation

- [Release scripts](https://github.com/sachinadk2011/finledge-app/tree/main/scripts): automation · Version sync, release orchestration, and packaging helpers · `scripts`
- [CI signing](https://github.com/sachinadk2011/finledge-app/blob/main/.github/workflows/release-signed.yml): ci-cd · GitHub Actions and SignPath code-signing policy · `.github/workflows/release-signed.yml`

## Connections

- Electron main → Preload bridge: loads bridge · Electron shell exposes a secure preload layer
- Electron main → App shell: hosts UI · Desktop shell launches the React frontend
- App shell → Pages: composes · Application shell renders domain pages
- Pages → UI components: uses · Pages are built from shared UI components
- Pages → Bank API: bank flows · Bank screen actions call bank API helpers
- Pages → Share API: share flows · Share screen actions call share API helpers
- Bank API → API client: requests · Domain client is built on the shared HTTP client
- Share API → API client: requests · Domain client is built on the shared HTTP client
- UI components → Charts: renders · Reusable components include chart and summary visualizations
- API client → Routes: HTTP API · Frontend talks to the local FastAPI sidecar
- FastAPI app → Routes: mounts · FastAPI app wires domain route modules
- Routes → Bank service: bank endpoints · Bank routes delegate to bank service logic
- Routes → Share service: share endpoints · Share routes delegate to share service logic
- Routes → Summary service: summary endpoints · Summary routes delegate to aggregation logic
- Bank service → Data models: uses contracts · Bank logic relies on shared backend schemas
- Share service → Data models: uses contracts · Share logic relies on shared backend schemas
- Summary service → Data models: uses contracts · Summary aggregation relies on shared backend schemas
- Bank service → Path utils: stores files · Bank data is written to local workbook locations
- Share service → Path utils: stores files · Share data is written to local workbook locations
- Summary service → Path utils: reads files · Summary aggregation reads the same local workbooks
- Release scripts → Electron main: packages · Release automation builds the desktop shell and sidecar
- Release scripts → FastAPI app: freezes · Python backend is bundled for desktop distribution
- CI signing → Release scripts: runs · CI enforces signing and release workflow
