# nandhuincede/bank-advisor architecture

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

- Interactive diagram: https://gitdiagram.com/nandhuincede/bank-advisor
- Repository: https://github.com/nandhuincede/bank-advisor

## Overview

1. This repository is a small Flask-based AI financial advisor with a single server-side application, a browser-rendered UI, a deterministic calculation layer, an LLM-backed reasoning layer, and a local SQLite persistence layer.

2. The user interface is a single HTML template in `templates/index.html`. It serves two main interactions: submitting a financial profile for analysis and chatting against a previously created analysis session. There is no separate frontend application or JS framework boundary visible in the repo.

3. The application entry point is `run.py` (with `main.py` also present). The Flask app is organized as a factory-style package under `app/`, with route registration in `app/api/routes.py` and database initialization in `app/db/database.py`.

4. The request boundary is HTTP JSON APIs. The key endpoints are `POST /api/analyze` for financial assessment, `POST /api/chat` for follow-up questions, `GET /api/history` for analysis summaries, and `GET /api/analysis/<id>` for retrieving one analysis plus its conversation history.

5. The core business logic is split into a pure computation layer in `app/services/financial_calculator.py`. This layer performs all financial math deterministically: EMI ratio, savings rate, credit utilization, projected annual savings, monthly surplus, and deficit detection. The README explicitly says the LLM does not perform calculations.

6. On top of that sits the agent layer in `app/services/agent.py`. This is the orchestration boundary where LangChain-style tool use and prompt-driven response generation happen. The agent consumes computed metrics and user context, then produces the human-readable financial report or chat answer.

7. The tool boundary is in `app/tools/financial_tools.py`. These tools expose calculator and lookup capabilities to the agent, such as computing metrics and fetching stored analysis/chat context. This keeps the model from directly accessing raw application internals.

8. LLM provider selection is abstracted in `app/services/llm_factory.py`. The README indicates support for OpenAI, Gemini, and local Ollama, so model access is a configurable infrastructure dependency rather than a hard-coded vendor integration.

9. Persistence is handled with SQLite in `app/db/database.py`. Two tables are central to the architecture: `analysis` stores the original financial inputs, computed metrics, and generated AI report; `chat_history` stores per-analysis conversation turns linked by `analysis_id`. This creates a session-scoped data model for follow-up Q&A.

10. The main data flow for analysis is: browser form submission → Flask route validation → calculator computes metrics → agent/LLM interprets results → analysis record is saved in SQLite → response is returned to the browser. The important architectural constraint is that metrics are computed before any LLM reasoning.

11. The chat flow is separate but stateful: browser question → lookup of the referenced analysis and prior chat history → agent and LLM generate a contextual answer → question/answer pair is appended to `chat_history` → answer is returned to the UI. The database therefore acts as both an audit trail and conversation memory.

12. Operationally, the project is lightweight: `pyproject.toml` and `uv.lock` indicate modern Python packaging with `uv`, and `.env.example` shows that runtime configuration is environment-driven. The only notable external runtime dependencies are the chosen LLM provider API or local Ollama endpoint plus the local SQLite file.

13. A useful diagram boundary for this repo is: presentation layer, Flask API layer, deterministic financial engine, LLM agent/tooling layer, and SQLite persistence layer. The central design principle is separation between numeric truth and natural-language interpretation.

