nandhuincede/bank-advisor

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.