# kaniampurath/mytradingmind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kaniampurath/mytradingmind-ai
- Repository: https://github.com/kaniampurath/mytradingmind-ai

## Overview

1. **Overall shape**
   This repository is a layered trading-operations platform, not a single monolith. The core flow is: Binance testnet market data in, derived features and strategy evaluation in the middle, execution and persistence behind hard boundaries, and an operator dashboard plus headless runtime on top.

2. **Two main entry surfaces**
   The system is split between a **dashboard/UI plane** and a **runtime/control plane**. `aegis_trader/app.py`, `aegis_trader/dashboards/app.py`, and `mytradingmind/dashboard.py` serve the operator console, while `aegis_trader/runtime/*` and `mytradingmind/runtime.py` run bot lifecycle management, commands, supervision, and headless operation. The README emphasizes these are intentionally separate.

3. **Market connectivity and data ingestion**
   `aegis_trader/market_data/binance_stream.py` and `binance_history.py` connect to Binance Spot Testnet for websocket streams and historical candle backfills. Data is modeled in `market_data/models.py` and accumulated into multiple timeframes, which is the upstream source for both live bots and backtests. The scripts in `scripts/` wrap these ingestion paths for daily operations.

4. **Market data fabric**
   Once data is ingested, it is transformed by `features/engine.py`, `orderflow/engine.py`, and `regime/engine.py`. This layer enriches raw candles with indicators, flow context, and regime classification before any strategy logic sees it. The architecture keeps this derivation separate from strategy code so strategies remain consumers of prepared signals rather than data mungers.

5. **Strategy layer**
   Strategies live under `aegis_trader/strategies/` and are organized as pluggable backtest/live-compatible modules. `base.py`, `engine.py`, `plugins.py`, `backtest_plugins.py`, `optimization.py`, and `exits.py` suggest a registry-based strategy system with shared exit/risk logic and support for optimization and validation. The README makes the key boundary explicit: strategies should emit signals, not call the exchange, write directly to the database, or bypass risk gates.

6. **Decision, consensus, and risk**
   Before orders are allowed out, decisions pass through `consensus/engine.py`, `consensus/devils_advocate.py`, and `risk/engine.py`. This is the platform’s “hard gate” layer: it evaluates whether a strategy idea should be accepted, blocked, or modified by safety rules. The presence of `llm/consensus_reviewer.py`, `llm/reasoning_agent.py`, and `llm/fallback_rules.py` shows that LLM assistance exists, but with deterministic fallback and review paths rather than being the sole decision-maker.

7. **Execution boundary**
   Actual order handling is isolated in `execution/engine.py`, `oms/order_manager.py`, and `exchange/gateway.py`, with `exchange/binance_testnet_gateway.py` as the concrete exchange adapter. This is the boundary where strategy intent becomes testnet order flow. Keeping OMS and exchange access here prevents strategies or UI code from placing orders directly.

8. **Bot lifecycle and runtime control**
   Bots are managed as runtime objects, not just strategy instances. `runtime/bot_registry.py`, `bot_runner.py`, `runtime_manager.py`, `process_supervisor.py`, `heartbeat.py`, `command_bus.py`, and `runtime_state.py` form the orchestration layer for starting, stopping, pausing, resuming, and monitoring bots. `bot/framework.py` and `bot/stability_framework.py` suggest bot execution abstractions and resilience policies around that lifecycle.

9. **Persistence, journaling, and repositories**
   State is persisted through `storage/db.py`, `storage/models.py`, `storage/bot_repository.py`, `storage/scan_repository.py`, `storage/replay_store.py`, and `storage/async_writer.py`. `journal/writer.py` captures operator- and trade-relevant events, while the README and tests indicate MariaDB is the main durable store. This layer is separate from runtime so bots survive dashboard restarts and can be inspected later.

