# chinmayshastry/ai-finance-research-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/chinmayshastry/ai-finance-research-assistant
- Repository: https://github.com/chinmayshastry/ai-finance-research-assistant

## Overview

1. **Project shape**
   - This is a single-page Streamlit application with a small, modular backend. `app.py` is the entrypoint and likely owns the UI state, user interaction, and orchestration of the analysis pipeline.

2. **Primary runtime boundary**
   - The application runs as a local/hosted Streamlit app in Python. The repo is not split into separate services; instead, it is organized into feature modules under `modules/` plus asset lists under `data/`.

3. **User-facing flow**
   - The user selects an Indian stock or commodity in the Streamlit UI, then the app pulls market history and recent news, runs LLM-based analysis, and renders charts plus generated research sections back into the dashboard.

4. **Market data subsystem**
   - `modules/market_data.py` is the market price layer. Based on the README, it likely retrieves historical price and volume data from Yahoo Finance and prepares time-series outputs for multiple horizons and charting.

5. **News aggregation subsystem**
   - `modules/news_fetcher.py` is responsible for collecting headlines and article metadata from the external news sources mentioned in the README: NewsAPI and Google News RSS. This is the raw textual input for downstream analysis.

6. **LLM analysis subsystem**
   - `modules/sentiment_analyzer.py` uses OpenAI models to summarize news sentiment over time windows such as 7, 30, and 90 days. This is where raw headlines become structured bullish/bearish/neutral assessments and key drivers.

7. **Research report generation**
   - `modules/report_generator.py` appears to synthesize the longer-form investment research output: recent price trends, probable reasons for movement, macro/sector context, future catalysts, and risks. This is distinct from simple sentiment scoring and is the main “report” product of the app.

8. **Shared utilities**
   - `modules/utils.py` is the common helper layer. In a repo like this it typically centralizes formatting, date handling, caching, string cleanup, and reusable transformations so the feature modules stay focused.

9. **Asset universe / reference data**
   - `data/nifty250.py` and `data/commodities.py` define the supported instruments. These files act as the app’s asset registry, letting the UI offer predefined Indian equities and commodity symbols instead of free-form lookup only.

10. **Configuration and secrets boundary**
   - `config.py` likely manages environment-backed settings such as `OPENAI_API_KEY` and `NEWS_API_KEY`, plus app constants. This is the boundary between code and deployment-specific credentials.

11. **End-to-end data flow**
   - The flow is: user input in Streamlit → asset lookup from `data/` → price retrieval from Yahoo Finance via `market_data` → news collection via `news_fetcher` → synthesis via OpenAI in `sentiment_analyzer` and `report_generator` → rendered charts, summaries, and risk/catalyst sections in the UI.

12. **External dependencies that matter architecturally**
   - The app depends on three external integration points that shape the architecture: Yahoo Finance for market data, NewsAPI/Google News RSS for news intake, and OpenAI for generative analysis. These are the core system boundaries and failure points.

13. **Presentation and visualization layer**
   - Streamlit is the only frontend framework in the repo, while Plotly and Pandas likely handle charting and tabular data preparation. The UI is therefore tightly coupled to the analysis pipeline rather than to a separate backend API.

14. **Development/deployment packaging**
   - `.devcontainer/` indicates a containerized development environment, which helps standardize Python dependencies and runtime setup. `requirements.txt` defines the Python stack used by the Streamlit app and its analysis modules.

15. **What to show in an architecture diagram**
   - A useful diagram would show one top-level Streamlit app, three downstream data/AI subsystems (market data, news ingestion, LLM analysis/reporting), shared config/utils, and the supported asset catalogs feeding the selection step. The main outputs are dashboards, charts, sentiment summaries, long-term reports, and risk/catalyst insights.

