# jedaniel777-tech/ai-investing architecture

> Architecture diagram of the GitHub repository jedaniel777-tech/ai-investing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jedaniel777-tech/ai-investing
- Repository: https://github.com/jedaniel777-tech/ai-investing

## Overview

1. **Repository purpose**
   - This is a Python command-line toolkit for constructing and testing quantitative stock portfolios.
   - The core workflow is: choose a stock universe, fetch historical prices, build multiple optimized portfolios, then backtest and/or forward-test them against a benchmark index.

2. **Primary entrypoint and orchestration**
   - `portfolio_manager.py` is the main coordinator described in the README.
   - It accepts CLI flags such as `is_test`, `future_bars`, `data_granularity_minutes`, `history_to_use`, `apply_noise_filtering`, `market_index`, `only_long`, `eigen_portfolio_number`, and `stocks_file_path`.
   - This file likely drives the full pipeline: input parsing, data loading, strategy execution, and results reporting.

3. **Input boundary: stock universe files**
   - The `stocks/` folder contains plain-text ticker lists like `stocks.txt` and `all_stocks.txt`.
   - These files define the investable universe and are the main user-controlled input to the system.
   - The architecture is universe-driven rather than market-wide; the strategies only operate on the symbols listed here.

4. **Market data ingestion**
   - `data_loader.py` is the data access layer.
   - The README states it loads historical price data from Yahoo Finance via `yfinance`.
   - It likely normalizes time granularity, trims history based on the requested window, and splits the data into training and optional out-of-sample test ranges.

5. **Strategy subsystem**
   - The `strategies/` package contains the portfolio construction algorithms:
     - `eigen_portfolio_strategy.py`
     - `minimum_variance_strategy.py`
     - `maximum_sharpe_ratio_strategy.py`
     - `genetic_algo_strategy.py`
   - These strategies all consume the same market data/returns inputs but differ in how they optimize portfolio weights and risk/reward characteristics.

6. **Shared strategy utilities and dispatch**
   - `strategies/strategy_helper_functions.py` appears to hold reusable math and preprocessing helpers used by multiple strategies.
   - `strategy_manager.py` is the abstraction layer that selects and coordinates the implemented strategies, so the orchestrator does not need to know strategy-specific details.

7. **Optimization and risk modeling**
   - The strategies rely on return series, covariance estimation, and portfolio optimization.
   - The README highlights “noise filtering” using random matrix theory, which affects covariance estimation before optimization.
   - `only_long` and `eigen_portfolio_number` are important control parameters that materially change the optimization boundary conditions.

8. **Evaluation subsystem**
   - `backtester.py` is responsible for measuring how generated portfolios perform over historical and forward periods.
   - It compares strategy returns against the chosen benchmark index such as `SPY` or `QQQ`.
   - This is the main validation boundary between “portfolio generation” and “performance assessment.”

9. **Forward simulation**
   - `simulator.py` provides a Monte Carlo style future-price/return simulation based on historical returns.
   - This is a separate analysis path from backtesting: backtesting uses actual historical out-of-sample data, while simulation projects possible future outcomes from the observed distribution.

10. **Validation and command metadata**
   - `argchecker.py` likely validates CLI arguments and enforces consistency between flags such as `is_test` and `future_bars`.
   - `commands.json` appears to store example or preset commands, supporting reproducible runs and user guidance.

11. **Packaging and runtime**
   - The project is a pure Python analytics tool, not a web service.
   - `requirements.txt` shows the key runtime dependencies: NumPy, Pandas, SciPy, scikit-learn, tqdm, and yfinance.
   - `Dockerfile` indicates the tool can be run in a containerized environment, which is useful for reproducibility.

12. **End-to-end data flow**
   - The high-level flow is: stock list → Yahoo Finance price history → return/covariance construction → strategy optimization → portfolio weights → backtest/simulation → benchmark comparison and output.
   - There is no evidence of a database or long-lived state; the system appears to be file/input driven and compute-oriented.

13. **Diagram boundary suggestion**
   - For an architecture diagram, the clearest split is:
     - **Inputs**: stock list files, CLI flags, benchmark symbol
     - **Core engine**: data loader + strategy manager + strategy implementations
     - **Evaluation**: backtester + simulator
     - **Outputs**: portfolio weights, performance plots/results, optional forward-test comparisons

