# ravindhu/algo-lab architecture

> Architecture diagram of the GitHub repository ravindhu/algo-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravindhu/algo-lab
- Repository: https://github.com/ravindhu/algo-lab

## Overview

AlgoLab is a MetaTrader 5 forex trading system with alert-only and order-execution paths. The principal workflow scans market history or live data, filters and validates signals, applies risk and safety guards, then alerts or executes through the broker adapter; results and operational state feed the dashboard. Separate workflows validate strategies, tune parameters, and discover/promote candidates under human approval. Edges use the excerpts, SOURCE INDEX references, or README statements; unsampled subsystem links are omitted where ownership is unclear.

Main entry points: [`src/algolab/live/pipeline.py`](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/pipeline.py) (Live cycle), [`src/algolab/cli.py`](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/cli.py) (CLI commands), [`src/algolab/ops/pipeline.py`](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/pipeline.py) (Alert-only cycle), [`src/algolab/backtest/validate.py`](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/backtest/validate.py) (Validation gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_signal["Signals and analysis"]
  node_scanner["Signal scanner<br/>[scanner.py]"]
  node_agent["Signal analyst<br/>[multi_agent.py]"]
  node_llm["Ollama client<br/>[ollama_client.py]"]
  node_budget["LLM budget<br/>[budget.py]"]
  node_alertpipeline["Alert-only cycle<br/>[pipeline.py]"]
end

subgraph group_trading["Live trading"]
  node_strategies["Framework strategies"]
  node_indicators["Shared indicators<br/>[hm.py]"]
  node_framework["Framework runner"]
  node_live["Live cycle<br/>[pipeline.py]"]
  node_broker["MT5 adapter<br/>[adapter.py]"]
end

subgraph group_assurance["Validation and research"]
  node_legacybacktest["Legacy backtest<br/>[engine.py]"]
  node_validation["Validation gate<br/>[validate.py]"]
  node_optimizer["Parameter tuning<br/>[autotune.py]"]
  node_ml["ML filter<br/>[model.py]"]
  node_discovery["Strategy discovery"]
  node_promotion["Candidate promotion"]
end

subgraph group_operations["Operations and state"]
  node_profile["Runtime profile<br/>[profile.py]"]
  node_risk["Loss limits<br/>[risk.py]"]
  node_alerts["Alerts<br/>[alerts.py]"]
  node_state[("Operational state<br/>[state.py]")]
  node_journal[("Trade journal<br/>[journal.py]")]
  node_memory[("Agent memory<br/>[store.py]")]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_dashboard["Dashboard<br/>[app.py]"]
end

node_operator(("Operator"))
node_external_user(("User"))
node_ollama_service["Ollama service"]
node_mt5["MetaTrader 5"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_profile
node_agent -->|"scans signals"| node_scanner
node_agent -->|"uses budget"| node_budget
node_budget -->|"wraps analyst"| node_llm
node_llm -->|"sends chat"| node_ollama_service
node_alertpipeline -->|"reviews signals"| node_agent
node_alertpipeline -->|"checks limits"| node_risk
node_alertpipeline -->|"sends alerts"| node_alerts
node_alertpipeline -->|"reads and writes"| node_state
node_live -->|"checks gate"| node_validation
node_live -->|"reads account"| node_broker
node_live -->|"runs cycle"| node_framework
node_broker -->|"connects directly"| node_mt5
node_framework -->|"asks strategies"| node_strategies
node_strategies -->|"uses indicators"| node_indicators
node_validation -->|"tests legacy rule"| node_legacybacktest
node_validation -->|"replays live path"| node_framework
node_validation -->|"records gate"| node_state
node_optimizer -->|"evaluates candidates"| node_legacybacktest
node_optimizer -->|"fits filter"| node_ml
node_discovery -.->|"produces candidates"| node_promotion
node_cli -->|"runs discovery"| node_discovery
node_cli -->|"promotes candidate"| node_promotion
node_cli -->|"runs tuning"| node_optimizer
node_dashboard -->|"reads status"| node_state
node_dashboard -->|"reads trades"| node_journal
node_dashboard -->|"reads calibration"| node_memory
node_external_user -->|"views monitor"| node_dashboard
node_live -->|"checks limits"| node_risk
node_live -->|"locks and records"| node_state
node_live -->|"reports breaches"| node_alerts

click node_cli "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/cli.py"
click node_profile "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/profile.py"
click node_scanner "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/framework/scanner.py"
click node_agent "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/agent/multi_agent.py"
click node_llm "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/llm/ollama_client.py"
click node_budget "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/llm/budget.py"
click node_legacybacktest "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/backtest/engine.py"
click node_validation "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/backtest/validate.py"
click node_strategies "https://github.com/ravindhu/algo-lab/tree/main/src/algolab/framework/strategies"
click node_indicators "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/framework/strategies/indicators/hm.py"
click node_framework "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/framework_runner.py"
click node_live "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/pipeline.py"
click node_broker "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/adapter.py"
click node_alertpipeline "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/pipeline.py"
click node_risk "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/risk.py"
click node_alerts "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/alerts.py"
click node_state "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/state.py"
click node_journal "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/journal.py"
click node_dashboard "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/dashboard/app.py"
click node_memory "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/memory/store.py"
click node_optimizer "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/optimize/autotune.py"
click node_ml "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ml/model.py"
click node_discovery "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/discovery_factory.py"
click node_promotion "https://github.com/ravindhu/algo-lab/blob/main/src/algolab/discovery_promote.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_scanner,node_agent,node_llm,node_budget,node_alertpipeline,node_external_user toneBlue
class node_strategies,node_indicators,node_framework,node_live,node_broker toneAmber
class node_legacybacktest,node_validation,node_optimizer,node_ml,node_discovery,node_promotion toneMint
class node_profile,node_risk,node_alerts,node_state,node_journal,node_memory toneRose
class node_cli,node_dashboard,node_operator,node_ollama_service,node_mt5 toneIndigo
```

## Components

### Signals and analysis

- [Signal scanner](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/framework/scanner.py): `src/algolab/framework/scanner.py`
- [Signal analyst](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/agent/multi_agent.py): `src/algolab/agent/multi_agent.py`
- [Ollama client](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/llm/ollama_client.py): `src/algolab/llm/ollama_client.py`
- [LLM budget](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/llm/budget.py): `src/algolab/llm/budget.py`
- [Alert-only cycle](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/pipeline.py): `src/algolab/ops/pipeline.py`

### Live trading

- [Framework strategies](https://github.com/ravindhu/algo-lab/tree/main/src/algolab/framework/strategies): `src/algolab/framework/strategies`
- [Shared indicators](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/framework/strategies/indicators/hm.py): `src/algolab/framework/strategies/indicators/hm.py`
- [Framework runner](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/framework_runner.py): `src/algolab/live/framework_runner.py`
- [Live cycle](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/pipeline.py): `src/algolab/live/pipeline.py`
- [MT5 adapter](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/live/adapter.py): `src/algolab/live/adapter.py`

### Validation and research

- [Legacy backtest](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/backtest/engine.py): `src/algolab/backtest/engine.py`
- [Validation gate](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/backtest/validate.py): `src/algolab/backtest/validate.py`
- [Parameter tuning](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/optimize/autotune.py): `src/algolab/optimize/autotune.py`
- [ML filter](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ml/model.py): `src/algolab/ml/model.py`
- [Strategy discovery](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/discovery_factory.py): `src/algolab/discovery_factory.py`
- [Candidate promotion](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/discovery_promote.py): `src/algolab/discovery_promote.py`

### Operations and state

- [Runtime profile](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/profile.py): `src/algolab/profile.py`
- [Loss limits](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/risk.py): `src/algolab/ops/risk.py`
- [Alerts](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/alerts.py): `src/algolab/ops/alerts.py`
- [Operational state](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/state.py): `src/algolab/ops/state.py`
- [Trade journal](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/ops/journal.py): `src/algolab/ops/journal.py`
- [Agent memory](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/memory/store.py): `src/algolab/memory/store.py`

### User interfaces

- [CLI commands](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/cli.py): `src/algolab/cli.py`
- [Dashboard](https://github.com/ravindhu/algo-lab/blob/main/src/algolab/dashboard/app.py): `src/algolab/dashboard/app.py`

### Other components

- **Operator**
- **User**
- **Ollama service**
- **MetaTrader 5**

## Connections

- Operator → CLI commands: runs commands
- CLI commands → Runtime profile: loads settings (evidence: `src/algolab/cli.py`)
- Signal analyst → Signal scanner: scans signals (evidence: `src/algolab/agent/multi_agent.py`)
- Signal analyst → LLM budget: uses budget (evidence: `src/algolab/agent/multi_agent.py`)
- LLM budget → Ollama client: wraps analyst (evidence: `src/algolab/agent/multi_agent.py`)
- Ollama client → Ollama service: sends chat (evidence: `src/algolab/llm/ollama_client.py`)
- Alert-only cycle → Signal analyst: reviews signals (evidence: `src/algolab/ops/pipeline.py`)
- Alert-only cycle → Loss limits: checks limits (evidence: `src/algolab/ops/pipeline.py`)
- Alert-only cycle → Alerts: sends alerts (evidence: `src/algolab/ops/pipeline.py`)
- Alert-only cycle → Operational state: reads and writes (evidence: `src/algolab/ops/pipeline.py`)
- Live cycle → Validation gate: checks gate (evidence: `src/algolab/live/pipeline.py`)
- Live cycle → MT5 adapter: reads account (evidence: `src/algolab/live/pipeline.py`)
- Live cycle → Framework runner: runs cycle (evidence: `src/algolab/live/pipeline.py`)
- MT5 adapter → MetaTrader 5: connects directly
- Framework runner → Framework strategies: asks strategies
- Framework strategies → Shared indicators: uses indicators (evidence: `src/algolab/framework/strategies/indicators/__init__.py`)
- Validation gate → Legacy backtest: tests legacy rule (evidence: `src/algolab/backtest/validate.py`)
- Validation gate → Framework runner: replays live path (evidence: `src/algolab/backtest/validate.py`)
- Validation gate → Operational state: records gate (evidence: `src/algolab/backtest/validate.py`)
- Parameter tuning → Legacy backtest: evaluates candidates (evidence: `src/algolab/optimize/autotune.py`)
- Parameter tuning → ML filter: fits filter (evidence: `src/algolab/optimize/autotune.py`)
- Strategy discovery → Candidate promotion: produces candidates (evidence: `src/algolab/discovery_promote.py`)
- CLI commands → Strategy discovery: runs discovery (evidence: `src/algolab/cli.py`)
- CLI commands → Candidate promotion: promotes candidate (evidence: `src/algolab/cli.py`)
- CLI commands → Parameter tuning: runs tuning (evidence: `src/algolab/cli.py`)
- Dashboard → Operational state: reads status (evidence: `src/algolab/dashboard/app.py`)
- Dashboard → Trade journal: reads trades (evidence: `src/algolab/dashboard/app.py`)
- Dashboard → Agent memory: reads calibration (evidence: `src/algolab/dashboard/app.py`)
- User → Dashboard: views monitor
- Live cycle → Loss limits: checks limits (evidence: `src/algolab/live/pipeline.py`)
- Live cycle → Operational state: locks and records (evidence: `src/algolab/live/pipeline.py`)
- Live cycle → Alerts: reports breaches (evidence: `src/algolab/live/pipeline.py`)