Main entry points: [`app.py`](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/app.py) (Streamlit App), [`modules/utils.py`](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/utils.py) (Shared Utils), [`modules/news_fetcher.py`](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/news_fetcher.py) (News Fetcher), [`modules/market_data.py`](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/market_data.py) (Market Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["Streamlit App<br/>entrypoint<br/>[app.py]"]
end

subgraph group_modules["Modules"]
  node_market_data["Market Data<br/>prices module<br/>[market_data.py]"]
  node_news_fetcher["News Fetcher<br/>news module<br/>[news_fetcher.py]"]
  node_sentiment_analyzer["Sentiment Analyzer<br/>LLM analysis"]
  node_report_generator["Report Generator<br/>research synthesis"]
  node_utils["Shared Utils<br/>helpers<br/>[utils.py]"]
end

subgraph group_data["Reference Data"]
  node_nifty250["Nifty 250<br/>equity universe<br/>[nifty250.py]"]
  node_commodities["Commodities<br/>asset universe<br/>[commodities.py]"]
end

subgraph group_external["External Systems"]
  node_streamlit(("Streamlit<br/>ui framework"))
  node_yahoo_finance(("Yahoo Finance<br/>market API"))
  node_news_api(("NewsAPI<br/>news API"))
  node_google_rss(("Google News RSS<br/>news feed"))
  node_openai(("OpenAI<br/>LLM API"))
end

subgraph group_ops["Dev & Config"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_requirements["Requirements<br/>python deps<br/>[requirements.txt]"]
  node_devcontainer["Dev Container<br/>dev setup<br/>[devcontainer.json]"]
end

node_app -->|"asset list"| node_nifty250
node_app -->|"asset list"| node_commodities
node_app -->|"prices"| node_market_data
node_app -->|"news"| node_news_fetcher
node_app -->|"analysis"| node_sentiment_analyzer
node_app -->|"report"| node_report_generator
node_app -->|"ui"| node_streamlit
node_market_data -->|"fetch"| node_yahoo_finance
node_news_fetcher -->|"fetch"| node_news_api
node_news_fetcher -->|"fetch"| node_google_rss
node_sentiment_analyzer -->|"summarize"| node_openai
node_report_generator -->|"draft"| node_openai
node_app -->|"helpers"| node_utils
node_market_data -->|"helpers"| node_utils
node_news_fetcher -->|"helpers"| node_utils
node_sentiment_analyzer -->|"helpers"| node_utils
node_report_generator -->|"helpers"| node_utils
node_config -->|"api key"| node_openai
node_config -->|"api key"| node_news_api
node_app -->|"settings"| node_config
node_app -.->|"deps"| node_requirements
node_devcontainer -.->|"env"| node_requirements
node_readme -.->|"docs"| node_app

click node_app "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/app.py"
click node_market_data "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/market_data.py"
click node_news_fetcher "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/news_fetcher.py"
click node_sentiment_analyzer "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/sentiment_analyzer.py"
click node_report_generator "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/report_generator.py"
click node_utils "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/utils.py"
click node_nifty250 "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/data/nifty250.py"
click node_commodities "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/data/commodities.py"
click node_config "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/config.py"
click node_readme "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/README.md"
click node_requirements "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/requirements.txt"
click node_devcontainer "https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/.devcontainer/devcontainer.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_app toneBlue
class node_market_data,node_news_fetcher,node_sentiment_analyzer,node_report_generator,node_utils toneAmber
class node_nifty250,node_commodities toneMint
class node_streamlit,node_yahoo_finance,node_news_api,node_google_rss,node_openai toneRose
class node_config,node_readme,node_requirements,node_devcontainer toneIndigo
```

## Components

### Runtime

Streamlit app entrypoint and user-facing orchestration

- [Streamlit App](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/app.py): entrypoint · Main UI, state, and end-to-end orchestration · `app.py`

### Modules

Core analysis and data-processing subsystems

- [Market Data](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/market_data.py): prices module · Fetches and prepares historical price/volume data · `modules/market_data.py`
- [News Fetcher](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/news_fetcher.py): news module · Collects headlines and article metadata from external sources · `modules/news_fetcher.py`
- [Sentiment Analyzer](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/sentiment_analyzer.py): LLM analysis · Summarizes news into bullish/bearish/neutral signals and drivers · `modules/sentiment_analyzer.py`
- [Report Generator](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/report_generator.py): research synthesis · Builds longer-form investment research and risk/catalyst sections · `modules/report_generator.py`
- [Shared Utils](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/modules/utils.py): helpers · Common formatting, cleanup, caching, and transformation helpers · `modules/utils.py`

### Reference Data

Supported instruments for selection in the UI

- [Nifty 250](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/data/nifty250.py): equity universe · Predefined Indian stock universe for selection · `data/nifty250.py`
- [Commodities](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/data/commodities.py): asset universe · Predefined commodity symbols for selection · `data/commodities.py`

### External Systems

Third-party data and AI dependencies

- **Streamlit**: ui framework · Interactive single-page dashboard runtime
- **Yahoo Finance**: market API · External source for historical market data
- **NewsAPI**: news API · External news source used for headline collection
- **Google News RSS**: news feed · RSS-based news intake source
- **OpenAI**: LLM API · Generative analysis backend for summarization and report drafting

### Dev & Config

Environment, secrets, and local setup

- [Config](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/config.py): settings · Environment-backed settings and app constants · `config.py`
- [README](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/README.md): docs · Usage and integration notes for the application · `README.md`
- [Requirements](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/requirements.txt): python deps · Pinned Python dependencies for the app and modules · `requirements.txt`
- [Dev Container](https://github.com/chinmayshastry/ai-finance-research-assistant/blob/main/.devcontainer/devcontainer.json): dev setup · Containerized local development environment · `.devcontainer/devcontainer.json`

## Connections

- Streamlit App → Nifty 250: asset list · Loads supported stocks for the selector
- Streamlit App → Commodities: asset list · Loads supported commodities for the selector
- Streamlit App → Market Data: prices · Requests historical market data for the selected instrument
- Streamlit App → News Fetcher: news · Requests recent headlines and article metadata
- Streamlit App → Sentiment Analyzer: analysis · Triggers LLM-based sentiment synthesis
- Streamlit App → Report Generator: report · Triggers long-form research generation
- Streamlit App → Streamlit: ui · Runs the interactive dashboard in Streamlit
- Market Data → Yahoo Finance: fetch · Retrieves historical prices and volume
- News Fetcher → NewsAPI: fetch · Pulls news from NewsAPI when available
- News Fetcher → Google News RSS: fetch · Collects headlines from Google News RSS
- Sentiment Analyzer → OpenAI: summarize · Uses OpenAI models to classify and summarize sentiment
- Report Generator → OpenAI: draft · Uses OpenAI models to synthesize the research report
- Streamlit App → Shared Utils: helpers · Shares formatting and transformation utilities
- Market Data → Shared Utils: helpers · Uses common data preparation helpers
- News Fetcher → Shared Utils: helpers · Uses common text cleanup and parsing helpers
- Sentiment Analyzer → Shared Utils: helpers · Uses shared normalization and aggregation helpers
- Report Generator → Shared Utils: helpers · Uses shared formatting and synthesis helpers
- Config → OpenAI: api key · Provides OpenAI credentials
- Config → NewsAPI: api key · Provides NewsAPI credentials
- Streamlit App → Config: settings · Reads runtime configuration and secrets
- Streamlit App → Requirements: deps · Runs against the declared Python dependency set
- Dev Container → Requirements: env · Uses the repository dependency stack in development
- README → Streamlit App: docs · Documents the main application workflow