# muhammadmoaz/risk-regime-engine architecture

> Architecture diagram of the GitHub repository muhammadmoaz/risk-regime-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhammadmoaz/risk-regime-engine
- Repository: https://github.com/muhammadmoaz/risk-regime-engine

## Overview

This repository is a single-script BTC risk-regime analysis prototype. Its current workflow fetches BTC history from Yahoo Finance, derives returns and volatility features, classifies regimes, compares forward returns by regime, assigns risk signals, and prints the latest result; it also produces plots and backtests a signal strategy. The README describes future up/flat/down probabilities and a web page, but those capabilities are not evidenced in the sampled implementation. All implementation nodes therefore point to main.py; connections reflect the excerpt, not unsampled code.

Main entry points: [`main.py`](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py) (Signal Scoring), [`Plots`](https://github.com/muhammadmoaz/risk-regime-engine/tree/master/Plots) (Saved Plots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_analysis["Market Analysis"]
  node_analysis_entry["Analysis Run<br/>[main.py]"]
  node_price_history["BTC History<br/>[main.py]"]
  node_market_features["Return Features<br/>[main.py]"]
end

subgraph group_signals["Regime Signals"]
  node_volatility["Volatility Regimes<br/>[main.py]"]
  node_regime_classifier["Trend Regimes<br/>[main.py]"]
  node_signal_scoring["Signal Scoring<br/>[main.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_forward_returns["Forward Returns<br/>[main.py]"]
  node_regime_summary["Regime Statistics<br/>[main.py]"]
  node_backtest["Strategy Backtest<br/>[main.py]"]
  node_performance_stats["Performance Stats<br/>[main.py]"]
end

subgraph group_outputs["Outputs"]
  node_latest_result["Latest Signal<br/>[main.py]"]
  node_plots["Saved Plots"]
end

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

node_user -->|"runs"| node_analysis_entry
node_analysis_entry -->|"fetches history"| node_yahoo
node_analysis_entry -->|"loads BTC data"| node_price_history
node_price_history -->|"derives returns"| node_market_features
node_market_features -->|"measures volatility"| node_volatility
node_market_features -->|"classifies trend"| node_regime_classifier
node_regime_classifier -->|"computes horizons"| node_forward_returns
node_forward_returns -->|"groups by regime"| node_regime_summary
node_regime_summary -->|"scores regimes"| node_signal_scoring
node_signal_scoring -->|"maps latest signal"| node_latest_result
node_signal_scoring -->|"sets positions"| node_backtest
node_backtest -->|"computes metrics"| node_performance_stats
node_volatility -->|"saves charts"| node_plots
node_regime_classifier -->|"saves regime chart"| node_plots
node_signal_scoring -->|"saves signal chart"| node_plots
node_backtest -->|"saves equity chart"| node_plots

click node_analysis_entry "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_price_history "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_market_features "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_volatility "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_regime_classifier "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_forward_returns "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_regime_summary "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_signal_scoring "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_latest_result "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_backtest "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_performance_stats "https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py"
click node_plots "https://github.com/muhammadmoaz/risk-regime-engine/tree/master/Plots"

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_analysis_entry,node_price_history,node_market_features,node_user toneBlue
class node_volatility,node_regime_classifier,node_signal_scoring toneAmber
class node_forward_returns,node_regime_summary,node_backtest,node_performance_stats toneMint
class node_latest_result,node_plots toneRose
class node_yahoo toneIndigo
```

## Components

### Market Analysis

- [Analysis Run](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [BTC History](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Return Features](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`

### Regime Signals

- [Volatility Regimes](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Trend Regimes](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Signal Scoring](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`

### Evaluation

- [Forward Returns](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Regime Statistics](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Strategy Backtest](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Performance Stats](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`

### Outputs

- [Latest Signal](https://github.com/muhammadmoaz/risk-regime-engine/blob/master/main.py): `main.py`
- [Saved Plots](https://github.com/muhammadmoaz/risk-regime-engine/tree/master/Plots): `Plots`

### Other components

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

## Connections

- User → Analysis Run: runs (evidence: `main.py`)
- Analysis Run → Yahoo Finance: fetches history (evidence: `main.py`)
- Analysis Run → BTC History: loads BTC data (evidence: `main.py`)
- BTC History → Return Features: derives returns (evidence: `main.py`)
- Return Features → Volatility Regimes: measures volatility (evidence: `main.py`)
- Return Features → Trend Regimes: classifies trend (evidence: `main.py`)
- Trend Regimes → Forward Returns: computes horizons (evidence: `main.py`)
- Forward Returns → Regime Statistics: groups by regime (evidence: `main.py`)
- Regime Statistics → Signal Scoring: scores regimes (evidence: `main.py`)
- Signal Scoring → Latest Signal: maps latest signal (evidence: `main.py`)
- Signal Scoring → Strategy Backtest: sets positions (evidence: `main.py`)
- Strategy Backtest → Performance Stats: computes metrics (evidence: `main.py`)
- Volatility Regimes → Saved Plots: saves charts (evidence: `main.py`)
- Trend Regimes → Saved Plots: saves regime chart (evidence: `main.py`)
- Signal Scoring → Saved Plots: saves signal chart (evidence: `main.py`)
- Strategy Backtest → Saved Plots: saves equity chart (evidence: `main.py`)
