# suryatejareddy195/crypto-screener architecture

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

- Interactive diagram: https://gitdiagram.com/suryatejareddy195/crypto-screener
- Repository: https://github.com/suryatejareddy195/crypto-screener

## Overview

Crypto Predictor is a Streamlit dashboard backed by a calibrated next-candle direction model and a research pipeline. The principal workflow refreshes market and funding data, builds causal features, trains and evaluates models, then serves gated UP/DOWN probabilities and diagnostics in the dashboard. The README also describes live derivatives diagnostics and a rule-based baseline. Edges reflect explicit README documentation or the shown SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`train_model.py`](https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py) (Walk-forward trainer), [`app.py`](https://github.com/suryatejareddy195/crypto-screener/blob/main/app.py) (Streamlit dashboard), [`retrain.py`](https://github.com/suryatejareddy195/crypto-screener/blob/main/retrain.py) (Refresh and retrain), [`build_dataset.py`](https://github.com/suryatejareddy195/crypto-screener/blob/main/build_dataset.py) (OHLCV ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_baseline["Rule-based baseline<br/>[predict.py]"]
  node_live_signal["Live market signal<br/>[predict.py]"]
end

subgraph group_data["Market data"]
  node_ohlcv_ingest["OHLCV ingestion<br/>[build_dataset.py]"]
  node_raw_cache[("Raw candle cache<br/>[build_dataset.py]")]
  node_derivatives["Funding and live alt-data<br/>[altdata.py]"]
  node_fund_cache[("Funding cache<br/>[altdata.py]")]
end

subgraph group_model["Model pipeline"]
  node_features["Causal features and labels<br/>[features.py]"]
  node_feature_cache[("Feature cache<br/>[features.py]")]
  node_trainer["Walk-forward trainer<br/>[train_model.py]"]
  node_calibration["Probability calibration<br/>[mlutils.py]"]
  node_evaluation["Skill and trading evaluation<br/>[train_model.py]"]
  node_inference["Calibrated gated inference<br/>[train_model.py]"]
end

subgraph group_ops["Model operations"]
  node_artifacts[("Trained model artifacts")]
  node_manifest["Latest-model registry<br/>[manifest.json]"]
  node_retraining["Refresh and retrain<br/>[retrain.py]"]
end

node_user(("Analyst"))
node_binance{{"Binance APIs"}}
node_coingecko{{"CoinGecko API"}}

node_user -->|"views"| node_dashboard
node_dashboard -->|"requests probabilities"| node_inference
node_dashboard -->|"shows diagnostics"| node_derivatives
node_dashboard -->|"uses baseline"| node_baseline
node_dashboard -->|"shows diagnostics"| node_trainer
node_user -->|"runs baseline"| node_baseline
node_ohlcv_ingest -->|"downloads candles"| node_binance
node_ohlcv_ingest -->|"falls back to"| node_coingecko
node_ohlcv_ingest -->|"caches candles"| node_raw_cache
node_derivatives -->|"fetches derivatives"| node_binance
node_derivatives -->|"caches funding"| node_fund_cache
node_features -->|"reads candles"| node_raw_cache
node_features -->|"joins funding"| node_fund_cache
node_features -->|"builds feature cache"| node_feature_cache
node_trainer -->|"trains from features"| node_feature_cache
node_trainer -->|"uses calibration"| node_calibration
node_trainer -->|"evaluates model"| node_evaluation
node_trainer -->|"saves models"| node_artifacts
node_trainer -->|"updates registry"| node_manifest
node_inference -->|"loads model"| node_artifacts
node_inference -->|"resolves latest"| node_manifest
node_retraining -->|"refreshes candles"| node_ohlcv_ingest
node_retraining -->|"refreshes funding"| node_derivatives
node_retraining -->|"rebuilds features"| node_features
node_retraining -->|"retrains models"| node_trainer

click node_dashboard "https://github.com/suryatejareddy195/crypto-screener/blob/main/app.py"
click node_baseline "https://github.com/suryatejareddy195/crypto-screener/blob/main/predict.py"
click node_live_signal "https://github.com/suryatejareddy195/crypto-screener/blob/main/predict.py"
click node_ohlcv_ingest "https://github.com/suryatejareddy195/crypto-screener/blob/main/build_dataset.py"
click node_raw_cache "https://github.com/suryatejareddy195/crypto-screener/blob/main/build_dataset.py"
click node_derivatives "https://github.com/suryatejareddy195/crypto-screener/blob/main/altdata.py"
click node_fund_cache "https://github.com/suryatejareddy195/crypto-screener/blob/main/altdata.py"
click node_features "https://github.com/suryatejareddy195/crypto-screener/blob/main/features.py"
click node_feature_cache "https://github.com/suryatejareddy195/crypto-screener/blob/main/features.py"
click node_trainer "https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py"
click node_calibration "https://github.com/suryatejareddy195/crypto-screener/blob/main/mlutils.py"
click node_evaluation "https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py"
click node_artifacts "https://github.com/suryatejareddy195/crypto-screener/tree/main/models"
click node_manifest "https://github.com/suryatejareddy195/crypto-screener/blob/main/models/manifest.json"
click node_inference "https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py"
click node_retraining "https://github.com/suryatejareddy195/crypto-screener/blob/main/retrain.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_dashboard,node_baseline,node_live_signal toneBlue
class node_ohlcv_ingest,node_raw_cache,node_derivatives,node_fund_cache toneAmber
class node_features,node_feature_cache,node_trainer,node_calibration,node_evaluation,node_inference,node_binance,node_coingecko toneMint
class node_artifacts,node_manifest,node_retraining toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Streamlit dashboard](https://github.com/suryatejareddy195/crypto-screener/blob/main/app.py): `app.py`
- [Rule-based baseline](https://github.com/suryatejareddy195/crypto-screener/blob/main/predict.py): `predict.py`
- [Live market signal](https://github.com/suryatejareddy195/crypto-screener/blob/main/predict.py): `predict.py`

### Market data

- [OHLCV ingestion](https://github.com/suryatejareddy195/crypto-screener/blob/main/build_dataset.py): `build_dataset.py`
- [Raw candle cache](https://github.com/suryatejareddy195/crypto-screener/blob/main/build_dataset.py): `build_dataset.py`
- [Funding and live alt-data](https://github.com/suryatejareddy195/crypto-screener/blob/main/altdata.py): `altdata.py`
- [Funding cache](https://github.com/suryatejareddy195/crypto-screener/blob/main/altdata.py): `altdata.py`

### Model pipeline

- [Causal features and labels](https://github.com/suryatejareddy195/crypto-screener/blob/main/features.py): `features.py`
- [Feature cache](https://github.com/suryatejareddy195/crypto-screener/blob/main/features.py): `features.py`
- [Walk-forward trainer](https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py): `train_model.py`
- [Probability calibration](https://github.com/suryatejareddy195/crypto-screener/blob/main/mlutils.py): `mlutils.py`
- [Skill and trading evaluation](https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py): `train_model.py`
- [Calibrated gated inference](https://github.com/suryatejareddy195/crypto-screener/blob/main/train_model.py): `train_model.py`

### Model operations

- [Trained model artifacts](https://github.com/suryatejareddy195/crypto-screener/tree/main/models): `models`
- [Latest-model registry](https://github.com/suryatejareddy195/crypto-screener/blob/main/models/manifest.json): `models/manifest.json`
- [Refresh and retrain](https://github.com/suryatejareddy195/crypto-screener/blob/main/retrain.py): `retrain.py`

### Other components

- **Analyst**
- **Binance APIs**
- **CoinGecko API**

## Connections

- Analyst → Streamlit dashboard: views (evidence: `README.md`)
- Streamlit dashboard → Calibrated gated inference: requests probabilities (evidence: `app.py`)
- Streamlit dashboard → Funding and live alt-data: shows diagnostics (evidence: `app.py`)
- Streamlit dashboard → Rule-based baseline: uses baseline (evidence: `app.py`)
- Streamlit dashboard → Walk-forward trainer: shows diagnostics (evidence: `app.py`)
- Analyst → Rule-based baseline: runs baseline (evidence: `README.md`)
- OHLCV ingestion → Binance APIs: downloads candles (evidence: `build_dataset.py`)
- OHLCV ingestion → CoinGecko API: falls back to (evidence: `build_dataset.py`)
- OHLCV ingestion → Raw candle cache: caches candles (evidence: `build_dataset.py`)
- Funding and live alt-data → Binance APIs: fetches derivatives (evidence: `altdata.py`)
- Funding and live alt-data → Funding cache: caches funding (evidence: `altdata.py`)
- Causal features and labels → Raw candle cache: reads candles (evidence: `README.md`)
- Causal features and labels → Funding cache: joins funding (evidence: `features.py`)
- Causal features and labels → Feature cache: builds feature cache (evidence: `README.md`)
- Walk-forward trainer → Feature cache: trains from features (evidence: `README.md`)
- Walk-forward trainer → Probability calibration: uses calibration (evidence: `train_model.py`)
- Walk-forward trainer → Skill and trading evaluation: evaluates model (evidence: `README.md`)
- Walk-forward trainer → Trained model artifacts: saves models (evidence: `README.md`)
- Walk-forward trainer → Latest-model registry: updates registry (evidence: `README.md`)
- Calibrated gated inference → Trained model artifacts: loads model (evidence: `train_model.py`)
- Calibrated gated inference → Latest-model registry: resolves latest (evidence: `train_model.py`)
- Refresh and retrain → OHLCV ingestion: refreshes candles (evidence: `retrain.py`)
- Refresh and retrain → Funding and live alt-data: refreshes funding (evidence: `retrain.py`)
- Refresh and retrain → Causal features and labels: rebuilds features (evidence: `retrain.py`)
- Refresh and retrain → Walk-forward trainer: retrains models (evidence: `retrain.py`)
