# shubankar-sridhar/fintrack architecture

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

- Interactive diagram: https://gitdiagram.com/shubankar-sridhar/fintrack
- Repository: https://github.com/shubankar-sridhar/fintrack

## Overview

#### Purpose and Deployment
FinTrack is a single-user-session personal finance manager for accounts, transactions, budgets, savings, recurring obligations, loans, and reporting. The production shape is a React SPA served as compiled static assets by a Flask backend, with Render deployment configuration in `render.yaml`. Key runtime entry points are `backend/app.py` and `src/main.jsx`.

#### Frontend Application Shell
`src/main.jsx` mounts the React application; `src/App.jsx` owns authentication state, shared data refresh behavior, and section-level routing. Once authenticated, the shell combines navigation and user controls from `src/components/Sidebar.jsx` and `src/components/Header.jsx`; unauthenticated users are routed to `src/components/AuthScreen.jsx`.

#### API Boundary and Authentication
The browser uses a centralized fetch layer in `src/utils/api.js` to call Flask `/api/*` endpoints. `backend/app.py` is the REST and static-serving boundary: it handles registration, login/logout, session-based authentication, user-scoped authorization, CRUD operations, transactional finance actions, export/reset, and analytics aggregation. Passwords are SHA256-hashed; Flask sessions carry authenticated identity.

#### Persistence and Financial Domain
`backend/database.py` owns SQLite initialization and schema access. `users` is the tenancy root; accounts, categories, expenses, income sources, recurring payments, savings goals, and EMIs are associated with a user, with transaction-related records additionally referencing accounts/categories where relevant. The backend enforces business mutations such as account balance changes, transfers, income receipts, recurring processing, savings contributions, and EMI payments.

#### Transaction and Obligation Workflows
Expense, income, account, category, recurring, savings, and EMI screens each collect input and invoke corresponding APIs:
`src/components/Expenses.jsx`, `src/components/Income.jsx`, and `src/components/Accounts.jsx` manage core cash-flow records and account transfers.
`src/components/Recurring.jsx`, `src/components/Emis.jsx`, and `src/components/Savings.jsx` manage scheduled liabilities and goal allocation. Date/frequency handling is backed by Python `dateutil`, with due-payment state exposed to navigation and dashboard views.

#### Dashboard and Analytics Read Models
The dashboard consumes summary, recent activity, and monthly aggregate data to present the current financial state in `src/components/Dashboard.jsx`. Analytics requests backend-generated monthly income/expense, category-spend, and daily-spend aggregates, rendered through Chart.js in `src/components/Analytics.jsx`. This keeps aggregation and user-data filtering server-side while visualization remains client-side.

#### Build and Runtime Infrastructure
Development uses Vite/React from `package.json` and `vite.config.js`; its production build is committed/served under `backend/static/index.html` and `backend/static/assets/`. Backend dependencies and production WSGI hosting are defined by `backend/requirements.txt`, including Flask, SQLite access, date utilities, and Gunicorn. No separate queue, scheduler, or external database service is represented; due recurring work is initiated through application API actions.