10. **Backtesting, replay, and analytics**
    Historical validation lives in `backtest/replay.py`, `analytics/replay_metrics.py`, `analytics/strategy_reports.py`, and `analytics/time_utils.py`. These modules consume stored or backfilled market data and replay strategy behavior to generate metrics, reports, and validation outputs. This is the offline counterpart to the live runtime and is central to the “testnet-first” workflow.

11. **Operator dashboard and visibility**
    The Streamlit-based operator UI is concentrated in `aegis_trader/dashboards/`. From the README, it exposes Bot Framework, Bot Runtime, Bot Admin, Validation Lab, Trade Management, Order Flow, Risk, System Health, and Journal views. This is a control and observability plane only; it is not the trading loop itself.

12. **LLM assistance as a bounded service**
    The `llm/` package contains client, prompts, commentary, trade explanation, and consensus review helpers. Architecturally, this is a support subsystem for journaling, analysis, and decision review, not a direct trading executor. The inclusion of fallback rules indicates the platform can degrade to deterministic behavior if LLM services are unavailable.

13. **Quality gates and safety testing**
    `testing/certification.py` and `testing/failure_injection.py`, plus the `tests/` suite, model the platform’s fail-closed philosophy. There are explicit tests for event bus behavior, runtime, dashboard screens, LLM fallback, deployment files, and stress scenarios. This makes validation part of the architecture, not an afterthought.

14. **Deployment and operational packaging**
    Deployment support is first-class via `deploy/docker-compose.yml`, `deploy/Dockerfile`, MariaDB bootstrap scripts, and Ubuntu helper notes. The `scripts/` directory contains runtime start/stop, backfill, streaming, validation, and readiness checks. That tooling reflects a system meant to run both locally and in a headless server environment with the same core components.

15. **Notable boundary between packages**
    The presence of both `aegis_trader/` and `mytradingmind/` suggests `aegis_trader` holds the substantive platform modules, while `mytradingmind` provides compatibility/launcher entry points for the current product branding. For an architecture diagram, treat `mytradingmind` as the front door and `aegis_trader` as the core subsystem implementation.