Main entry points: [`portfolio_manager.py`](https://github.com/jedaniel777-tech/ai-investing/blob/master/portfolio_manager.py) (Portfolio manager), [`strategy_manager.py`](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategy_manager.py) (Strategy manager), [`strategies/strategy_helper_functions.py`](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/strategy_helper_functions.py) (Strategy helpers), [`data_loader.py`](https://github.com/jedaniel777-tech/ai-investing/blob/master/data_loader.py) (Data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_stocks_txt["Stocks list<br/>universe file<br/>[stocks.txt]"]
  node_all_stocks_txt["All stocks<br/>universe file<br/>[all_stocks.txt]"]
  node_commands_json["Commands<br/>preset runs<br/>[commands.json]"]
end

subgraph group_core["Core Engine"]
  node_portfolio_manager["Portfolio manager<br/>cli orchestrator"]
  node_argchecker["Arg checker<br/>cli validation<br/>[argchecker.py]"]
  node_data_loader["Data loader<br/>market data<br/>[data_loader.py]"]
  node_strategy_manager["Strategy manager<br/>dispatch layer"]
end

subgraph group_strategies["Strategies"]
  node_eigen_strategy["Eigen portfolio<br/>optimizer"]
  node_minvar_strategy["Min variance<br/>optimizer"]
  node_maxsharpe_strategy["Max Sharpe<br/>optimizer"]
  node_genetic_strategy["Genetic algo<br/>optimizer"]
  node_strategy_helpers["Strategy helpers<br/>math utilities"]
end

subgraph group_evaluation["Evaluation"]
  node_backtester["Backtester<br/>performance eval<br/>[backtester.py]"]
  node_simulator["Simulator<br/>future simulation<br/>[simulator.py]"]
end

subgraph group_runtime["Runtime"]
  node_requirements_txt["Requirements<br/>dependencies<br/>[requirements.txt]"]
  node_dockerfile["Dockerfile<br/>container build"]
end

node_stocks_txt -->|"universe input"| node_portfolio_manager
node_all_stocks_txt -->|"universe input"| node_portfolio_manager
node_commands_json -->|"preset commands"| node_portfolio_manager
node_portfolio_manager -->|"validate args"| node_argchecker
node_portfolio_manager -->|"request data"| node_data_loader
node_data_loader -->|"price/returns"| node_strategy_manager
node_strategy_manager -->|"dispatch"| node_eigen_strategy
node_strategy_manager -->|"dispatch"| node_minvar_strategy
node_strategy_manager -->|"dispatch"| node_maxsharpe_strategy
node_strategy_manager -->|"dispatch"| node_genetic_strategy
node_eigen_strategy -->|"use helpers"| node_strategy_helpers
node_minvar_strategy -->|"use helpers"| node_strategy_helpers
node_maxsharpe_strategy -->|"use helpers"| node_strategy_helpers
node_genetic_strategy -->|"use helpers"| node_strategy_helpers
node_strategy_manager -->|"portfolio weights"| node_backtester
node_portfolio_manager -->|"evaluate"| node_backtester
node_portfolio_manager -->|"simulate"| node_simulator
node_backtester -.->|"shared stats"| node_simulator
node_requirements_txt -.->|"depends on"| node_data_loader
node_requirements_txt -.->|"depends on"| node_strategy_manager
node_dockerfile -.->|"run target"| node_portfolio_manager

click node_portfolio_manager "https://github.com/jedaniel777-tech/ai-investing/blob/master/portfolio_manager.py"
click node_argchecker "https://github.com/jedaniel777-tech/ai-investing/blob/master/argchecker.py"
click node_data_loader "https://github.com/jedaniel777-tech/ai-investing/blob/master/data_loader.py"
click node_strategy_manager "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategy_manager.py"
click node_eigen_strategy "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/eigen_portfolio_strategy.py"
click node_minvar_strategy "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/minimum_variance_strategy.py"
click node_maxsharpe_strategy "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/maximum_sharpe_ratio_strategy.py"
click node_genetic_strategy "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/genetic_algo_strategy.py"
click node_strategy_helpers "https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/strategy_helper_functions.py"
click node_backtester "https://github.com/jedaniel777-tech/ai-investing/blob/master/backtester.py"
click node_simulator "https://github.com/jedaniel777-tech/ai-investing/blob/master/simulator.py"
click node_stocks_txt "https://github.com/jedaniel777-tech/ai-investing/blob/master/stocks/stocks.txt"
click node_all_stocks_txt "https://github.com/jedaniel777-tech/ai-investing/blob/master/stocks/all_stocks.txt"
click node_commands_json "https://github.com/jedaniel777-tech/ai-investing/blob/master/commands.json"
click node_requirements_txt "https://github.com/jedaniel777-tech/ai-investing/blob/master/requirements.txt"
click node_dockerfile "https://github.com/jedaniel777-tech/ai-investing/tree/master/Dockerfile"

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_stocks_txt,node_all_stocks_txt,node_commands_json toneBlue
class node_portfolio_manager,node_argchecker,node_data_loader,node_strategy_manager toneAmber
class node_eigen_strategy,node_minvar_strategy,node_maxsharpe_strategy,node_genetic_strategy,node_strategy_helpers toneMint
class node_backtester,node_simulator toneRose
class node_requirements_txt,node_dockerfile toneIndigo
```

## Components

### Inputs

User-controlled universe and run configuration.

- [Stocks list](https://github.com/jedaniel777-tech/ai-investing/blob/master/stocks/stocks.txt): universe file · Primary ticker universe input file. · `stocks/stocks.txt`
- [All stocks](https://github.com/jedaniel777-tech/ai-investing/blob/master/stocks/all_stocks.txt): universe file · Broader ticker universe input file. · `stocks/all_stocks.txt`
- [Commands](https://github.com/jedaniel777-tech/ai-investing/blob/master/commands.json): preset runs · Example or preset command configurations for reproducible execution. · `commands.json`

### Core Engine

Data loading, orchestration, and strategy selection.

- [Portfolio manager](https://github.com/jedaniel777-tech/ai-investing/blob/master/portfolio_manager.py): cli orchestrator · Main command-line entrypoint that coordinates the end-to-end portfolio workflow. · `portfolio_manager.py`
- [Arg checker](https://github.com/jedaniel777-tech/ai-investing/blob/master/argchecker.py): cli validation · Validates command-line arguments and run-mode consistency. · `argchecker.py`
- [Data loader](https://github.com/jedaniel777-tech/ai-investing/blob/master/data_loader.py): market data · Fetches and prepares historical price data for the selected universe. · `data_loader.py`
- [Strategy manager](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategy_manager.py): dispatch layer · Selects and coordinates the portfolio construction strategies. · `strategy_manager.py`

### Strategies

Portfolio construction algorithms and shared helpers.

- [Eigen portfolio](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/eigen_portfolio_strategy.py): optimizer · Builds portfolios using eigenvector-based allocation logic. · `strategies/eigen_portfolio_strategy.py`
- [Min variance](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/minimum_variance_strategy.py): optimizer · Constructs low-volatility portfolios by minimizing variance. · `strategies/minimum_variance_strategy.py`
- [Max Sharpe](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/maximum_sharpe_ratio_strategy.py): optimizer · Optimizes portfolios for risk-adjusted return. · `strategies/maximum_sharpe_ratio_strategy.py`
- [Genetic algo](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/genetic_algo_strategy.py): optimizer · Searches for portfolio weights using evolutionary optimization. · `strategies/genetic_algo_strategy.py`
- [Strategy helpers](https://github.com/jedaniel777-tech/ai-investing/blob/master/strategies/strategy_helper_functions.py): math utilities · Shared preprocessing, return handling, and optimization helpers. · `strategies/strategy_helper_functions.py`

### Evaluation

Backtesting and forward simulation of candidate portfolios.

- [Backtester](https://github.com/jedaniel777-tech/ai-investing/blob/master/backtester.py): performance eval · Measures historical and out-of-sample portfolio performance against a benchmark. · `backtester.py`
- [Simulator](https://github.com/jedaniel777-tech/ai-investing/blob/master/simulator.py): future simulation · Generates forward-looking price or return scenarios from observed data. · `simulator.py`

### Runtime

Packaging and execution metadata.

- [Requirements](https://github.com/jedaniel777-tech/ai-investing/blob/master/requirements.txt): dependencies · Python runtime dependencies used by the toolkit. · `requirements.txt`
- [Dockerfile](https://github.com/jedaniel777-tech/ai-investing/tree/master/Dockerfile): container build · Container image definition for reproducible execution. · `Dockerfile`

## Connections

- Stocks list → Portfolio manager: universe input · Ticker list selected for a run.
- All stocks → Portfolio manager: universe input · Alternative broader ticker list.
- Commands → Portfolio manager: preset commands · Provides runnable examples or presets.
- Portfolio manager → Arg checker: validate args · Checks CLI flags and run-mode constraints.
- Portfolio manager → Data loader: request data · Loads historical prices for the chosen universe.
- Data loader → Strategy manager: price/returns · Supplies prepared market data for strategy execution.
- Strategy manager → Eigen portfolio: dispatch · Runs eigen-portfolio construction.
- Strategy manager → Min variance: dispatch · Runs minimum-variance optimization.
- Strategy manager → Max Sharpe: dispatch · Runs maximum Sharpe optimization.
- Strategy manager → Genetic algo: dispatch · Runs genetic-algorithm optimization.
- Eigen portfolio → Strategy helpers: use helpers · Shares preprocessing and math utilities.
- Min variance → Strategy helpers: use helpers · Shares preprocessing and math utilities.
- Max Sharpe → Strategy helpers: use helpers · Shares preprocessing and math utilities.
- Genetic algo → Strategy helpers: use helpers · Shares preprocessing and math utilities.
- Strategy manager → Backtester: portfolio weights · Passes candidate portfolios for evaluation.
- Portfolio manager → Backtester: evaluate · Triggers historical and benchmark comparison.
- Portfolio manager → Simulator: simulate · Triggers forward outcome generation.
- Backtester → Simulator: shared stats · Uses historical return structure as analysis context.
- Requirements → Data loader: depends on · Lists runtime libraries used by ingestion and analytics.
- Requirements → Strategy manager: depends on · Lists runtime libraries used by optimization routines.
- Dockerfile → Portfolio manager: run target · Container entry environment for the CLI workflow.
