# dhiraj1308/finsight-ai architecture

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

- Interactive diagram: https://gitdiagram.com/dhiraj1308/finsight-ai
- Repository: https://github.com/dhiraj1308/finsight-ai

## Overview

FinSight AI is a personal-finance assistant: users submit transaction statements or ask questions, and the API parses and stores transactions, then exposes retrieval, anomaly, forecasting, and chat capabilities. Chat uses a tool-calling agent to ground answers in transaction data and analysis. The README describes a Streamlit dashboard, but no frontend source appears in the supplied tree, so the graph starts at the API. API wiring is sampled; the store implementation and some API routes are not, so uncertain links are omitted.

Main entry points: [`src/api/app.py`](https://github.com/dhiraj1308/finsight-ai/blob/master/src/api/app.py) (FastAPI service), [`src/agent/tools.py`](https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/tools.py) (Financial tools), [`src/ingestion/transaction_store.py`](https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/transaction_store.py) (Transaction store), [`src/agent/agent.py`](https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/agent.py) (Financial agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api["FastAPI service<br/>[app.py]"]
  node_settings["Configuration<br/>[config.py]"]
end

subgraph group_ingest["Statement ingestion"]
  node_csv["CSV parser<br/>[csv_parser.py]"]
  node_pdf["PDF parser<br/>[pdf_parser.py]"]
end

subgraph group_data["Transaction data"]
  node_transaction["Transaction model<br/>[domain.py]"]
  node_store[("Transaction store")]
end

subgraph group_analysis["Financial analysis"]
  node_categorizer["Categorizer<br/>[categorizer.py]"]
  node_anomaly["Anomaly detector"]
  node_forecaster["Spending forecaster<br/>[forecaster.py]"]
end

subgraph group_assistant["AI assistant"]
  node_vector[("Vector retrieval<br/>[vector_store.py]")]
  node_agent["Financial agent<br/>[agent.py]"]
  node_tools["Financial tools<br/>[tools.py]"]
end

node_user(("User"))
node_llm["Groq language model"]

node_user -->|"submits requests"| node_api
node_api -->|"loads settings"| node_settings
node_api -->|"parses CSV"| node_csv
node_api -->|"parses PDF"| node_pdf
node_pdf -->|"reuses field parsing"| node_csv
node_api -->|"categorizes transactions"| node_categorizer
node_api -->|"stores and queries"| node_store
node_api -->|"indexes transactions"| node_vector
node_api -->|"requests anomalies"| node_anomaly
node_anomaly -->|"reads and updates"| node_store
node_api -->|"requests forecasts"| node_forecaster
node_forecaster -->|"reads category history"| node_store
node_api -->|"handles chat"| node_agent
node_agent -->|"dispatches tool calls"| node_tools
node_agent -->|"sends prompts"| node_llm
node_tools -->|"retrieves transactions"| node_vector
node_tools -->|"queries spending"| node_store
node_tools -->|"runs forecasts"| node_forecaster
node_tools -->|"gets anomalies"| node_anomaly

click node_api "https://github.com/dhiraj1308/finsight-ai/blob/master/src/api/app.py"
click node_settings "https://github.com/dhiraj1308/finsight-ai/blob/master/src/config.py"
click node_csv "https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/csv_parser.py"
click node_pdf "https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/pdf_parser.py"
click node_transaction "https://github.com/dhiraj1308/finsight-ai/blob/master/src/domain.py"
click node_store "https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/transaction_store.py"
click node_categorizer "https://github.com/dhiraj1308/finsight-ai/blob/master/src/categorization/categorizer.py"
click node_anomaly "https://github.com/dhiraj1308/finsight-ai/blob/master/src/anomaly/anomaly_detector.py"
click node_forecaster "https://github.com/dhiraj1308/finsight-ai/blob/master/src/forecasting/forecaster.py"
click node_vector "https://github.com/dhiraj1308/finsight-ai/blob/master/src/api/vector_store.py"
click node_agent "https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/agent.py"
click node_tools "https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/tools.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_api,node_settings,node_user toneBlue
class node_csv,node_pdf toneAmber
class node_transaction,node_store toneMint
class node_categorizer,node_anomaly,node_forecaster toneRose
class node_vector,node_agent,node_tools,node_llm toneIndigo
```

## Components

### API and access

- [FastAPI service](https://github.com/dhiraj1308/finsight-ai/blob/master/src/api/app.py): `src/api/app.py`
- [Configuration](https://github.com/dhiraj1308/finsight-ai/blob/master/src/config.py): `src/config.py`

### Statement ingestion

- [CSV parser](https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/csv_parser.py): `src/ingestion/csv_parser.py`
- [PDF parser](https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/pdf_parser.py): `src/ingestion/pdf_parser.py`

### Transaction data

- [Transaction model](https://github.com/dhiraj1308/finsight-ai/blob/master/src/domain.py): `src/domain.py`
- [Transaction store](https://github.com/dhiraj1308/finsight-ai/blob/master/src/ingestion/transaction_store.py): `src/ingestion/transaction_store.py`

### Financial analysis

- [Categorizer](https://github.com/dhiraj1308/finsight-ai/blob/master/src/categorization/categorizer.py): `src/categorization/categorizer.py`
- [Anomaly detector](https://github.com/dhiraj1308/finsight-ai/blob/master/src/anomaly/anomaly_detector.py): `src/anomaly/anomaly_detector.py`
- [Spending forecaster](https://github.com/dhiraj1308/finsight-ai/blob/master/src/forecasting/forecaster.py): `src/forecasting/forecaster.py`

### AI assistant

- [Vector retrieval](https://github.com/dhiraj1308/finsight-ai/blob/master/src/api/vector_store.py): `src/api/vector_store.py`
- [Financial agent](https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/agent.py): `src/agent/agent.py`
- [Financial tools](https://github.com/dhiraj1308/finsight-ai/blob/master/src/agent/tools.py): `src/agent/tools.py`

### Other components

- **User**
- **Groq language model**

## Connections

- User → FastAPI service: submits requests
- FastAPI service → Configuration: loads settings
- FastAPI service → CSV parser: parses CSV
- FastAPI service → PDF parser: parses PDF
- PDF parser → CSV parser: reuses field parsing
- FastAPI service → Categorizer: categorizes transactions
- FastAPI service → Transaction store: stores and queries
- FastAPI service → Vector retrieval: indexes transactions
- FastAPI service → Anomaly detector: requests anomalies
- Anomaly detector → Transaction store: reads and updates
- FastAPI service → Spending forecaster: requests forecasts
- Spending forecaster → Transaction store: reads category history
- FastAPI service → Financial agent: handles chat
- Financial agent → Financial tools: dispatches tool calls
- Financial agent → Groq language model: sends prompts
- Financial tools → Vector retrieval: retrieves transactions
- Financial tools → Transaction store: queries spending
- Financial tools → Spending forecaster: runs forecasts
- Financial tools → Anomaly detector: gets anomalies