Main entry points: [`aegis_trader/runtime/runtime_manager.py`](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/runtime/runtime_manager.py) (Runtime Manager), [`aegis_trader/dashboards/app.py`](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/dashboards/app.py) (Operator UI), [`aegis_trader/strategies/engine.py`](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/strategies/engine.py) (Strategy Stack), [`aegis_trader/consensus/engine.py`](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/consensus/engine.py) (Consensus Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_interfaces["Interfaces"]
  node_node_mytradingmind_runtime["Runtime API<br/>entrypoint<br/>[runtime.py]"]
  node_node_mytradingmind_dashboard["Dashboard API<br/>entrypoint<br/>[dashboard.py]"]
  node_node_aegis_app["App Entrypoint<br/>[app.py]"]
  node_node_dashboards["Operator UI<br/>streamlit ui<br/>[app.py]"]
end

subgraph group_group_market["Market Pipeline"]
  node_node_market_data["Market Feed<br/>ingestion<br/>[binance_stream.py]"]
  node_node_features["Feature Engine<br/>feature derivation<br/>[engine.py]"]
  node_node_orderflow["Order Flow<br/>signal enrichment<br/>[engine.py]"]
  node_node_regime["Regime Engine<br/>classification<br/>[engine.py]"]
end

subgraph group_group_decision["Decision Gates"]
  node_node_strategies["Strategy Stack<br/>strategy framework<br/>[engine.py]"]
  node_node_consensus{{"Consensus Gate<br/>review gate<br/>[engine.py]"}}
  node_node_risk{{"Risk Engine<br/>risk gate<br/>[engine.py]"}}
  node_node_execution["Execution Engine<br/>execution boundary<br/>[engine.py]"]
  node_node_oms["Order Manager<br/>oms<br/>[order_manager.py]"]
  node_node_exchange["Testnet Gateway<br/>exchange adapter"]
end

subgraph group_group_runtime["Runtime & State"]
  node_node_runtime["Runtime Manager<br/>orchestration<br/>[runtime_manager.py]"]
  node_node_headless["Headless Service"]
  node_node_storage[("Storage Layer<br/>persistence<br/>[db.py]")]
  node_node_journal["Journal Writer<br/>event journaling<br/>[writer.py]"]
end

subgraph group_group_offline["Offline Validation"]
  node_node_backtest["Replay Engine<br/>backtest<br/>[replay.py]"]
  node_node_analytics["Analytics<br/>reports"]
  node_node_testing["Safety Checks<br/>validation<br/>[certification.py]"]
end

subgraph group_group_support["Support & Tooling"]
  node_node_llm["LLM Assist<br/>assistant support<br/>[llm_client.py]"]
  node_node_scripts["Ops Scripts<br/>ops tooling"]
  node_node_deploy["Deployment<br/>packaging<br/>[docker-compose.yml]"]
end

node_node_mytradingmind_dashboard -->|"opens"| node_node_dashboards
node_node_mytradingmind_runtime -->|"starts"| node_node_headless
node_node_aegis_app -->|"boots"| node_node_dashboards
node_node_market_data -->|"candle stream"| node_node_features
node_node_features -->|"enrich"| node_node_orderflow
node_node_orderflow -->|"context"| node_node_regime
node_node_regime -->|"signals"| node_node_strategies
node_node_strategies -->|"propose"| node_node_consensus
node_node_consensus -->|"gate"| node_node_risk
node_node_risk -->|"approve"| node_node_execution
node_node_execution -->|"manage"| node_node_oms
node_node_oms -->|"route"| node_node_exchange
node_node_runtime -->|"runs"| node_node_strategies
node_node_runtime -->|"persists"| node_node_storage
node_node_runtime -->|"records"| node_node_journal
node_node_headless -->|"supervises"| node_node_runtime
node_node_backtest -->|"replay data"| node_node_storage
node_node_backtest -->|"produces"| node_node_analytics
node_node_testing -->|"validates"| node_node_runtime
node_node_llm -->|"assists"| node_node_consensus
node_node_llm -->|"comments"| node_node_journal
node_node_scripts -->|"operates"| node_node_market_data
node_node_scripts -->|"controls"| node_node_headless
node_node_deploy -->|"packages"| node_node_storage
node_node_dashboards -->|"observes"| node_node_journal
node_node_dashboards -->|"controls"| node_node_runtime

click node_node_mytradingmind_runtime "https://github.com/kaniampurath/mytradingmind-ai/blob/main/mytradingmind/runtime.py"
click node_node_mytradingmind_dashboard "https://github.com/kaniampurath/mytradingmind-ai/blob/main/mytradingmind/dashboard.py"
click node_node_aegis_app "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/app.py"
click node_node_dashboards "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/dashboards/app.py"
click node_node_market_data "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/market_data/binance_stream.py"
click node_node_features "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/features/engine.py"
click node_node_orderflow "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/orderflow/engine.py"
click node_node_regime "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/regime/engine.py"
click node_node_strategies "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/strategies/engine.py"
click node_node_consensus "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/consensus/engine.py"
click node_node_risk "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/risk/engine.py"
click node_node_execution "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/execution/engine.py"
click node_node_oms "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/oms/order_manager.py"
click node_node_exchange "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/exchange/binance_testnet_gateway.py"
click node_node_runtime "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/runtime/runtime_manager.py"
click node_node_headless "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/runtime/headless_service.py"
click node_node_storage "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/storage/db.py"
click node_node_journal "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/journal/writer.py"
click node_node_backtest "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/backtest/replay.py"
click node_node_analytics "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/analytics/strategy_reports.py"
click node_node_testing "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/testing/certification.py"
click node_node_llm "https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/llm/llm_client.py"
click node_node_scripts "https://github.com/kaniampurath/mytradingmind-ai/blob/main/scripts/run_headless_runtime.py"
click node_node_deploy "https://github.com/kaniampurath/mytradingmind-ai/blob/main/deploy/docker-compose.yml"

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_node_mytradingmind_runtime,node_node_mytradingmind_dashboard,node_node_aegis_app,node_node_dashboards toneBlue
class node_node_market_data,node_node_features,node_node_orderflow,node_node_regime toneAmber
class node_node_strategies,node_node_consensus,node_node_risk,node_node_execution,node_node_oms,node_node_exchange toneMint
class node_node_runtime,node_node_headless,node_node_storage,node_node_journal toneRose
class node_node_backtest,node_node_analytics,node_node_testing toneIndigo
class node_node_llm,node_node_scripts,node_node_deploy toneTeal
```

## Components

### Interfaces

Operator-facing entry points and dashboard surfaces.

- [Runtime API](https://github.com/kaniampurath/mytradingmind-ai/blob/main/mytradingmind/runtime.py): entrypoint · Compatibility runtime launcher and headless entry surface. · `mytradingmind/runtime.py`
- [Dashboard API](https://github.com/kaniampurath/mytradingmind-ai/blob/main/mytradingmind/dashboard.py): entrypoint · Compatibility dashboard launcher for the operator console. · `mytradingmind/dashboard.py`
- [App Entrypoint](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/app.py): entrypoint · Primary application entry point. · `aegis_trader/app.py`
- [Operator UI](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/dashboards/app.py): streamlit ui · Dashboard package for bot ops, trade management, risk, and journal visibility. · `aegis_trader/dashboards/app.py`

### Market Pipeline

Ingestion and derived market context used by live and offline workflows.

- [Market Feed](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/market_data/binance_stream.py): ingestion · Binance testnet streaming, historical backfill, and candle models. · `aegis_trader/market_data/binance_stream.py`
- [Feature Engine](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/features/engine.py): feature derivation · Transforms raw candles into technical features. · `aegis_trader/features/engine.py`
- [Order Flow](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/orderflow/engine.py): signal enrichment · Adds flow context to market data. · `aegis_trader/orderflow/engine.py`
- [Regime Engine](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/regime/engine.py): classification · Classifies market regime for downstream consumers. · `aegis_trader/regime/engine.py`

### Decision Gates

Strategy, consensus, risk, and execution boundaries.

- [Strategy Stack](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/strategies/engine.py): strategy framework · Pluggable strategies, exits, optimization, and shared backtest/live adapters. · `aegis_trader/strategies/engine.py`
- [Consensus Gate](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/consensus/engine.py): review gate · Consensus and devil's-advocate review before orders proceed. · `aegis_trader/consensus/engine.py`
- [Risk Engine](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/risk/engine.py): risk gate · Hard risk controls that can block or modify decisions. · `aegis_trader/risk/engine.py`
- [Execution Engine](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/execution/engine.py): execution boundary · Coordinates order intent into OMS and exchange calls. · `aegis_trader/execution/engine.py`
- [Order Manager](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/oms/order_manager.py): oms · Owns order lifecycle handling inside the trading boundary. · `aegis_trader/oms/order_manager.py`
- [Testnet Gateway](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/exchange/binance_testnet_gateway.py): exchange adapter · Binance Spot Testnet gateway implementation. · `aegis_trader/exchange/binance_testnet_gateway.py`

### Runtime & State

Bot lifecycle, orchestration, persistence, and journaling.

- [Runtime Manager](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/runtime/runtime_manager.py): orchestration · Bot registry, runner, supervisor, commands, heartbeat, and runtime state. · `aegis_trader/runtime/runtime_manager.py`
- [Headless Service](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/runtime/headless_service.py): service · Headless runtime service used for unattended operation. · `aegis_trader/runtime/headless_service.py`
- [Storage Layer](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/storage/db.py): persistence · Database access, repositories, async writes, and replay storage. · `aegis_trader/storage/db.py`
- [Journal Writer](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/journal/writer.py): event journaling · Captures operator and trade-relevant event history. · `aegis_trader/journal/writer.py`

### Offline Validation

Backtesting, replay, analytics, and quality gates.

- [Replay Engine](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/backtest/replay.py): backtest · Historical replay and validation of strategy behavior. · `aegis_trader/backtest/replay.py`
- [Analytics](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/analytics/strategy_reports.py): reports · Replay metrics, strategy reports, and timing utilities. · `aegis_trader/analytics/strategy_reports.py`
- [Safety Checks](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/testing/certification.py): validation · Certification and failure-injection harnesses for fail-closed behavior. · `aegis_trader/testing/certification.py`

### Support & Tooling

LLM helpers, scripts, deployment, and package front doors.

- [LLM Assist](https://github.com/kaniampurath/mytradingmind-ai/blob/main/aegis_trader/llm/llm_client.py): assistant support · Reasoning, review, commentary, and deterministic fallback helpers. · `aegis_trader/llm/llm_client.py`
- [Ops Scripts](https://github.com/kaniampurath/mytradingmind-ai/blob/main/scripts/run_headless_runtime.py): ops tooling · Backfill, stream, runtime, validation, and readiness scripts. · `scripts/run_headless_runtime.py`
- [Deployment](https://github.com/kaniampurath/mytradingmind-ai/blob/main/deploy/docker-compose.yml): packaging · Docker, compose, and database bootstrap packaging. · `deploy/docker-compose.yml`

## Connections

- Dashboard API → Operator UI: opens · Launcher routes operators into the dashboard surface.
- Runtime API → Headless Service: starts · Compatibility runtime entry starts headless operation.
- App Entrypoint → Operator UI: boots · Primary app can boot the operator UI.
- Market Feed → Feature Engine: candle stream · Raw market data feeds feature derivation.
- Feature Engine → Order Flow: enrich · Feature layer hands context to order-flow analysis.
- Order Flow → Regime Engine: context · Order-flow context informs regime classification.
- Regime Engine → Strategy Stack: signals · Prepared market context is consumed by strategy modules.
- Strategy Stack → Consensus Gate: propose · Strategies emit candidates for review.
- Consensus Gate → Risk Engine: gate · Consensus output is constrained by risk controls.
- Risk Engine → Execution Engine: approve · Only approved intents proceed to execution.
- Execution Engine → Order Manager: manage · Execution delegates order lifecycle handling to OMS.
- Order Manager → Testnet Gateway: route · OMS routes orders to the exchange adapter.
- Runtime Manager → Strategy Stack: runs · Runtime manager hosts strategy-capable bots.
- Runtime Manager → Storage Layer: persists · Runtime state and bot records are stored durably.
- Runtime Manager → Journal Writer: records · Bot and operator events are journaled.
- Headless Service → Runtime Manager: supervises · Headless service wraps lifecycle orchestration.
- Replay Engine → Storage Layer: replay data · Replay consumes stored historical runs and market state.
- Replay Engine → Analytics: produces · Backtests feed metrics and reports.
- Safety Checks → Runtime Manager: validates · Certification and failure injection exercise runtime behavior.
- LLM Assist → Consensus Gate: assists · LLM review supports consensus, with fallback rules.
- LLM Assist → Journal Writer: comments · LLM-generated commentary and explanations support journaling.
- Ops Scripts → Market Feed: operates · Scripts wrap backfill and streaming workflows.
- Ops Scripts → Headless Service: controls · Scripts start, stop, and monitor the headless runtime.
- Deployment → Storage Layer: packages · Deployment assets include database bootstrap and runtime packaging.
- Operator UI → Journal Writer: observes · Dashboard surfaces journal and operational visibility.
- Operator UI → Runtime Manager: controls · UI issues runtime actions through the control plane.
