# akash-kumar5/cryptomarket_regime_classifier architecture

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

- Interactive diagram: https://gitdiagram.com/akash-kumar5/cryptomarket_regime_classifier
- Repository: https://github.com/akash-kumar5/cryptomarket_regime_classifier

## Overview

1. **Repository purpose**
   - This is a crypto market regime intelligence pipeline, not a general trading bot.
   - Its core job is to turn Binance OHLCV data into regime labels and next-regime predictions for downstream strategy selection, sizing, and risk control.

2. **End-to-end architecture**
   - The data path is: Binance OHLCV input → feature engineering → PCA-style reduction for regime discovery → HMM for latent regime labeling → LSTM for sequence prediction → exported models/scalers for live use.
   - The README describes a two-stage ML design: unsupervised regime discovery first, then supervised temporal prediction.

3. **Data acquisition boundary**
   - `src/data_fetcher.py` and `src/fetch_binance_klines.py` are the ingestion layer.
   - They likely encapsulate Binance API access and multi-timeframe OHLCV retrieval, with the repository focused on 5m data plus 15m context.
   - `dashboard/pages/1_Fetch_data.py` exposes this step in the UI, suggesting manual or guided data refresh.

4. **Data cleaning and normalization**
   - `src/data_cleaner.py` is the preprocessing boundary between raw market data and model-ready inputs.
   - This layer is important because all downstream modeling depends on time alignment, missing-data handling, and feature consistency across timeframes.

5. **Feature engineering subsystem**
   - `src/compute_features.py` and `dashboard/pages/2_Compute_Features.py` are the feature generation stage.
   - The README says features cover momentum, trend, and volatility, and they are built from multi-timeframe OHLCV.
   - `features.txt` likely records the selected feature set used for training/inference parity.

6. **Regime discovery subsystem**
   - `src/regime_label.py` and `src/hmm_tuner.py` implement the HMM-based latent regime discovery.
   - The pipeline uses PCA-reduced features before HMM fitting and selects a 6-state model using lowest BIC, per the README.
   - The saved `.joblib` HMM files in `models/` are the persisted regime discovery artifacts.

7. **Supervised prediction subsystem**
   - `src/lstm_model.py` and `src/lstm_tuner.py` handle the LSTM that learns temporal patterns over HMM-derived labels.
   - The LSTM is the predictive layer that outputs the current regime and likely future regime probabilities.
   - `models/lstm_regime_model.keras`, `models/scaler.joblib`, and `models/lstm_model_metadata.json` are the deployable outputs of this stage.

8. **Live inference boundary**
   - `src/live_inference.py` and `dashboard/pages/7_Live_Implementation.py` represent the runtime path for using trained artifacts on fresh data.
   - This is the integration layer that consumes the exported model/scaler assets from `models/` and produces live regime classification results.

9. **Dashboard as orchestration and observability**
   - `dashboard/app.py` plus the numbered pages create a Streamlit-based workflow UI.
   - The page sequence mirrors the pipeline: fetch data, compute features, classify regimes, train models, tune HMM, tune LSTM, and validate live usage.
   - `plot_regime.py` likely supports visualization of regime transitions and model outputs.

10. **Training artifacts and experiment tracking**
   - `tuner_logs/` stores Keras Tuner/HMM tuning outputs, including trial configs, checkpoints, and oracle metadata.
   - This directory is a clear separation between reproducible experiments and the deployed artifacts in `models/`.

11. **Operational model of the repo**
   - The repo is organized around a batch research workflow with persistent artifacts, not a single always-on service.
   - The key state transitions are: raw Binance data in, engineered features out, trained regime models saved, then reused by live inference and dashboard pages.

12. **Architecture diagram hint**
   - A good diagram should show three layers: data ingestion, model pipeline, and consumption/UI.
   - The important storage boundaries are `models/` for deployable artifacts and `tuner_logs/` for experimentation history.

