# codewithjaswanth/jev-alpaca-trader architecture

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

- Interactive diagram: https://gitdiagram.com/codewithjaswanth/jev-alpaca-trader
- Repository: https://github.com/codewithjaswanth/jev-alpaca-trader

## Overview

JEV-ALPACA-TRADER is a quantitative trading application built around market-data ingestion, strategy selection, portfolio construction, backtesting, and Alpaca execution, with a Streamlit dashboard as an alternate user interface. The CLI and dashboard expose data, backtest, and trading workflows; adaptive rotation is a separately orchestrated strategy with regime, ranking, exception, and risk stages. The graph includes documented ML and fundamental-selection capabilities. Some subsystem links rely on README descriptions or the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py) (Rotation Orchestrator), [`FinRL-Trading/src/web/app.py`](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/web/app.py) (Streamlit Dashboard), [`FinRL-Trading/src/data/data_fetcher.py`](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_fetcher.py) (Data Fetcher), [`FinRL-Trading/src/main.py`](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/main.py) (CLI Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry And Interface"]
  node_cli["CLI Router<br/>[main.py]"]
  node_dashboard["Streamlit Dashboard<br/>[app.py]"]
  node_settings["Application Settings<br/>[settings.py]"]
end

subgraph group_data["Market Data"]
  node_providers["Market Data Providers"]
  node_fetcher["Data Fetcher<br/>[data_fetcher.py]"]
  node_processor["Feature Processing<br/>[data_processor.py]"]
  node_store[("SQLite Data Store<br/>[data_store.py]")]
  node_calendar["Trading Calendar"]
end

subgraph group_strategy["Strategy And Portfolio"]
  node_ml["ML Stock Selection<br/>[ml_strategy.py]"]
  node_buckets["Bucket Selection"]
  node_fundamental["Fundamental DRL"]
  node_base["Strategy Contract<br/>[base_strategy.py]"]
end

subgraph group_execution["Trading And Analysis"]
  node_backtest["Backtest Engine<br/>[backtest_engine.py]"]
  node_executor["Trade Executor<br/>[trade_executor.py]"]
  node_alpaca["Alpaca Manager<br/>[alpaca_manager.py]"]
  node_performance["Performance Analysis"]
end

subgraph group_adaptive["Adaptive Rotation"]
  node_adaptive_engine["Rotation Orchestrator"]
  node_adaptive_config["Rotation Configuration<br/>[config_loader.py]"]
  node_preprocess["Rotation Preprocessor"]
  node_regime["Market Regime<br/>[market_regime.py]"]
  node_strength["Group Strength<br/>[group_strength.py]"]
  node_ranking["Intra-Group Ranking"]
  node_exceptions["Exception Detection"]
  node_risk["Rotation Risk Manager<br/>[risk_manager.py]"]
  node_portfolio["Portfolio Builder"]
  node_stats["Robust Statistics<br/>[robust_stats.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_operator -.->|"uses UI"| node_dashboard
node_cli -->|"loads config"| node_settings
node_cli -->|"routes dashboard"| node_dashboard
node_cli -->|"routes backtest"| node_backtest
node_cli -->|"routes trading"| node_executor
node_dashboard -->|"runs backtest"| node_backtest
node_dashboard -->|"executes strategy"| node_executor
node_providers -->|"supplies market data"| node_fetcher
node_fetcher -->|"caches data"| node_store
node_fetcher -->|"uses credentials"| node_settings
node_store -->|"uses trading days"| node_calendar
node_dashboard -->|"processes data"| node_processor
node_dashboard -->|"reads data"| node_store
node_ml -->|"fetches inputs"| node_fetcher
node_ml -->|"implements strategy"| node_base
node_buckets -->|"fetches inputs"| node_fetcher
node_ml -.->|"provides selection signals"| node_backtest
node_fundamental -.->|"supports portfolio research"| node_backtest
node_executor -->|"submits orders"| node_alpaca
node_executor -->|"accepts strategies"| node_base
node_performance -->|"reads account state"| node_alpaca
node_performance -->|"gets benchmark data"| node_fetcher
node_adaptive_engine -->|"loads configuration"| node_adaptive_config
node_adaptive_engine -->|"requests daily data"| node_preprocess
node_adaptive_engine -->|"detects regime"| node_regime
node_adaptive_engine -->|"scores groups"| node_strength
node_adaptive_engine -->|"ranks assets"| node_ranking
node_adaptive_engine -->|"detects exceptions"| node_exceptions
node_adaptive_engine -->|"checks risk"| node_risk
node_adaptive_engine -->|"builds weights"| node_portfolio
node_strength -->|"uses robust metrics"| node_stats
node_ranking -->|"uses robust metrics"| node_stats
node_regime -->|"uses robust metrics"| node_stats
node_portfolio -->|"uses regime"| node_regime
node_portfolio -->|"uses group scores"| node_strength
node_portfolio -->|"uses rankings"| node_ranking
node_portfolio -->|"applies exceptions"| node_exceptions

click node_cli "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/main.py"
click node_dashboard "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/web/app.py"
click node_settings "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/config/settings.py"
click node_fetcher "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_fetcher.py"
click node_processor "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_processor.py"
click node_store "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_store.py"
click node_calendar "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/trading_calendar.py"
click node_ml "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/ml_strategy.py"
click node_buckets "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/ml_bucket_selection.py"
click node_fundamental "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/fundamental_portfolio_drl.py"
click node_base "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/base_strategy.py"
click node_backtest "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/backtest/backtest_engine.py"
click node_executor "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/trade_executor.py"
click node_alpaca "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/alpaca_manager.py"
click node_performance "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/performance_analyzer.py"
click node_adaptive_engine "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py"
click node_adaptive_config "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/config_loader.py"
click node_preprocess "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/data_preprocessor.py"
click node_regime "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/market_regime.py"
click node_strength "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/group_strength.py"
click node_ranking "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/intra_group_ranking.py"
click node_exceptions "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/exception_framework.py"
click node_risk "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/risk_manager.py"
click node_portfolio "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py"
click node_stats "https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/utils/robust_stats.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_cli,node_dashboard,node_settings toneBlue
class node_providers,node_fetcher,node_processor,node_store,node_calendar toneAmber
class node_ml,node_buckets,node_fundamental,node_base toneMint
class node_backtest,node_executor,node_alpaca,node_performance toneRose
class node_adaptive_engine,node_adaptive_config,node_preprocess,node_regime,node_strength,node_ranking,node_exceptions,node_risk,node_portfolio,node_stats,node_operator toneIndigo
```

## Components

### Entry And Interface

- [CLI Router](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/main.py): `FinRL-Trading/src/main.py`
- [Streamlit Dashboard](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/web/app.py): `FinRL-Trading/src/web/app.py`
- [Application Settings](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/config/settings.py): `FinRL-Trading/src/config/settings.py`

### Market Data

- **Market Data Providers**
- [Data Fetcher](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_fetcher.py): `FinRL-Trading/src/data/data_fetcher.py`
- [Feature Processing](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_processor.py): `FinRL-Trading/src/data/data_processor.py`
- [SQLite Data Store](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/data_store.py): `FinRL-Trading/src/data/data_store.py`
- [Trading Calendar](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/data/trading_calendar.py): `FinRL-Trading/src/data/trading_calendar.py`

### Strategy And Portfolio

- [ML Stock Selection](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/ml_strategy.py): `FinRL-Trading/src/strategies/ml_strategy.py`
- [Bucket Selection](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/ml_bucket_selection.py): `FinRL-Trading/src/strategies/ml_bucket_selection.py`
- [Fundamental DRL](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/fundamental_portfolio_drl.py): `FinRL-Trading/src/strategies/fundamental_portfolio_drl.py`
- [Strategy Contract](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/base_strategy.py): `FinRL-Trading/src/strategies/base_strategy.py`

### Trading And Analysis

- [Backtest Engine](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/backtest/backtest_engine.py): `FinRL-Trading/src/backtest/backtest_engine.py`
- [Trade Executor](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/trade_executor.py): `FinRL-Trading/src/trading/trade_executor.py`
- [Alpaca Manager](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/alpaca_manager.py): `FinRL-Trading/src/trading/alpaca_manager.py`
- [Performance Analysis](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/trading/performance_analyzer.py): `FinRL-Trading/src/trading/performance_analyzer.py`

### Adaptive Rotation

- [Rotation Orchestrator](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py): `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`
- [Rotation Configuration](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/config_loader.py): `FinRL-Trading/src/strategies/adaptive_rotation/config_loader.py`
- [Rotation Preprocessor](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/data_preprocessor.py): `FinRL-Trading/src/strategies/adaptive_rotation/data_preprocessor.py`
- [Market Regime](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/market_regime.py): `FinRL-Trading/src/strategies/adaptive_rotation/market_regime.py`
- [Group Strength](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/group_strength.py): `FinRL-Trading/src/strategies/adaptive_rotation/group_strength.py`
- [Intra-Group Ranking](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/intra_group_ranking.py): `FinRL-Trading/src/strategies/adaptive_rotation/intra_group_ranking.py`
- [Exception Detection](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/exception_framework.py): `FinRL-Trading/src/strategies/adaptive_rotation/exception_framework.py`
- [Rotation Risk Manager](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/risk_manager.py): `FinRL-Trading/src/strategies/adaptive_rotation/risk_manager.py`
- [Portfolio Builder](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py): `FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py`
- [Robust Statistics](https://github.com/codewithjaswanth/jev-alpaca-trader/blob/main/FinRL-Trading/src/strategies/adaptive_rotation/utils/robust_stats.py): `FinRL-Trading/src/strategies/adaptive_rotation/utils/robust_stats.py`

### Other components

- **Operator**

## Connections

- Operator → CLI Router: runs commands (evidence: `FinRL-Trading/src/main.py`)
- Operator → Streamlit Dashboard: uses UI (evidence: `FinRL-Trading/src/web/app.py`)
- CLI Router → Application Settings: loads config (evidence: `FinRL-Trading/src/main.py`)
- CLI Router → Streamlit Dashboard: routes dashboard (evidence: `FinRL-Trading/src/main.py`)
- CLI Router → Backtest Engine: routes backtest (evidence: `FinRL-Trading/src/main.py`)
- CLI Router → Trade Executor: routes trading (evidence: `FinRL-Trading/src/main.py`)
- Streamlit Dashboard → Backtest Engine: runs backtest (evidence: `FinRL-Trading/src/web/app.py`)
- Streamlit Dashboard → Trade Executor: executes strategy (evidence: `FinRL-Trading/src/web/app.py`)
- Market Data Providers → Data Fetcher: supplies market data (evidence: `README.md`)
- Data Fetcher → SQLite Data Store: caches data (evidence: `FinRL-Trading/src/data/data_fetcher.py`)
- Data Fetcher → Application Settings: uses credentials (evidence: `FinRL-Trading/src/data/data_fetcher.py`)
- SQLite Data Store → Trading Calendar: uses trading days (evidence: `FinRL-Trading/src/data/data_store.py`)
- Streamlit Dashboard → Feature Processing: processes data (evidence: `FinRL-Trading/src/web/app.py`)
- Streamlit Dashboard → SQLite Data Store: reads data (evidence: `FinRL-Trading/src/web/app.py`)
- ML Stock Selection → Data Fetcher: fetches inputs (evidence: `FinRL-Trading/src/strategies/ml_strategy.py`)
- ML Stock Selection → Strategy Contract: implements strategy (evidence: `FinRL-Trading/src/strategies/ml_strategy.py`)
- Bucket Selection → Data Fetcher: fetches inputs (evidence: `FinRL-Trading/src/strategies/ml_bucket_selection.py`)
- ML Stock Selection → Backtest Engine: provides selection signals (evidence: `README.md`)
- Fundamental DRL → Backtest Engine: supports portfolio research (evidence: `README.md`)
- Trade Executor → Alpaca Manager: submits orders (evidence: `FinRL-Trading/src/trading/trade_executor.py`)
- Trade Executor → Strategy Contract: accepts strategies (evidence: `FinRL-Trading/src/trading/trade_executor.py`)
- Performance Analysis → Alpaca Manager: reads account state (evidence: `FinRL-Trading/src/trading/performance_analyzer.py`)
- Performance Analysis → Data Fetcher: gets benchmark data (evidence: `FinRL-Trading/src/trading/performance_analyzer.py`)
- Rotation Orchestrator → Rotation Configuration: loads configuration (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Rotation Preprocessor: requests daily data (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Market Regime: detects regime (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Group Strength: scores groups (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Intra-Group Ranking: ranks assets (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Exception Detection: detects exceptions (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Rotation Risk Manager: checks risk (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Rotation Orchestrator → Portfolio Builder: builds weights (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/adaptive_rotation_engine.py`)
- Group Strength → Robust Statistics: uses robust metrics (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/group_strength.py`)
- Intra-Group Ranking → Robust Statistics: uses robust metrics (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/intra_group_ranking.py`)
- Market Regime → Robust Statistics: uses robust metrics (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/market_regime.py`)
- Portfolio Builder → Market Regime: uses regime (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py`)
- Portfolio Builder → Group Strength: uses group scores (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py`)
- Portfolio Builder → Intra-Group Ranking: uses rankings (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py`)
- Portfolio Builder → Exception Detection: applies exceptions (evidence: `FinRL-Trading/src/strategies/adaptive_rotation/portfolio_builder.py`)