# vishveswara31/finance-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vishveswara31/finance-ai
- Repository: https://github.com/vishveswara31/finance-ai

## Overview

FinanceAI is a Flask finance assistant with four user-facing workflows: expense tracking, 50/30/20 budget generation, transaction fraud scoring, and company investment recommendations. A browser submits form data to Flask routes; each route validates input and invokes its corresponding agent, which returns a result and, where applicable, persists records in SQLite. Investment lookup also reads company reference data. The source excerpts establish these calls and data accesses; the HTML template and styling exist in the tree but were not sampled, so their internal behavior is not expanded here.

Main entry points: [`app.py`](https://github.com/vishveswara31/finance-ai/blob/main/app.py) (API routes), [`database.py`](https://github.com/vishveswara31/finance-ai/blob/main/database.py) (SQLite access), [`agents/investment_agent.py`](https://github.com/vishveswara31/finance-ai/blob/main/agents/investment_agent.py) (Investment lookup), [`static/script.js`](https://github.com/vishveswara31/finance-ai/blob/main/static/script.js) (Form client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Browser interface"]
  node_page["Finance page<br/>[index.html]"]
  node_client["Form client<br/>[script.js]"]
end

subgraph group_api["Flask API"]
  node_routes["API routes<br/>[app.py]"]
end

subgraph group_workflows["Finance workflows"]
  node_expense["Expense tracker<br/>[expense_agent.py]"]
  node_budget["Budget planner<br/>[budget_agent.py]"]
  node_fraud["Fraud scorer<br/>[fraud_agent.py]"]
  node_investment["Investment lookup"]
end

subgraph group_data["Data stores"]
  node_db_access["SQLite access<br/>[database.py]"]
  node_sqlite[("Finance database")]
  node_companies["Company catalog<br/>[companies.json]"]
end

node_user(("Finance user"))

node_user -.->|"uses"| node_page
node_routes -->|"renders"| node_page
node_client -->|"posts forms"| node_routes
node_routes -->|"returns JSON"| node_client
node_routes -->|"initializes"| node_db_access
node_routes -->|"invokes"| node_expense
node_routes -->|"invokes"| node_budget
node_routes -->|"invokes"| node_fraud
node_routes -->|"invokes"| node_investment
node_expense -->|"uses"| node_db_access
node_budget -->|"uses"| node_db_access
node_investment -->|"uses"| node_db_access
node_db_access -->|"connects"| node_sqlite
node_investment -->|"reads catalog"| node_companies

click node_page "https://github.com/vishveswara31/finance-ai/blob/main/templates/index.html"
click node_client "https://github.com/vishveswara31/finance-ai/blob/main/static/script.js"
click node_routes "https://github.com/vishveswara31/finance-ai/blob/main/app.py"
click node_expense "https://github.com/vishveswara31/finance-ai/blob/main/agents/expense_agent.py"
click node_budget "https://github.com/vishveswara31/finance-ai/blob/main/agents/budget_agent.py"
click node_fraud "https://github.com/vishveswara31/finance-ai/blob/main/agents/fraud_agent.py"
click node_investment "https://github.com/vishveswara31/finance-ai/blob/main/agents/investment_agent.py"
click node_db_access "https://github.com/vishveswara31/finance-ai/blob/main/database.py"
click node_sqlite "https://github.com/vishveswara31/finance-ai/tree/main/database"
click node_companies "https://github.com/vishveswara31/finance-ai/blob/main/data/companies.json"

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_page,node_client,node_user toneBlue
class node_routes toneAmber
class node_expense,node_budget,node_fraud,node_investment toneMint
class node_db_access,node_sqlite,node_companies toneRose
```

## Components

### Browser interface

- [Finance page](https://github.com/vishveswara31/finance-ai/blob/main/templates/index.html): `templates/index.html`
- [Form client](https://github.com/vishveswara31/finance-ai/blob/main/static/script.js): `static/script.js`

### Flask API

- [API routes](https://github.com/vishveswara31/finance-ai/blob/main/app.py): `app.py`

### Finance workflows

- [Expense tracker](https://github.com/vishveswara31/finance-ai/blob/main/agents/expense_agent.py): `agents/expense_agent.py`
- [Budget planner](https://github.com/vishveswara31/finance-ai/blob/main/agents/budget_agent.py): `agents/budget_agent.py`
- [Fraud scorer](https://github.com/vishveswara31/finance-ai/blob/main/agents/fraud_agent.py): `agents/fraud_agent.py`
- [Investment lookup](https://github.com/vishveswara31/finance-ai/blob/main/agents/investment_agent.py): `agents/investment_agent.py`

### Data stores

- [SQLite access](https://github.com/vishveswara31/finance-ai/blob/main/database.py): `database.py`
- [Finance database](https://github.com/vishveswara31/finance-ai/tree/main/database): `database`
- [Company catalog](https://github.com/vishveswara31/finance-ai/blob/main/data/companies.json): `data/companies.json`

### Other components

- **Finance user**

## Connections

- Finance user → Finance page: uses
- API routes → Finance page: renders (evidence: `app.py`)
- Form client → API routes: posts forms (evidence: `static/script.js`)
- API routes → Form client: returns JSON (evidence: `app.py`)
- API routes → SQLite access: initializes (evidence: `app.py`)
- API routes → Expense tracker: invokes (evidence: `app.py`)
- API routes → Budget planner: invokes (evidence: `app.py`)
- API routes → Fraud scorer: invokes (evidence: `app.py`)
- API routes → Investment lookup: invokes (evidence: `app.py`)
- Expense tracker → SQLite access: uses (evidence: `agents/expense_agent.py`)
- Budget planner → SQLite access: uses (evidence: `agents/budget_agent.py`)
- Investment lookup → SQLite access: uses (evidence: `agents/investment_agent.py`)
- SQLite access → Finance database: connects (evidence: `database.py`)
- Investment lookup → Company catalog: reads catalog (evidence: `agents/investment_agent.py`)