# elhaouchomar/sp500-strategies architecture

> Architecture diagram of the GitHub repository elhaouchomar/sp500-strategies, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elhaouchomar/sp500-strategies
- Repository: https://github.com/elhaouchomar/sp500-strategies

## Overview

This repository implements a stock-direction machine-learning and backtesting workflow: historical prices become technical features and a future-return target; date-based cross-validation selects a classifier; out-of-fold and test predictions become trading positions; and backtesting produces performance metrics and a report. The graph follows the calls visible in `run_all.py` and the sampled modules. The README is empty, so unsampled capabilities and wiring are not inferred.

Main entry points: [`project/scripts/run_all.py`](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/run_all.py) (Workflow runner), [`project/data`](https://github.com/elhaouchomar/sp500-strategies/tree/master/project/data) (Train/test dataset), [`project/scripts/features_engineering.py`](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/features_engineering.py) (Feature engineering), [`project/scripts/gridsearch.py`](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/gridsearch.py) (CV grid search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Market Data Prep"]
  node_prices["Stock prices<br/>[all_stocks_5yr.csv]"]
  node_features["Feature engineering"]
  node_train_data["Train/test dataset"]
end

subgraph group_training["Model Training"]
  node_runner["Workflow runner<br/>[run_all.py]"]
  node_search["CV grid search<br/>[gridsearch.py]"]
  node_selected_model["Selected pipeline<br/>[selected_model.pkl]"]
  node_model_metrics["Fold metrics<br/>[model_selection.py]"]
  node_cv_results["CV reports"]
end

subgraph group_signals["Signals"]
  node_signal_builder["Signal generation<br/>[create_signal.py]"]
  node_signal_file["ML signal<br/>[ml_signal.csv]"]
end

subgraph group_backtest["Backtesting"]
  node_index["Index prices<br/>[HistoricalData.csv]"]
  node_backtest["Strategy backtest<br/>[backtest.py]"]
  node_strategy_results["Strategy results<br/>[results.csv]"]
  node_report["Strategy report<br/>[report.md]"]
end

node_user(("Analyst"))

node_user -->|"runs workflow"| node_runner
node_runner -->|"builds dataset"| node_features
node_features -->|"reads prices"| node_prices
node_features -->|"writes splits"| node_train_data
node_runner -->|"searches models"| node_search
node_search -->|"fits on training data"| node_train_data
node_search -->|"saves best pipeline"| node_selected_model
node_runner -->|"computes fold metrics"| node_model_metrics
node_runner -->|"loads pipeline"| node_selected_model
node_model_metrics -->|"evaluates folds"| node_train_data
node_runner -->|"writes metrics"| node_cv_results
node_runner -->|"generates predictions"| node_signal_builder
node_signal_builder -->|"loads pipeline"| node_selected_model
node_signal_builder -->|"fits and predicts"| node_train_data
node_runner -->|"writes signals"| node_signal_file
node_runner -->|"runs backtest"| node_backtest
node_backtest -->|"uses signals"| node_signal_file
node_backtest -->|"computes returns"| node_prices
node_runner -->|"reads benchmark"| node_index
node_runner -->|"writes metrics"| node_strategy_results
node_runner -->|"writes report"| node_report

click node_runner "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/run_all.py"
click node_prices "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/data/all_stocks_5yr.csv"
click node_index "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/data/HistoricalData.csv"
click node_features "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/features_engineering.py"
click node_train_data "https://github.com/elhaouchomar/sp500-strategies/tree/master/project/data"
click node_search "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/gridsearch.py"
click node_selected_model "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/selected-model/selected_model.pkl"
click node_model_metrics "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/model_selection.py"
click node_cv_results "https://github.com/elhaouchomar/sp500-strategies/tree/master/project/results/cross-validation"
click node_signal_builder "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/create_signal.py"
click node_signal_file "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/selected-model/ml_signal.csv"
click node_backtest "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/strategy/backtest.py"
click node_strategy_results "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/strategy/results.csv"
click node_report "https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/strategy/report.md"

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_features,node_train_data toneBlue
class node_runner,node_search,node_selected_model,node_model_metrics,node_cv_results toneAmber
class node_signal_builder,node_signal_file toneMint
class node_index,node_backtest,node_strategy_results,node_report toneRose
class node_user toneIndigo
```

## Components

### Market Data Prep

- [Stock prices](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/data/all_stocks_5yr.csv): `project/data/all_stocks_5yr.csv`
- [Feature engineering](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/features_engineering.py): `project/scripts/features_engineering.py`
- [Train/test dataset](https://github.com/elhaouchomar/sp500-strategies/tree/master/project/data): `project/data`

### Model Training

- [Workflow runner](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/run_all.py): `project/scripts/run_all.py`
- [CV grid search](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/gridsearch.py): `project/scripts/gridsearch.py`
- [Selected pipeline](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/selected-model/selected_model.pkl): `project/results/selected-model/selected_model.pkl`
- [Fold metrics](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/model_selection.py): `project/scripts/model_selection.py`
- [CV reports](https://github.com/elhaouchomar/sp500-strategies/tree/master/project/results/cross-validation): `project/results/cross-validation`

### Signals

- [Signal generation](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/create_signal.py): `project/scripts/create_signal.py`
- [ML signal](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/selected-model/ml_signal.csv): `project/results/selected-model/ml_signal.csv`

### Backtesting

- [Index prices](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/data/HistoricalData.csv): `project/data/HistoricalData.csv`
- [Strategy backtest](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/scripts/strategy/backtest.py): `project/scripts/strategy/backtest.py`
- [Strategy results](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/strategy/results.csv): `project/results/strategy/results.csv`
- [Strategy report](https://github.com/elhaouchomar/sp500-strategies/blob/master/project/results/strategy/report.md): `project/results/strategy/report.md`

### Other components

- **Analyst**

## Connections

- Analyst → Workflow runner: runs workflow
- Workflow runner → Feature engineering: builds dataset
- Feature engineering → Stock prices: reads prices
- Feature engineering → Train/test dataset: writes splits
- Workflow runner → CV grid search: searches models
- CV grid search → Train/test dataset: fits on training data
- CV grid search → Selected pipeline: saves best pipeline
- Workflow runner → Fold metrics: computes fold metrics
- Workflow runner → Selected pipeline: loads pipeline
- Fold metrics → Train/test dataset: evaluates folds
- Workflow runner → CV reports: writes metrics
- Workflow runner → Signal generation: generates predictions
- Signal generation → Selected pipeline: loads pipeline
- Signal generation → Train/test dataset: fits and predicts
- Workflow runner → ML signal: writes signals
- Workflow runner → Strategy backtest: runs backtest
- Strategy backtest → ML signal: uses signals
- Strategy backtest → Stock prices: computes returns
- Workflow runner → Index prices: reads benchmark
- Workflow runner → Strategy results: writes metrics
- Workflow runner → Strategy report: writes report