Main entry points: [`src/App.jsx`](https://github.com/shubankar-sridhar/fintrack/blob/main/src/App.jsx) (Application shell), [`src/utils/api.js`](https://github.com/shubankar-sridhar/fintrack/blob/main/src/utils/api.js) (API client), [`backend/app.py`](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py) (REST & static server), [`backend/database.py`](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/database.py) (Schema & database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_main["React entry<br/>SPA bootstrap<br/>[main.jsx]"]
  node_app["Application shell<br/>React state &amp; routing<br/>[App.jsx]"]
  node_auth_screen["Auth screen<br/>React view<br/>[AuthScreen.jsx]"]
  node_shell_ui["Navigation &amp; header<br/>React shell UI<br/>[Sidebar.jsx]"]
  node_api_client["API client<br/>central fetch layer<br/>[api.js]"]
  node_cashflow_views["Cash-flow views<br/>React finance screens<br/>[Expenses.jsx]"]
  node_obligation_views["Obligation views<br/>React finance screens<br/>[Recurring.jsx]"]
  node_dashboard["Dashboard<br/>React read model view<br/>[Dashboard.jsx]"]
  node_analytics["Analytics charts<br/>Chart.js view<br/>[Analytics.jsx]"]
end

subgraph group_backend["Flask backend"]
  node_flask_app{{"REST &amp; static server<br/>Flask application<br/>[app.py]"}}
  node_finance_mutations["Finance mutations<br/>domain workflow layer<br/>[app.py]"]
  node_analytics_api["Analytics aggregation<br/>server read models<br/>[app.py]"]
end

subgraph group_data["SQLite data"]
  node_database_access["Schema &amp; database access<br/>SQLite access layer<br/>[database.py]"]
  node_fintrack_db[("User-scoped finance data<br/>SQLite database")]
end

subgraph group_runtime["Build &amp; deployment"]
  node_vite_build["Vite production build<br/>React build pipeline<br/>[vite.config.js]"]
  node_static_assets["Compiled SPA assets<br/>static bundle<br/>[index.html]"]
  node_wsgi_runtime["Gunicorn backend runtime<br/>production WSGI host<br/>[requirements.txt]"]
  node_render["Render deployment<br/>deployment configuration<br/>[render.yaml]"]
end

node_main -->|"mounts"| node_app
node_app -->|"unauthenticated"| node_auth_screen
node_app -->|"authenticated shell"| node_shell_ui
node_app -->|"routes to"| node_cashflow_views
node_app -->|"routes to"| node_obligation_views
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_analytics
node_auth_screen -->|"auth requests"| node_api_client
node_cashflow_views -->|"CRUD and transfers"| node_api_client
node_obligation_views -->|"payment actions"| node_api_client
node_dashboard -->|"summary reads"| node_api_client
node_analytics -->|"aggregate reads"| node_api_client
node_api_client -->|"/api/*"| node_flask_app
node_flask_app -->|"transactional actions"| node_finance_mutations
node_flask_app -->|"analytics requests"| node_analytics_api
node_finance_mutations -->|"persists changes"| node_database_access
node_analytics_api -->|"queries aggregates"| node_database_access
node_database_access -->|"reads and writes"| node_fintrack_db
node_vite_build -->|"emits"| node_static_assets
node_flask_app -->|"serves"| node_static_assets
node_wsgi_runtime -->|"hosts"| node_flask_app
node_render -->|"deploys"| node_wsgi_runtime

click node_main "https://github.com/shubankar-sridhar/fintrack/blob/main/src/main.jsx"
click node_app "https://github.com/shubankar-sridhar/fintrack/blob/main/src/App.jsx"
click node_auth_screen "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/AuthScreen.jsx"
click node_shell_ui "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Sidebar.jsx"
click node_api_client "https://github.com/shubankar-sridhar/fintrack/blob/main/src/utils/api.js"
click node_cashflow_views "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Expenses.jsx"
click node_obligation_views "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Recurring.jsx"
click node_dashboard "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Dashboard.jsx"
click node_analytics "https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Analytics.jsx"
click node_flask_app "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py"
click node_finance_mutations "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py"
click node_analytics_api "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py"
click node_database_access "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/database.py"
click node_vite_build "https://github.com/shubankar-sridhar/fintrack/blob/main/vite.config.js"
click node_static_assets "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/static/index.html"
click node_wsgi_runtime "https://github.com/shubankar-sridhar/fintrack/blob/main/backend/requirements.txt"
click node_render "https://github.com/shubankar-sridhar/fintrack/blob/main/render.yaml"

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_main,node_app,node_auth_screen,node_shell_ui,node_api_client,node_cashflow_views,node_obligation_views,node_dashboard,node_analytics toneBlue
class node_flask_app,node_finance_mutations,node_analytics_api toneAmber
class node_database_access,node_fintrack_db toneMint
class node_vite_build,node_static_assets,node_wsgi_runtime,node_render toneRose
```

## Components

### React frontend

- [React entry](https://github.com/shubankar-sridhar/fintrack/blob/main/src/main.jsx): SPA bootstrap · `src/main.jsx`
- [Application shell](https://github.com/shubankar-sridhar/fintrack/blob/main/src/App.jsx): React state & routing · Owns auth state and shared refresh behavior. · `src/App.jsx`
- [Auth screen](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/AuthScreen.jsx): React view · `src/components/AuthScreen.jsx`
- [Navigation & header](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Sidebar.jsx): React shell UI · `src/components/Sidebar.jsx`
- [API client](https://github.com/shubankar-sridhar/fintrack/blob/main/src/utils/api.js): central fetch layer · `src/utils/api.js`
- [Cash-flow views](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Expenses.jsx): React finance screens · Expenses, income, accounts, and transfers. · `src/components/Expenses.jsx`
- [Obligation views](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Recurring.jsx): React finance screens · Recurring payments, EMIs, and savings goals. · `src/components/Recurring.jsx`
- [Dashboard](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Dashboard.jsx): React read model view · `src/components/Dashboard.jsx`
- [Analytics charts](https://github.com/shubankar-sridhar/fintrack/blob/main/src/components/Analytics.jsx): Chart.js view · `src/components/Analytics.jsx`

### Flask backend

- [REST & static server](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py): Flask application · Serves SPA assets and user-scoped /api endpoints. · `backend/app.py`
- [Finance mutations](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py): domain workflow layer · Applies balances, transfers, receipts, obligations, savings, and EMI payments. · `backend/app.py`
- [Analytics aggregation](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/app.py): server read models · Builds summary, activity, and spending aggregates. · `backend/app.py`

### SQLite data

- [Schema & database access](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/database.py): SQLite access layer · `backend/database.py`
- **User-scoped finance data**: SQLite database · Users root accounts, categories, transactions, obligations, and goals.

### Build & deployment

- [Vite production build](https://github.com/shubankar-sridhar/fintrack/blob/main/vite.config.js): React build pipeline · `vite.config.js`
- [Compiled SPA assets](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/static/index.html): static bundle · `backend/static/index.html`
- [Gunicorn backend runtime](https://github.com/shubankar-sridhar/fintrack/blob/main/backend/requirements.txt): production WSGI host · `backend/requirements.txt`
- [Render deployment](https://github.com/shubankar-sridhar/fintrack/blob/main/render.yaml): deployment configuration · `render.yaml`

## Connections

- React entry → Application shell: mounts
- Application shell → Auth screen: unauthenticated
- Application shell → Navigation & header: authenticated shell
- Application shell → Cash-flow views: routes to
- Application shell → Obligation views: routes to
- Application shell → Dashboard: routes to
- Application shell → Analytics charts: routes to
- Auth screen → API client: auth requests
- Cash-flow views → API client: CRUD and transfers
- Obligation views → API client: payment actions
- Dashboard → API client: summary reads
- Analytics charts → API client: aggregate reads
- API client → REST & static server: /api/*
- REST & static server → Finance mutations: transactional actions
- REST & static server → Analytics aggregation: analytics requests
- Finance mutations → Schema & database access: persists changes
- Analytics aggregation → Schema & database access: queries aggregates
- Schema & database access → User-scoped finance data: reads and writes
- Vite production build → Compiled SPA assets: emits
- REST & static server → Compiled SPA assets: serves
- Gunicorn backend runtime → REST & static server: hosts
- Render deployment → Gunicorn backend runtime: deploys