How sachinadk2011/finledge-app works
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: routes Routes · pages Pages · bank_service.py Bank service · share_service.py Share service
Components 18
Desktop shell
Electron packaging and secure bridge for the local app
- Electron main · Bootstraps the desktop app and manages the packaged runtime
desktop/main.js - Preload 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 · Top-level React application entry and routing composition
frontendwebapp/src/App.jsx - Pages · Home, bank, share, and summary screens
frontendwebapp/src/pages - UI components · Reusable forms, tables, charts, dialogs, and status panels
frontendwebapp/src/components - API client · Browser-side request helpers for the local backend
frontendwebapp/src/api/client.js - Bank API · Frontend calls for bank workflows
frontendwebapp/src/api/bankApi.js - Share API · Frontend calls for share workflows
frontendwebapp/src/api/shareApi.js - Charts · Interactive timelines, bar charts, and summary visuals
frontendwebapp/src/components/BarChart.jsx
FastAPI backend
Local sidecar API, business logic, and persistence
- FastAPI app · Local sidecar server and application startup
backend/main.py - Routes · Domain HTTP endpoints for bank, share, and summary
backend/routes - Bank service · Bank workflow logic, validation, and persistence coordination
backend/services/bank_service.py - Share service · Share workflow logic, validation, and persistence coordination
backend/services/share_service.py - Summary service · Cross-domain metrics and chart-ready aggregation
backend/services/summary_graph_service.py - Data models · Shared backend data contracts and schemas
backend/models.py - Path utils · Resolves user-profile file locations for local workbooks
backend/services/path_utils.py
Release
Build, versioning, and signing automation
- Release scripts · Version sync, release orchestration, and packaging helpers
scripts - CI signing · GitHub Actions and SignPath code-signing policy
.github/workflows/release-signed.yml
Connections 23
- 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