# bhumikaaggwl/equity-return-prediction-alpha-signal-model architecture

> Architecture diagram of the GitHub repository bhumikaaggwl/equity-return-prediction-alpha-signal-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model
- Repository: https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model

## Overview

This is an equity-return research and alpha-signal platform: it ingests market, fundamentals, and news data, builds features and excess-return targets, trains and evaluates models, then produces signals and research views. The main batch workflow is explicit in `main.py`; the README documents SHAP explainability and signal-basket risk analysis. Some feature and dashboard implementations were not excerpted, so their documented capabilities are shown without assuming unverified internal calls.

Main entry points: [`data/storage.py`](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/storage.py) (SQLite research store), [`models/trainer.py`](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/trainer.py) (Model training and comparison), [`main.py`](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/main.py) (Pipeline runner), [`features/builder.py`](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/builder.py) (Feature and target builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_prices["Price ingestion<br/>[fetcher.py]"]
  node_fundamentals["Fundamentals ingestion<br/>[fetcher.py]"]
  node_news["News ingestion<br/>[news_fetcher.py]"]
  node_marketdata["Market data provider"]
  node_database[("SQLite research store<br/>[storage.py]")]
end

subgraph group_features["Feature engineering"]
  node_builder["Feature and target builder<br/>[builder.py]"]
  node_technical["Technical indicators<br/>[technical.py]"]
  node_fundamental["Fundamental ratios<br/>[fundamental.py]"]
  node_valuation["Valuation metrics<br/>[valuation.py]"]
  node_sentiment["FinBERT sentiment<br/>[sentiment.py]"]
  node_finbert["FinBERT model"]
end

subgraph group_research["Model research"]
  node_trainer["Model training and comparison<br/>[trainer.py]"]
  node_decisiontree["Scratch decision tree<br/>[decision_tree.py]"]
  node_xgboostscratch["Scratch XGBoost<br/>[xgboost_model.py]"]
  node_metrics["Prediction metrics<br/>[metrics.py]"]
  node_backtest["Walk-forward validation<br/>[walkforward.py]"]
end

subgraph group_outputs["Signals and research"]
  node_signals["BUY HOLD SELL signals<br/>[signal.py]"]
  node_shap["SHAP explainability<br/>[shap_analysis.py]"]
  node_risk["Signal basket risk<br/>[risk.py]"]
  node_dashboard["Interactive dashboard<br/>[app.py]"]
  node_report["Research report export<br/>[export_report.py]"]
end

node_analyst(("Research user"))
node_main["Pipeline runner<br/>[main.py]"]
node_config["Universe and settings<br/>[config.py]"]
node_logger["Logging<br/>[logger.py]"]

node_analyst -->|"starts pipeline"| node_main
node_analyst -->|"explores research"| node_dashboard
node_main -->|"initializes"| node_database
node_main -->|"fetches prices"| node_prices
node_main -->|"fetches fundamentals"| node_fundamentals
node_main -->|"fetches headlines"| node_news
node_main -->|"trains models"| node_trainer
node_main -->|"runs validation"| node_backtest
node_prices -.->|"downloads prices"| node_marketdata
node_fundamentals -.->|"fetches fundamentals"| node_marketdata
node_news -.->|"fetches news"| node_marketdata
node_prices -->|"writes prices"| node_database
node_fundamentals -->|"writes records"| node_database
node_news -->|"writes headlines"| node_database
node_builder -->|"reads prices"| node_database
node_builder -->|"computes indicators"| node_technical
node_builder -->|"computes ratios"| node_fundamental
node_builder -->|"computes valuation"| node_valuation
node_builder -->|"merges sentiment"| node_sentiment
node_sentiment -->|"reads headlines"| node_database
node_sentiment -->|"scores headlines"| node_finbert
node_trainer -->|"builds training data"| node_builder
node_trainer -->|"trains scratch tree"| node_decisiontree
node_trainer -->|"trains scratch model"| node_xgboostscratch
node_trainer -->|"scores predictions"| node_metrics
node_trainer -->|"stores metrics"| node_database
node_backtest -->|"builds test data"| node_builder
node_backtest -->|"evaluates folds"| node_metrics
node_backtest -->|"counts fold signals"| node_signals
node_trainer -->|"generates saved signals"| node_signals
node_dashboard -->|"reads research data"| node_database
node_dashboard -->|"builds features"| node_builder
node_dashboard -->|"generates signals"| node_signals
node_dashboard -->|"computes metrics"| node_metrics
node_dashboard -->|"runs backtest"| node_backtest
node_dashboard -.->|"explains predictions"| node_shap
node_report -->|"reports risk"| node_risk
node_risk -->|"reads signal data"| node_database
node_main -->|"logs pipeline"| node_logger
node_trainer -->|"logs training"| node_logger
node_config -->|"sets database path"| node_database

click node_main "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/main.py"
click node_config "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/config.py"
click node_prices "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/fetcher.py"
click node_fundamentals "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/fetcher.py"
click node_news "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/news_fetcher.py"
click node_database "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/storage.py"
click node_builder "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/builder.py"
click node_technical "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/technical.py"
click node_fundamental "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/fundamental.py"
click node_valuation "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/valuation.py"
click node_sentiment "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/sentiment.py"
click node_trainer "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/trainer.py"
click node_decisiontree "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/decision_tree.py"
click node_xgboostscratch "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/xgboost_model.py"
click node_metrics "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/evaluation/metrics.py"
click node_backtest "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/backtest/walkforward.py"
click node_signals "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/recommendation/signal.py"
click node_shap "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/explainability/shap_analysis.py"
click node_risk "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/evaluation/risk.py"
click node_dashboard "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/dashboard/app.py"
click node_report "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/export_report.py"
click node_logger "https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/src/utils/logger.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_prices,node_fundamentals,node_news,node_marketdata,node_database,node_analyst toneBlue
class node_builder,node_technical,node_fundamental,node_valuation,node_sentiment,node_finbert toneAmber
class node_trainer,node_decisiontree,node_xgboostscratch,node_metrics,node_backtest toneMint
class node_signals,node_shap,node_risk,node_dashboard,node_report toneRose
class node_main,node_config,node_logger toneTeal
```

## Components

### Data ingestion

- [Price ingestion](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/fetcher.py): `data/fetcher.py`
- [Fundamentals ingestion](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/fetcher.py): `data/fetcher.py`
- [News ingestion](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/news_fetcher.py): `data/news_fetcher.py`
- **Market data provider**
- [SQLite research store](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/data/storage.py): `data/storage.py`

### Feature engineering

- [Feature and target builder](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/builder.py): `features/builder.py`
- [Technical indicators](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/technical.py): `features/technical.py`
- [Fundamental ratios](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/fundamental.py): `features/fundamental.py`
- [Valuation metrics](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/valuation.py): `features/valuation.py`
- [FinBERT sentiment](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/features/sentiment.py): `features/sentiment.py`
- **FinBERT model**

### Model research

- [Model training and comparison](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/trainer.py): `models/trainer.py`
- [Scratch decision tree](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/decision_tree.py): `models/decision_tree.py`
- [Scratch XGBoost](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/models/xgboost_model.py): `models/xgboost_model.py`
- [Prediction metrics](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/evaluation/metrics.py): `evaluation/metrics.py`
- [Walk-forward validation](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/backtest/walkforward.py): `backtest/walkforward.py`

### Signals and research

- [BUY HOLD SELL signals](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/recommendation/signal.py): `recommendation/signal.py`
- [SHAP explainability](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/explainability/shap_analysis.py): `explainability/shap_analysis.py`
- [Signal basket risk](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/evaluation/risk.py): `evaluation/risk.py`
- [Interactive dashboard](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/dashboard/app.py): `dashboard/app.py`
- [Research report export](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/export_report.py): `export_report.py`

### Other components

- **Research user**
- [Pipeline runner](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/main.py): `main.py`
- [Universe and settings](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/config.py): `config.py`
- [Logging](https://github.com/bhumikaaggwl/equity-return-prediction-alpha-signal-model/blob/main/src/utils/logger.py): `src/utils/logger.py`

## Connections

- Research user → Pipeline runner: starts pipeline (evidence: `README.md`)
- Research user → Interactive dashboard: explores research (evidence: `README.md`)
- Pipeline runner → SQLite research store: initializes (evidence: `main.py`)
- Pipeline runner → Price ingestion: fetches prices (evidence: `main.py`)
- Pipeline runner → Fundamentals ingestion: fetches fundamentals (evidence: `main.py`)
- Pipeline runner → News ingestion: fetches headlines (evidence: `main.py`)
- Pipeline runner → Model training and comparison: trains models (evidence: `main.py`)
- Pipeline runner → Walk-forward validation: runs validation (evidence: `main.py`)
- Price ingestion → Market data provider: downloads prices (evidence: `README.md`)
- Fundamentals ingestion → Market data provider: fetches fundamentals (evidence: `README.md`)
- News ingestion → Market data provider: fetches news (evidence: `README.md`)
- Price ingestion → SQLite research store: writes prices (evidence: `data/fetcher.py`)
- Fundamentals ingestion → SQLite research store: writes records (evidence: `data/fetcher.py`)
- News ingestion → SQLite research store: writes headlines (evidence: `data/news_fetcher.py`)
- Feature and target builder → SQLite research store: reads prices (evidence: `features/builder.py`)
- Feature and target builder → Technical indicators: computes indicators (evidence: `features/builder.py`)
- Feature and target builder → Fundamental ratios: computes ratios (evidence: `features/builder.py`)
- Feature and target builder → Valuation metrics: computes valuation (evidence: `features/builder.py`)
- Feature and target builder → FinBERT sentiment: merges sentiment (evidence: `features/builder.py`)
- FinBERT sentiment → SQLite research store: reads headlines (evidence: `features/sentiment.py`)
- FinBERT sentiment → FinBERT model: scores headlines (evidence: `features/sentiment.py`)
- Model training and comparison → Feature and target builder: builds training data (evidence: `models/trainer.py`)
- Model training and comparison → Scratch decision tree: trains scratch tree (evidence: `models/trainer.py`)
- Model training and comparison → Scratch XGBoost: trains scratch model (evidence: `models/trainer.py`)
- Model training and comparison → Prediction metrics: scores predictions (evidence: `models/trainer.py`)
- Model training and comparison → SQLite research store: stores metrics (evidence: `models/trainer.py`)
- Walk-forward validation → Feature and target builder: builds test data (evidence: `backtest/walkforward.py`)
- Walk-forward validation → Prediction metrics: evaluates folds (evidence: `backtest/walkforward.py`)
- Walk-forward validation → BUY HOLD SELL signals: counts fold signals (evidence: `backtest/walkforward.py`)
- Model training and comparison → BUY HOLD SELL signals: generates saved signals (evidence: `models/trainer.py`)
- Interactive dashboard → SQLite research store: reads research data (evidence: `dashboard/app.py`)
- Interactive dashboard → Feature and target builder: builds features (evidence: `dashboard/app.py`)
- Interactive dashboard → BUY HOLD SELL signals: generates signals (evidence: `dashboard/app.py`)
- Interactive dashboard → Prediction metrics: computes metrics (evidence: `dashboard/app.py`)
- Interactive dashboard → Walk-forward validation: runs backtest (evidence: `dashboard/app.py`)
- Interactive dashboard → SHAP explainability: explains predictions (evidence: `README.md`)
- Research report export → Signal basket risk: reports risk (evidence: `export_report.py`)
- Signal basket risk → SQLite research store: reads signal data (evidence: `evaluation/risk.py`)
- Pipeline runner → Logging: logs pipeline (evidence: `main.py`)
- Model training and comparison → Logging: logs training (evidence: `models/trainer.py`)
- Universe and settings → SQLite research store: sets database path (evidence: `data/storage.py`)