Main entry points: [`dashboard/app.py`](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/app.py) (Dashboard), [`src/compute_features.py`](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/compute_features.py) (Feature Engine), [`src/regime_label.py`](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/regime_label.py) (Regime Labeling), [`src/lstm_tuner.py`](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/lstm_tuner.py) (LSTM Tuner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion"]
  node_binance_fetcher["Binance Fetch<br/>ingestion<br/>[data_fetcher.py]"]
  node_kline_loader["Kline Loader<br/>ingestion"]
  node_data_cleaner["Cleaner<br/>preprocess<br/>[data_cleaner.py]"]
end

subgraph group_modeling["Modeling"]
  node_feature_engineering["Feature Engine<br/>features"]
  node_features_spec["Feature Set<br/>artifact spec<br/>[features.txt]"]
  node_regime_label["Regime Labeling<br/>hmm pipeline<br/>[regime_label.py]"]
  node_hmm_tuner["HMM Tuner<br/>model selection<br/>[hmm_tuner.py]"]
  node_hmm_models[("HMM Artifacts<br/>persisted model")]
  node_lstm_model["LSTM Model<br/>sequence predictor<br/>[lstm_model.py]"]
  node_lstm_tuner["LSTM Tuner<br/>model selection<br/>[lstm_tuner.py]"]
  node_lstm_artifacts[("LSTM Artifacts<br/>deployable model")]
  node_tuner_logs[("Tuning Logs<br/>experiment store<br/>[oracle.json]")]
end

subgraph group_serving["Serving & UI"]
  node_dashboard_app["Dashboard<br/>streamlit app<br/>[app.py]"]
  node_fetch_page["Fetch Data<br/>ui page<br/>[1_Fetch_data.py]"]
  node_features_page["Compute Features<br/>ui page"]
  node_regime_page["Regime Classifier<br/>ui page"]
  node_train_page["Model Training<br/>ui page"]
  node_hmm_page["HMM Tuning<br/>ui page<br/>[5_HMM_Tuning.py]"]
  node_lstm_page["LSTM Tuning<br/>ui page<br/>[6_LSTM_Tuning.py]"]
  node_live_page["Live Use<br/>ui page"]
  node_plot_regime["Regime Plot<br/>viz helper<br/>[plot_regime.py]"]
  node_live_inference["Live Inference<br/>runtime<br/>[live_inference.py]"]
end

node_dashboard_app -->|"orchestrates"| node_fetch_page
node_dashboard_app -->|"orchestrates"| node_features_page
node_dashboard_app -->|"orchestrates"| node_regime_page
node_dashboard_app -->|"orchestrates"| node_train_page
node_dashboard_app -->|"orchestrates"| node_hmm_page
node_dashboard_app -->|"orchestrates"| node_lstm_page
node_dashboard_app -->|"orchestrates"| node_live_page
node_binance_fetcher -->|"retrieves"| node_kline_loader
node_kline_loader -->|"raw data"| node_data_cleaner
node_data_cleaner -->|"cleaned data"| node_feature_engineering
node_feature_engineering -->|"defines"| node_features_spec
node_feature_engineering -->|"features"| node_regime_label
node_regime_label -->|"fits"| node_hmm_tuner
node_hmm_tuner -->|"persists"| node_hmm_models
node_hmm_models -->|"labels"| node_lstm_model
node_lstm_model -->|"tunes"| node_lstm_tuner
node_lstm_tuner -->|"exports"| node_lstm_artifacts
node_tuner_logs -->|"records"| node_lstm_tuner
node_live_inference -->|"loads"| node_lstm_artifacts
node_live_inference -->|"loads"| node_hmm_models
node_fetch_page -->|"invokes"| node_binance_fetcher
node_features_page -->|"invokes"| node_feature_engineering
node_regime_page -->|"invokes"| node_regime_label
node_train_page -->|"invokes"| node_lstm_model
node_hmm_page -->|"invokes"| node_hmm_tuner
node_lstm_page -->|"invokes"| node_lstm_tuner
node_live_page -->|"invokes"| node_live_inference
node_plot_regime -->|"visualizes"| node_regime_label

click node_dashboard_app "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/app.py"
click node_fetch_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/1_Fetch_data.py"
click node_features_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/2_Compute_Features.py"
click node_regime_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/3_Regime_Classifier.py"
click node_train_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/4_Model_Training.py"
click node_hmm_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/5_HMM_Tuning.py"
click node_lstm_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/6_LSTM_Tuning.py"
click node_live_page "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/7_Live_Implementation.py"
click node_plot_regime "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/plot_regime.py"
click node_binance_fetcher "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/data_fetcher.py"
click node_kline_loader "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/fetch_binance_klines.py"
click node_data_cleaner "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/data_cleaner.py"
click node_feature_engineering "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/compute_features.py"
click node_features_spec "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/features.txt"
click node_regime_label "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/regime_label.py"
click node_hmm_tuner "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/hmm_tuner.py"
click node_hmm_models "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/models/hmm_BTCUSDT_combined_klines_20221106_20251105_features_states6.joblib"
click node_lstm_model "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/lstm_model.py"
click node_lstm_tuner "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/lstm_tuner.py"
click node_lstm_artifacts "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/models/lstm_regime_model.keras"
click node_live_inference "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/live_inference.py"
click node_tuner_logs "https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/tuner_logs/lstm_tuning_BTCUSDT_combined_klines_20221107_20251106_states6_labeled/oracle.json"

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_binance_fetcher,node_kline_loader,node_data_cleaner toneBlue
class node_feature_engineering,node_features_spec,node_regime_label,node_hmm_tuner,node_hmm_models,node_lstm_model,node_lstm_tuner,node_lstm_artifacts,node_tuner_logs toneAmber
class node_dashboard_app,node_fetch_page,node_features_page,node_regime_page,node_train_page,node_hmm_page,node_lstm_page,node_live_page,node_plot_regime,node_live_inference toneMint
```

## Components

### Ingestion

Binance data acquisition and raw-to-clean market data preparation.

- [Binance Fetch](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/data_fetcher.py): ingestion · Binance OHLCV access and kline retrieval boundary. · `src/data_fetcher.py`
- [Kline Loader](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/fetch_binance_klines.py): ingestion · Kline download and multi-timeframe retrieval implementation. · `src/fetch_binance_klines.py`
- [Cleaner](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/data_cleaner.py): preprocess · Alignment, missing-data handling, and model-ready normalization boundary. · `src/data_cleaner.py`

### Modeling

Feature engineering, regime discovery, sequence prediction, and training artifacts.

- [Feature Engine](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/compute_features.py): features · Momentum, trend, and volatility feature construction across timeframes. · `src/compute_features.py`
- [Feature Set](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/features.txt): artifact spec · Recorded feature list used to keep training and inference consistent. · `features.txt`
- [Regime Labeling](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/regime_label.py): hmm pipeline · PCA-style reduction and HMM-based latent regime discovery. · `src/regime_label.py`
- [HMM Tuner](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/hmm_tuner.py): model selection · Chooses regime model configuration, including state count and BIC-based fit. · `src/hmm_tuner.py`
- [HMM Artifacts](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/models/hmm_BTCUSDT_combined_klines_20221106_20251105_features_states6.joblib): persisted model · Saved regime discovery models used for downstream labeling and inference. · `models/hmm_BTCUSDT_combined_klines_20221106_20251105_features_states6.joblib`
- [LSTM Model](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/lstm_model.py): sequence predictor · Trains the supervised temporal model over regime labels. · `src/lstm_model.py`
- [LSTM Tuner](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/lstm_tuner.py): model selection · Tunes sequence model hyperparameters and training setup. · `src/lstm_tuner.py`
- [LSTM Artifacts](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/models/lstm_regime_model.keras): deployable model · Exported LSTM model, scaler, and metadata for live use. · `models/lstm_regime_model.keras`
- [Tuning Logs](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/tuner_logs/lstm_tuning_BTCUSDT_combined_klines_20221107_20251106_states6_labeled/oracle.json): experiment store · Keras Tuner and HMM trial histories, checkpoints, and oracle state. · `tuner_logs/lstm_tuning_BTCUSDT_combined_klines_20221107_20251106_states6_labeled/oracle.json`

### Serving & UI

Dashboard orchestration, live inference, and visualization.

- [Dashboard](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/app.py): streamlit app · Entry point for the numbered workflow pages and model operations. · `dashboard/app.py`
- [Fetch Data](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/1_Fetch_data.py): ui page · Dashboard step for refreshing Binance OHLCV data. · `dashboard/pages/1_Fetch_data.py`
- [Compute Features](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/2_Compute_Features.py): ui page · Dashboard step for generating model features from market data. · `dashboard/pages/2_Compute_Features.py`
- [Regime Classifier](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/3_Regime_Classifier.py): ui page · Dashboard step for labeling regimes and inspecting classification output. · `dashboard/pages/3_Regime_Classifier.py`
- [Model Training](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/4_Model_Training.py): ui page · Dashboard step for running model training workflows. · `dashboard/pages/4_Model_Training.py`
- [HMM Tuning](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/5_HMM_Tuning.py): ui page · Dashboard step for tuning the hidden Markov model. · `dashboard/pages/5_HMM_Tuning.py`
- [LSTM Tuning](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/6_LSTM_Tuning.py): ui page · Dashboard step for tuning the sequence model. · `dashboard/pages/6_LSTM_Tuning.py`
- [Live Use](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/dashboard/pages/7_Live_Implementation.py): ui page · Dashboard step for validating live inference on fresh data. · `dashboard/pages/7_Live_Implementation.py`
- [Regime Plot](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/plot_regime.py): viz helper · Visualization helper for regime transitions and outputs. · `plot_regime.py`
- [Live Inference](https://github.com/akash-kumar5/cryptomarket_regime_classifier/blob/main/src/live_inference.py): runtime · Consumes fresh data and persisted artifacts to produce regime predictions. · `src/live_inference.py`

## Connections

- Dashboard → Fetch Data: orchestrates · The UI exposes the data refresh workflow.
- Dashboard → Compute Features: orchestrates · The UI exposes feature generation.
- Dashboard → Regime Classifier: orchestrates · The UI exposes regime labeling.
- Dashboard → Model Training: orchestrates · The UI exposes model training.
- Dashboard → HMM Tuning: orchestrates · The UI exposes HMM tuning.
- Dashboard → LSTM Tuning: orchestrates · The UI exposes LSTM tuning.
- Dashboard → Live Use: orchestrates · The UI exposes live validation.
- Binance Fetch → Kline Loader: retrieves · Raw ingestion is backed by kline retrieval logic.
- Kline Loader → Cleaner: raw data · Downloaded OHLCV is prepared for modeling.
- Cleaner → Feature Engine: cleaned data · Cleaned market data feeds feature generation.
- Feature Engine → Feature Set: defines · The selected feature set documents training/inference parity.
- Feature Engine → Regime Labeling: features · Engineered features are reduced and labeled into regimes.
- Regime Labeling → HMM Tuner: fits · HMM tuning searches regime configurations.
- HMM Tuner → HMM Artifacts: persists · Best regime model is saved for reuse.
- HMM Artifacts → LSTM Model: labels · HMM regime outputs become supervised targets or inputs.
- LSTM Model → LSTM Tuner: tunes · Sequence model hyperparameters are optimized.
- LSTM Tuner → LSTM Artifacts: exports · Final LSTM, scaler, and metadata are stored for deployment.
- Tuning Logs → LSTM Tuner: records · Trial history and checkpoints support repeated tuning runs.
- Live Inference → LSTM Artifacts: loads · Runtime inference consumes the exported LSTM assets.
- Live Inference → HMM Artifacts: loads · Runtime inference also needs the persisted regime model.
- Fetch Data → Binance Fetch: invokes · The dashboard can trigger fresh data acquisition.
- Compute Features → Feature Engine: invokes · The dashboard can trigger feature generation.
- Regime Classifier → Regime Labeling: invokes · The dashboard can run regime classification.
- Model Training → LSTM Model: invokes · The dashboard can run model training.
- HMM Tuning → HMM Tuner: invokes · The dashboard can run HMM tuning.
- LSTM Tuning → LSTM Tuner: invokes · The dashboard can run LSTM tuning.
- Live Use → Live Inference: invokes · The dashboard can run live implementation checks.
- Regime Plot → Regime Labeling: visualizes · Regime plots present labeling and transitions.
