chinmayshastry/ai-finance-research-assistant

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.