Main entry points: [`app/api/routes.py`](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py) (Chat API), [`app/services/agent.py`](https://github.com/nandhuincede/bank-advisor/blob/main/app/services/agent.py) (Advisor agent), [`app/__init__.py`](https://github.com/nandhuincede/bank-advisor/blob/main/app/__init__.py) (App factory), [`app/db/database.py`](https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py) (Analysis store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_index_template["Index page<br/>HTML template<br/>[index.html]"]
end

subgraph group_api["API Layer"]
  node_routes["Routes<br/>HTTP API<br/>[routes.py]"]
  node_analyze_api["Analyze API<br/>POST /api/analyze<br/>[routes.py]"]
  node_chat_api["Chat API<br/>POST /api/chat<br/>[routes.py]"]
  node_history_api["History API<br/>GET /api/history<br/>[routes.py]"]
  node_analysis_api["Analysis API<br/>GET /api/analysis/<id><br/>[routes.py]"]
end

subgraph group_core["Core Logic"]
  node_calculator{{"Calculator<br/>deterministic finance engine"}}
  node_agent{{"Advisor agent<br/>LLM orchestrator<br/>[agent.py]"}}
  node_llm_factory["LLM factory<br/>model provider config<br/>[llm_factory.py]"]
  node_tools["Financial tools<br/>agent tools<br/>[financial_tools.py]"]
end

subgraph group_data["Data Layer"]
  node_database[("DB init<br/>SQLite bootstrap<br/>[database.py]")]
  node_analysis_table[("Analysis store<br/>SQLite table<br/>[database.py]")]
  node_chat_table[("Chat store<br/>SQLite table<br/>[database.py]")]
end

subgraph group_runtime["Runtime"]
  node_run_py["Run app<br/>startup script<br/>[run.py]"]
  node_main_py["Main entry<br/>startup module<br/>[main.py]"]
  node_app_init["App factory<br/>Flask package<br/>[__init__.py]"]
end

node_run_py -->|"starts"| node_app_init
node_main_py -->|"starts"| node_app_init
node_app_init -->|"registers"| node_routes
node_app_init -->|"initializes"| node_database
node_routes -->|"exposes"| node_analyze_api
node_routes -->|"exposes"| node_chat_api
node_routes -->|"exposes"| node_history_api
node_routes -->|"exposes"| node_analysis_api
node_analyze_api -->|"computes"| node_calculator
node_analyze_api -->|"interprets"| node_agent
node_analyze_api -->|"saves"| node_analysis_table
node_chat_api -->|"loads"| node_analysis_table
node_chat_api -->|"reads/writes"| node_chat_table
node_chat_api -->|"uses"| node_tools
node_chat_api -->|"answers with"| node_agent
node_analysis_api -->|"reads"| node_analysis_table
node_analysis_api -->|"reads"| node_chat_table
node_agent -->|"selects model"| node_llm_factory
node_agent -->|"invokes"| node_tools
node_tools -->|"wraps"| node_calculator
node_database -->|"hosts"| node_analysis_table
node_database -->|"hosts"| node_chat_table
node_index_template -->|"submits to"| node_analyze_api
node_index_template -->|"submits to"| node_chat_api
node_index_template -->|"displays"| node_analysis_api

click node_index_template "https://github.com/nandhuincede/bank-advisor/blob/main/templates/index.html"
click node_run_py "https://github.com/nandhuincede/bank-advisor/blob/main/run.py"
click node_main_py "https://github.com/nandhuincede/bank-advisor/blob/main/main.py"
click node_app_init "https://github.com/nandhuincede/bank-advisor/blob/main/app/__init__.py"
click node_routes "https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py"
click node_database "https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py"
click node_calculator "https://github.com/nandhuincede/bank-advisor/blob/main/app/services/financial_calculator.py"
click node_agent "https://github.com/nandhuincede/bank-advisor/blob/main/app/services/agent.py"
click node_llm_factory "https://github.com/nandhuincede/bank-advisor/blob/main/app/services/llm_factory.py"
click node_tools "https://github.com/nandhuincede/bank-advisor/blob/main/app/tools/financial_tools.py"
click node_analysis_table "https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py"
click node_chat_table "https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py"
click node_analyze_api "https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py"
click node_chat_api "https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py"
click node_history_api "https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py"
click node_analysis_api "https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.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_index_template toneBlue
class node_routes,node_analyze_api,node_chat_api,node_history_api,node_analysis_api toneAmber
class node_calculator,node_agent,node_llm_factory,node_tools toneMint
class node_database,node_analysis_table,node_chat_table toneRose
class node_run_py,node_main_py,node_app_init toneIndigo
```

## Components

### Presentation

Browser-facing UI and entrypoints

- [Index page](https://github.com/nandhuincede/bank-advisor/blob/main/templates/index.html): HTML template · Single browser UI for analysis and chat interactions · `templates/index.html`

### API Layer

Flask request handling and route surface

- [Routes](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py): HTTP API · Defines analysis, chat, and history endpoints · `app/api/routes.py`
- [Analyze API](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py): POST /api/analyze · Validates profile and returns a financial assessment · `app/api/routes.py`
- [Chat API](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py): POST /api/chat · Answers follow-up questions for an analysis session · `app/api/routes.py`
- [History API](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py): GET /api/history · Returns analysis summaries · `app/api/routes.py`
- [Analysis API](https://github.com/nandhuincede/bank-advisor/blob/main/app/api/routes.py): GET /api/analysis/<id> · Returns one analysis with conversation history · `app/api/routes.py`

### Core Logic

Deterministic finance logic and AI orchestration

- [Calculator](https://github.com/nandhuincede/bank-advisor/blob/main/app/services/financial_calculator.py): deterministic finance engine · Computes ratios, savings, surplus, and deficit checks · `app/services/financial_calculator.py`
- [Advisor agent](https://github.com/nandhuincede/bank-advisor/blob/main/app/services/agent.py): LLM orchestrator · Turns computed metrics into reports and chat answers · `app/services/agent.py`
- [LLM factory](https://github.com/nandhuincede/bank-advisor/blob/main/app/services/llm_factory.py): model provider config · Selects OpenAI, Gemini, or local Ollama backend · `app/services/llm_factory.py`
- [Financial tools](https://github.com/nandhuincede/bank-advisor/blob/main/app/tools/financial_tools.py): agent tools · Tool boundary for metrics and stored context access · `app/tools/financial_tools.py`

### Data Layer

SQLite persistence and session state

- [DB init](https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py): SQLite bootstrap · Database connection and table initialization · `app/db/database.py`
- [Analysis store](https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py): SQLite table · Persists input profile, computed metrics, and generated report · `app/db/database.py`
- [Chat store](https://github.com/nandhuincede/bank-advisor/blob/main/app/db/database.py): SQLite table · Stores per-analysis question and answer history · `app/db/database.py`

### Runtime

App bootstrap and configuration

- [Run app](https://github.com/nandhuincede/bank-advisor/blob/main/run.py): startup script · Primary execution entrypoint for the Flask server · `run.py`
- [Main entry](https://github.com/nandhuincede/bank-advisor/blob/main/main.py): startup module · Alternate application entrypoint · `main.py`
- [App factory](https://github.com/nandhuincede/bank-advisor/blob/main/app/__init__.py): Flask package · Application package initialization and factory setup · `app/__init__.py`

## Connections

- Run app → App factory: starts · Launches the Flask application
- Main entry → App factory: starts · Alternative application startup path
- App factory → Routes: registers · Attaches HTTP routes to the app
- App factory → DB init: initializes · Creates or prepares the SQLite schema
- Routes → Analyze API: exposes · HTTP endpoint for financial analysis
- Routes → Chat API: exposes · HTTP endpoint for follow-up chat
- Routes → History API: exposes · HTTP endpoint for analysis summaries
- Routes → Analysis API: exposes · HTTP endpoint for one analysis session
- Analyze API → Calculator: computes · Derives deterministic financial metrics
- Analyze API → Advisor agent: interprets · Turns metrics into a human-readable report
- Analyze API → Analysis store: saves · Persists the completed analysis
- Chat API → Analysis store: loads · Fetches the referenced analysis context
- Chat API → Chat store: reads/writes · Uses prior turns and appends the new exchange
- Chat API → Financial tools: uses · Supplies stored context and metric access to the agent
- Chat API → Advisor agent: answers with · Generates contextual follow-up responses
- Analysis API → Analysis store: reads · Retrieves the stored analysis record
- Analysis API → Chat store: reads · Retrieves the conversation history
- Advisor agent → LLM factory: selects model · Obtains the configured provider backend
- Advisor agent → Financial tools: invokes · Calls tools for metrics and context
- Financial tools → Calculator: wraps · Exposes deterministic calculations to the agent
- DB init → Analysis store: hosts · Physical storage for analysis records
- DB init → Chat store: hosts · Physical storage for chat history
- Index page → Analyze API: submits to · Browser form posts analysis requests
- Index page → Chat API: submits to · Browser chat UI posts follow-up questions
- Index page → Analysis API: displays · Renders a selected analysis session