# nbucci4325/stockga architecture

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

- Interactive diagram: https://gitdiagram.com/nbucci4325/stockga
- Repository: https://github.com/nbucci4325/stockga

## Overview

This project combines a broadly trained neural network with a per-stock genetic search: the network estimates forward volatility, a configured mapping turns that estimate into a crossover rate, and the GA evolves and backtests indicator strategies before producing a BUY/SELL/HOLD decision. The training workflow and experiment workflow share data, indicators, and feature engineering. Edges reflect the sampled source and README; GA internals not fully shown in the excerpts are represented only where the README documents them.

Main entry points: [`ga.py`](https://github.com/nbucci4325/stockga/blob/main/ga.py) (GA Command), [`run_experiment.py`](https://github.com/nbucci4325/stockga/blob/main/run_experiment.py) (Single-Stock Experiment), [`data/fetcher.py`](https://github.com/nbucci4325/stockga/blob/main/data/fetcher.py) (Market Data Fetcher), [`config.py`](https://github.com/nbucci4325/stockga/blob/main/config.py) (Shared Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_features["Market Data &amp; Features"]
  node_fetcher["Market Data Fetcher<br/>[fetcher.py]"]
  node_indicators["Fixed Indicators<br/>[indicators.py]"]
  node_dataset["Feature &amp; Label Builder<br/>[dataset_builder.py]"]
end

subgraph group_volatility_model["Volatility Model"]
  node_train_entry["NN Training Workflow<br/>[train_nn.py]"]
  node_nn_training["Model Training &amp; Evaluation<br/>[train.py]"]
  node_nn_model["Volatility Model &amp; Artifacts<br/>[nn_model.py]"]
  node_experiment["Single-Stock Experiment<br/>[run_experiment.py]"]
  node_prediction["Volatility &amp; Rate Mapping<br/>[predict.py]"]
end

subgraph group_strategy_ga["Strategy Evolution"]
  node_ga_entry["GA Command<br/>[ga.py]"]
  node_evolution["Strategy Evolution<br/>[ga.py]"]
  node_backtest["Signal Backtest<br/>[ga.py]"]
  node_decision["Live Decision<br/>[ga.py]"]
end

subgraph group_outputs_config["Configuration &amp; Results"]
  node_config["Shared Configuration<br/>[config.py]"]
  node_decision_log[("Decision Log<br/>[decisions.csv]")]
  node_results[("GA Results<br/>[results.csv]")]
end

node_user(("User"))
node_yfinance["Yahoo Finance"]

node_user -->|"trains model"| node_train_entry
node_user -->|"chooses ticker"| node_experiment
node_user -->|"runs GA"| node_ga_entry
node_fetcher -->|"downloads prices"| node_yfinance
node_train_entry -->|"gets training dates"| node_fetcher
node_train_entry -->|"builds dataset"| node_dataset
node_dataset -->|"fetches tickers"| node_fetcher
node_dataset -->|"adds indicators"| node_indicators
node_train_entry -->|"trains and evaluates"| node_nn_training
node_nn_training -->|"builds model"| node_nn_model
node_train_entry -->|"saves artifacts"| node_nn_model
node_experiment -->|"fetches buffered prices"| node_fetcher
node_experiment -->|"computes indicators"| node_indicators
node_experiment -->|"builds features"| node_dataset
node_experiment -->|"predicts rate"| node_prediction
node_prediction -->|"loads artifacts"| node_nn_model
node_experiment -->|"hands off data and rate"| node_ga_entry
node_ga_entry -->|"gets experiment inputs"| node_experiment
node_ga_entry -->|"starts search"| node_evolution
node_evolution -->|"scores candidates"| node_backtest
node_ga_entry -->|"produces action"| node_decision
node_ga_entry -->|"fetches price history"| node_fetcher
node_ga_entry -->|"computes strategy signals"| node_indicators
node_ga_entry -->|"appends decision"| node_decision_log
node_ga_entry -.->|"records fitness"| node_results
node_fetcher -->|"reads data settings"| node_config
node_indicators -->|"reads indicator settings"| node_config
node_dataset -->|"reads label settings"| node_config
node_nn_training -->|"reads training settings"| node_config
node_prediction -->|"reads mapping settings"| node_config
node_evolution -->|"uses gene constraints"| node_config

click node_fetcher "https://github.com/nbucci4325/stockga/blob/main/data/fetcher.py"
click node_indicators "https://github.com/nbucci4325/stockga/blob/main/features/indicators.py"
click node_dataset "https://github.com/nbucci4325/stockga/blob/main/features/dataset_builder.py"
click node_train_entry "https://github.com/nbucci4325/stockga/blob/main/train_nn.py"
click node_nn_training "https://github.com/nbucci4325/stockga/blob/main/model/train.py"
click node_nn_model "https://github.com/nbucci4325/stockga/blob/main/model/nn_model.py"
click node_experiment "https://github.com/nbucci4325/stockga/blob/main/run_experiment.py"
click node_prediction "https://github.com/nbucci4325/stockga/blob/main/model/predict.py"
click node_config "https://github.com/nbucci4325/stockga/blob/main/config.py"
click node_ga_entry "https://github.com/nbucci4325/stockga/blob/main/ga.py"
click node_evolution "https://github.com/nbucci4325/stockga/blob/main/ga.py"
click node_backtest "https://github.com/nbucci4325/stockga/blob/main/ga.py"
click node_decision "https://github.com/nbucci4325/stockga/blob/main/ga.py"
click node_decision_log "https://github.com/nbucci4325/stockga/blob/main/decisions.csv"
click node_results "https://github.com/nbucci4325/stockga/blob/main/results.csv"

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_fetcher,node_indicators,node_dataset,node_user toneBlue
class node_train_entry,node_nn_training,node_nn_model,node_experiment,node_prediction toneAmber
class node_ga_entry,node_evolution,node_backtest,node_decision toneMint
class node_config,node_decision_log,node_results toneRose
class node_yfinance toneIndigo
```

## Components

### Market Data & Features

- [Market Data Fetcher](https://github.com/nbucci4325/stockga/blob/main/data/fetcher.py): `data/fetcher.py`
- [Fixed Indicators](https://github.com/nbucci4325/stockga/blob/main/features/indicators.py): `features/indicators.py`
- [Feature & Label Builder](https://github.com/nbucci4325/stockga/blob/main/features/dataset_builder.py): `features/dataset_builder.py`

### Volatility Model

- [NN Training Workflow](https://github.com/nbucci4325/stockga/blob/main/train_nn.py): `train_nn.py`
- [Model Training & Evaluation](https://github.com/nbucci4325/stockga/blob/main/model/train.py): `model/train.py`
- [Volatility Model & Artifacts](https://github.com/nbucci4325/stockga/blob/main/model/nn_model.py): `model/nn_model.py`
- [Single-Stock Experiment](https://github.com/nbucci4325/stockga/blob/main/run_experiment.py): `run_experiment.py`
- [Volatility & Rate Mapping](https://github.com/nbucci4325/stockga/blob/main/model/predict.py): `model/predict.py`

### Strategy Evolution

- [GA Command](https://github.com/nbucci4325/stockga/blob/main/ga.py): `ga.py`
- [Strategy Evolution](https://github.com/nbucci4325/stockga/blob/main/ga.py): `ga.py`
- [Signal Backtest](https://github.com/nbucci4325/stockga/blob/main/ga.py): `ga.py`
- [Live Decision](https://github.com/nbucci4325/stockga/blob/main/ga.py): `ga.py`

### Configuration & Results

- [Shared Configuration](https://github.com/nbucci4325/stockga/blob/main/config.py): `config.py`
- [Decision Log](https://github.com/nbucci4325/stockga/blob/main/decisions.csv): `decisions.csv`
- [GA Results](https://github.com/nbucci4325/stockga/blob/main/results.csv): `results.csv`

### Other components

- **User**
- **Yahoo Finance**

## Connections

- User → NN Training Workflow: trains model (evidence: `README.md`)
- User → Single-Stock Experiment: chooses ticker (evidence: `README.md`)
- User → GA Command: runs GA (evidence: `README.md`)
- Market Data Fetcher → Yahoo Finance: downloads prices (evidence: `data/fetcher.py`)
- NN Training Workflow → Market Data Fetcher: gets training dates (evidence: `train_nn.py`)
- NN Training Workflow → Feature & Label Builder: builds dataset (evidence: `train_nn.py`)
- Feature & Label Builder → Market Data Fetcher: fetches tickers (evidence: `features/dataset_builder.py`)
- Feature & Label Builder → Fixed Indicators: adds indicators (evidence: `features/dataset_builder.py`)
- NN Training Workflow → Model Training & Evaluation: trains and evaluates (evidence: `train_nn.py`)
- Model Training & Evaluation → Volatility Model & Artifacts: builds model (evidence: `model/train.py`)
- NN Training Workflow → Volatility Model & Artifacts: saves artifacts (evidence: `train_nn.py`)
- Single-Stock Experiment → Market Data Fetcher: fetches buffered prices (evidence: `run_experiment.py`)
- Single-Stock Experiment → Fixed Indicators: computes indicators (evidence: `run_experiment.py`)
- Single-Stock Experiment → Feature & Label Builder: builds features (evidence: `run_experiment.py`)
- Single-Stock Experiment → Volatility & Rate Mapping: predicts rate (evidence: `run_experiment.py`)
- Volatility & Rate Mapping → Volatility Model & Artifacts: loads artifacts (evidence: `model/predict.py`)
- Single-Stock Experiment → GA Command: hands off data and rate (evidence: `README.md`)
- GA Command → Single-Stock Experiment: gets experiment inputs (evidence: `ga.py`)
- GA Command → Strategy Evolution: starts search (evidence: `README.md`)
- Strategy Evolution → Signal Backtest: scores candidates (evidence: `README.md`)
- GA Command → Live Decision: produces action (evidence: `README.md`)
- GA Command → Market Data Fetcher: fetches price history (evidence: `ga.py`)
- GA Command → Fixed Indicators: computes strategy signals (evidence: `ga.py`)
- GA Command → Decision Log: appends decision (evidence: `ga.py`)
- GA Command → GA Results: records fitness (evidence: `README.md`)
- Market Data Fetcher → Shared Configuration: reads data settings (evidence: `data/fetcher.py`)
- Fixed Indicators → Shared Configuration: reads indicator settings (evidence: `features/indicators.py`)
- Feature & Label Builder → Shared Configuration: reads label settings (evidence: `features/dataset_builder.py`)
- Model Training & Evaluation → Shared Configuration: reads training settings (evidence: `model/train.py`)
- Volatility & Rate Mapping → Shared Configuration: reads mapping settings (evidence: `model/predict.py`)
- Strategy Evolution → Shared Configuration: uses gene constraints (evidence: `ga.py`)
