# kunj406962/finsight architecture

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

- Interactive diagram: https://gitdiagram.com/kunj406962/finsight
- Repository: https://github.com/kunj406962/finsight
- Video tour (about a minute): https://gitdiagram.com/kunj406962/finsight/video

## Overview

FinSight takes a user from account setup and bank-statement upload through transaction categorization, review, and persistence, then serves searchable transactions, reconciled account balances, forecasts, anomaly flags, and narrated insights in a React dashboard. The backend routers coordinate parsing, ML, database access, and external services; the frontend API client carries authenticated requests. The README documents the domain behavior and major capabilities, but several router implementations were not sampled, so their internal wiring is shown only where explicitly documented.

Main entry points: [`backend/app/main.py`](https://github.com/kunj406962/finsight/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/upload.py`](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/upload.py) (Upload routes), [`backend/app/services/db.py`](https://github.com/kunj406962/finsight/blob/main/backend/app/services/db.py) (Database service), [`frontend/src/api/client.ts`](https://github.com/kunj406962/finsight/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["React application<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_txquery["Transaction query"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_accountsui["Account views<br/>[Accounts.tsx]"]
  node_transactionsui["Transaction views<br/>[Transactions.tsx]"]
end

subgraph group_api["API and identity"]
  node_api["FastAPI application<br/>[main.py]"]
  node_authroute["Auth routes<br/>[auth.py]"]
  node_accountroute["Account routes<br/>[accounts.py]"]
  node_transactionroute["Transaction routes<br/>[transactions.py]"]
  node_emailroute["Auth email hook<br/>[email_hook.py]"]
  node_dbservice["Database service<br/>[db.py]"]
end

subgraph group_ingestion["Transaction ingestion"]
  node_uploadroute["Upload routes<br/>[upload.py]"]
  node_parserdetect["Format detection<br/>[detector.py]"]
  node_rbcparser["RBC parser<br/>[rbc_parser.py]"]
  node_categorizer["ML categorizer<br/>[categorizer.py]"]
  node_transfer["Transfer detection"]
end

subgraph group_analytics["Financial analytics"]
  node_anomaly["Anomaly scoring<br/>[anomaly.py]"]
  node_forecastroute["Forecast routes<br/>[forecast.py]"]
  node_forecaster["Spending forecaster<br/>[forecaster.py]"]
  node_insightsroute["Insights routes<br/>[insights.py]"]
end

subgraph group_integrations["External services"]
  node_supabase[("Supabase database and auth")]
  node_gemini["Gemini AI"]
  node_emailsender["Email sender<br/>[email_sender.py]"]
end

node_user(("Finance user"))
node_bankcsv["Bank CSV export"]

node_user -->|"uses"| node_webapp
node_webapp -->|"provides auth"| node_authui
node_authui -->|"requests auth"| node_apiclient
node_webapp -->|"renders"| node_dashboard
node_webapp -->|"renders"| node_accountsui
node_webapp -->|"renders"| node_transactionsui
node_dashboard -->|"requests insights"| node_apiclient
node_dashboard -->|"requests forecasts"| node_apiclient
node_transactionsui -->|"queries"| node_txquery
node_txquery -->|"fetches pages"| node_apiclient
node_accountsui -->|"requests accounts"| node_apiclient
node_apiclient -->|"HTTP requests"| node_api
node_api -->|"dispatches"| node_authroute
node_api -->|"dispatches"| node_accountroute
node_api -->|"dispatches"| node_uploadroute
node_api -->|"dispatches"| node_transactionroute
node_api -->|"dispatches"| node_forecastroute
node_api -->|"dispatches"| node_insightsroute
node_api -->|"dispatches"| node_emailroute
node_bankcsv -->|"uploads"| node_uploadroute
node_uploadroute -->|"detects format"| node_parserdetect
node_uploadroute -->|"parses CSV"| node_rbcparser
node_uploadroute -->|"classifies transactions"| node_categorizer
node_uploadroute -->|"detects transfers"| node_transfer
node_uploadroute -->|"inserts on confirm"| node_dbservice
node_uploadroute -->|"queues scoring"| node_anomaly
node_accountroute -->|"reads and writes"| node_dbservice
node_transactionroute -->|"reads and writes"| node_dbservice
node_forecastroute -->|"computes forecasts"| node_forecaster
node_forecastroute -->|"reads and caches"| node_dbservice
node_insightsroute -->|"generates narration"| node_gemini
node_insightsroute -->|"reads and caches"| node_dbservice
node_authroute -->|"authenticates users"| node_supabase
node_dbservice -->|"queries and persists"| node_supabase
node_emailroute -->|"sends email"| node_emailsender
node_anomaly -->|"stores scores"| node_dbservice
node_forecastroute -->|"returns forecast"| node_dashboard
node_insightsroute -->|"returns narration"| node_dashboard

click node_webapp "https://github.com/kunj406962/finsight/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/kunj406962/finsight/blob/main/frontend/src/context/AuthContext.tsx"
click node_apiclient "https://github.com/kunj406962/finsight/blob/main/frontend/src/api/client.ts"
click node_txquery "https://github.com/kunj406962/finsight/blob/main/frontend/src/hooks/useTransactionsQuery.ts"
click node_dashboard "https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Dashboard.tsx"
click node_accountsui "https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Accounts.tsx"
click node_transactionsui "https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Transactions.tsx"
click node_api "https://github.com/kunj406962/finsight/blob/main/backend/app/main.py"
click node_authroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/auth.py"
click node_accountroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/accounts.py"
click node_uploadroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/upload.py"
click node_transactionroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/transactions.py"
click node_parserdetect "https://github.com/kunj406962/finsight/blob/main/backend/app/services/parsers/detector.py"
click node_rbcparser "https://github.com/kunj406962/finsight/blob/main/backend/app/services/parsers/rbc_parser.py"
click node_categorizer "https://github.com/kunj406962/finsight/blob/main/backend/app/ml/categorizer.py"
click node_transfer "https://github.com/kunj406962/finsight/blob/main/backend/app/ml/transfer_detector.py"
click node_anomaly "https://github.com/kunj406962/finsight/blob/main/backend/app/ml/anomaly.py"
click node_forecastroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/forecast.py"
click node_forecaster "https://github.com/kunj406962/finsight/blob/main/backend/app/ml/forecaster.py"
click node_insightsroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/insights.py"
click node_emailroute "https://github.com/kunj406962/finsight/blob/main/backend/app/routers/email_hook.py"
click node_dbservice "https://github.com/kunj406962/finsight/blob/main/backend/app/services/db.py"
click node_emailsender "https://github.com/kunj406962/finsight/blob/main/backend/app/services/email_sender.py"

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_webapp,node_authui,node_apiclient,node_txquery,node_dashboard,node_accountsui,node_transactionsui,node_user toneBlue
class node_api,node_authroute,node_accountroute,node_transactionroute,node_emailroute,node_dbservice toneAmber
class node_uploadroute,node_parserdetect,node_rbcparser,node_categorizer,node_transfer toneMint
class node_anomaly,node_forecastroute,node_forecaster,node_insightsroute toneRose
class node_supabase,node_gemini,node_emailsender,node_bankcsv toneIndigo
```

## Components

### Web application

- [React application](https://github.com/kunj406962/finsight/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/kunj406962/finsight/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/kunj406962/finsight/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Transaction query](https://github.com/kunj406962/finsight/blob/main/frontend/src/hooks/useTransactionsQuery.ts): `frontend/src/hooks/useTransactionsQuery.ts`
- [Dashboard](https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Account views](https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Accounts.tsx): `frontend/src/pages/Accounts.tsx`
- [Transaction views](https://github.com/kunj406962/finsight/blob/main/frontend/src/pages/Transactions.tsx): `frontend/src/pages/Transactions.tsx`

### API and identity

- [FastAPI application](https://github.com/kunj406962/finsight/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Account routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/accounts.py): `backend/app/routers/accounts.py`
- [Transaction routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/transactions.py): `backend/app/routers/transactions.py`
- [Auth email hook](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/email_hook.py): `backend/app/routers/email_hook.py`
- [Database service](https://github.com/kunj406962/finsight/blob/main/backend/app/services/db.py): `backend/app/services/db.py`

### Transaction ingestion

- [Upload routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/upload.py): `backend/app/routers/upload.py`
- [Format detection](https://github.com/kunj406962/finsight/blob/main/backend/app/services/parsers/detector.py): `backend/app/services/parsers/detector.py`
- [RBC parser](https://github.com/kunj406962/finsight/blob/main/backend/app/services/parsers/rbc_parser.py): `backend/app/services/parsers/rbc_parser.py`
- [ML categorizer](https://github.com/kunj406962/finsight/blob/main/backend/app/ml/categorizer.py): `backend/app/ml/categorizer.py`
- [Transfer detection](https://github.com/kunj406962/finsight/blob/main/backend/app/ml/transfer_detector.py): `backend/app/ml/transfer_detector.py`

### Financial analytics

- [Anomaly scoring](https://github.com/kunj406962/finsight/blob/main/backend/app/ml/anomaly.py): `backend/app/ml/anomaly.py`
- [Forecast routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/forecast.py): `backend/app/routers/forecast.py`
- [Spending forecaster](https://github.com/kunj406962/finsight/blob/main/backend/app/ml/forecaster.py): `backend/app/ml/forecaster.py`
- [Insights routes](https://github.com/kunj406962/finsight/blob/main/backend/app/routers/insights.py): `backend/app/routers/insights.py`

### External services

- **Supabase database and auth**
- **Gemini AI**
- [Email sender](https://github.com/kunj406962/finsight/blob/main/backend/app/services/email_sender.py): `backend/app/services/email_sender.py`

### Other components

- **Finance user**
- **Bank CSV export**

## Connections

- Finance user → React application: uses
- React application → Auth context: provides auth
- Auth context → API client: requests auth
- React application → Dashboard: renders
- React application → Account views: renders
- React application → Transaction views: renders
- Dashboard → API client: requests insights
- Dashboard → API client: requests forecasts
- Transaction views → Transaction query: queries
- Transaction query → API client: fetches pages
- Account views → API client: requests accounts
- API client → FastAPI application: HTTP requests
- FastAPI application → Auth routes: dispatches
- FastAPI application → Account routes: dispatches
- FastAPI application → Upload routes: dispatches
- FastAPI application → Transaction routes: dispatches
- FastAPI application → Forecast routes: dispatches
- FastAPI application → Insights routes: dispatches
- FastAPI application → Auth email hook: dispatches
- Bank CSV export → Upload routes: uploads
- Upload routes → Format detection: detects format
- Upload routes → RBC parser: parses CSV
- Upload routes → ML categorizer: classifies transactions
- Upload routes → Transfer detection: detects transfers
- Upload routes → Database service: inserts on confirm
- Upload routes → Anomaly scoring: queues scoring
- Account routes → Database service: reads and writes
- Transaction routes → Database service: reads and writes
- Forecast routes → Spending forecaster: computes forecasts
- Forecast routes → Database service: reads and caches
- Insights routes → Gemini AI: generates narration
- Insights routes → Database service: reads and caches
- Auth routes → Supabase database and auth: authenticates users
- Database service → Supabase database and auth: queries and persists
- Auth email hook → Email sender: sends email
- Anomaly scoring → Database service: stores scores
- Forecast routes → Dashboard: returns forecast
- Insights routes → Dashboard: returns narration