# alejo24288-byte/trading-optimizer architecture

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

- Interactive diagram: https://gitdiagram.com/alejo24288-byte/trading-optimizer
- Repository: https://github.com/alejo24288-byte/trading-optimizer

## Overview

#### Propósito y entradas
Repositorio de trading SMC (Smart Money Concepts) para BTC/USDT: combina backtesting histórico y un radar de alertas en vivo multi-temporal. Las entradas operativas principales son `live_alert_bot.py` (scanner en vivo), `macro_analyst_agent.py` (proceso macro auxiliar), y los runners de backtest `main.py` y `mtf_main.py`.

#### Núcleo de estrategia SMC
`strategy_logic.py` concentra la lógica reutilizable de estructura de mercado, rupturas de estructura (BOS) y Order Blocks (OB). Es el límite entre datos de velas y señales/zonas de trading. `SMC_Backtester.pine` representa una implementación separada para TradingView/Pine Script, útil para contrastar o visualizar la estrategia, pero no forma parte del runtime Python.

#### Ingesta y normalización de mercado
`data_ingestion.py` es la capa de adquisición de datos históricos/de mercado para los flujos Python. En vivo, `live_alert_bot.py` obtiene velas de Binance mediante CCXT en 1h, 30m, 15m y 5m, además del libro de órdenes cuando una zona es tocada. Binance es la dependencia externa principal del análisis de precio y liquidez.

#### Pipeline de alertas en vivo
`live_alert_bot.py` orquesta el ciclo periódico: descarga la matriz temporal, calcula OBs por timeframe, usa 5m como gatillo, y busca anidamiento/confluencia contra OBs de 15m, 30m y 1h. Al entrar el precio en un OB, consulta profundidad de mercado y clasifica la alerta: OB aislado, confluencia multi-timeframe, o confluencia respaldada por volumen pasivo (“ballena”). El script calcula parámetros sugeridos de entrada, stop y take-profit según riesgo, apalancamiento, RR y ATR; su salida es de consola/sonido, no ejecución automática de órdenes.

#### Contexto macro con IA
`macro_analyst_agent.py` corre independientemente del scanner y actualiza sentimiento macro aproximadamente cada 15 minutos. Consume feeds/noticias y Google Gemini para producir una clasificación BULLISH, BEARISH o NEUTRAL que sirve como contexto para las alertas. La integración con Gemini requiere credenciales/API key y representa un límite de disponibilidad/coste externo.

#### Backtesting de una y múltiples temporalidades
`backtester.py` implementa el flujo histórico base alrededor de la estrategia. `mtf_backtester.py` y `mtf_backtest_logic.py` extienden ese análisis para reglas multi-timeframe, con `mtf_main.py` como entrada dedicada. Estos componentes permiten evaluar la estrategia antes de modificar parámetros del bot en vivo, pero sus resultados no sustituyen la validación manual requerida para ejecutar operaciones.

#### Límites operativos e infraestructura
El runtime es Python y sus dependencias están declaradas en `requirements.txt`; destacan CCXT para Binance y librerías de Gemini/feeds para el agente macro. La arquitectura se opera como procesos locales separados —scanner y agente macro— sin servidor, base de datos, API propia ni capa de ejecución de trading indicada. La decisión final y la colocación de órdenes LIMIT permanecen fuera del sistema, en Binance y bajo validación humana.

Main entry points: [`live_alert_bot.py`](https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py) (Scanner de alertas), [`strategy_logic.py`](https://github.com/alejo24288-byte/trading-optimizer/blob/main/strategy_logic.py) (Lógica SMC), [`macro_analyst_agent.py`](https://github.com/alejo24288-byte/trading-optimizer/blob/main/macro_analyst_agent.py) (Agente macro), [`backtester.py`](https://github.com/alejo24288-byte/trading-optimizer/blob/main/backtester.py) (Backtester base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Alertas en vivo"]
  node_live_bot["Scanner de alertas<br/>Python entrypoint<br/>[live_alert_bot.py]"]
  node_candle_matrix["Matriz de velas<br/>Market data"]
  node_confluence["Confluencia y riesgo<br/>Alert logic<br/>[live_alert_bot.py]"]
  node_order_book["Profundidad al tocar OB<br/>Liquidity check<br/>[live_alert_bot.py]"]
  node_alert_output["Consola y sonido<br/>Alert output<br/>[live_alert_bot.py]"]
  node_macro_agent["Agente macro<br/>Python process"]
end

subgraph group_backtest["Backtesting"]
  node_main["Runner histórico<br/>Python entrypoint<br/>[main.py]"]
  node_backtester["Backtester base<br/>Historical engine<br/>[backtester.py]"]
  node_mtf_main["Runner MTF<br/>Python entrypoint<br/>[mtf_main.py]"]
  node_mtf_backtester["Backtester MTF<br/>Historical engine<br/>[mtf_backtester.py]"]
  node_mtf_logic["Reglas MTF<br/>Strategy extension"]
end

subgraph group_strategy["Estrategia SMC"]
  node_strategy_logic{{"Lógica SMC<br/>Strategy core<br/>[strategy_logic.py]"}}
  node_pine["Implementación Pine<br/>TradingView script"]
  node_ingestion["Ingesta histórica<br/>Data acquisition<br/>[data_ingestion.py]"]
end

subgraph group_external["Servicios externos"]
  node_binance(("Binance<br/>Exchange API"))
  node_gemini_feeds(("Gemini y feeds<br/>AI/news services"))
  node_human["Validación humana y órdenes LIMIT<br/>Manual operation"]
end

node_requirements["Dependencias Python<br/>Runtime manifest<br/>[requirements.txt]"]

node_binance -->|"velas"| node_candle_matrix
node_candle_matrix -->|"datos de mercado"| node_live_bot
node_live_bot -->|"calcula OBs"| node_strategy_logic
node_strategy_logic -->|"OBs y estructura"| node_confluence
node_live_bot -->|"al tocar zona"| node_order_book
node_binance -->|"libro de órdenes"| node_order_book
node_order_book -->|"liquidez pasiva"| node_confluence
node_confluence -->|"alerta clasificada"| node_alert_output
node_gemini_feeds -->|"noticias e IA"| node_macro_agent
node_macro_agent -.->|"contexto macro"| node_live_bot
node_ingestion -->|"histórico"| node_backtester
node_main -->|"ejecuta"| node_backtester
node_backtester -->|"evalúa"| node_strategy_logic
node_mtf_main -->|"ejecuta"| node_mtf_backtester
node_mtf_backtester -->|"aplica"| node_mtf_logic
node_mtf_logic -->|"extiende"| node_strategy_logic
node_alert_output -->|"requiere validación"| node_human
node_requirements -.->|"runtime"| node_live_bot
node_requirements -.->|"runtime"| node_macro_agent

click node_live_bot "https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py"
click node_confluence "https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py"
click node_order_book "https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py"
click node_alert_output "https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py"
click node_macro_agent "https://github.com/alejo24288-byte/trading-optimizer/blob/main/macro_analyst_agent.py"
click node_main "https://github.com/alejo24288-byte/trading-optimizer/blob/main/main.py"
click node_backtester "https://github.com/alejo24288-byte/trading-optimizer/blob/main/backtester.py"
click node_mtf_main "https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_main.py"
click node_mtf_backtester "https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_backtester.py"
click node_mtf_logic "https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_backtest_logic.py"
click node_strategy_logic "https://github.com/alejo24288-byte/trading-optimizer/blob/main/strategy_logic.py"
click node_pine "https://github.com/alejo24288-byte/trading-optimizer/blob/main/SMC_Backtester.pine"
click node_ingestion "https://github.com/alejo24288-byte/trading-optimizer/blob/main/data_ingestion.py"
click node_requirements "https://github.com/alejo24288-byte/trading-optimizer/blob/main/requirements.txt"

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_live_bot,node_candle_matrix,node_confluence,node_order_book,node_alert_output,node_macro_agent toneBlue
class node_main,node_backtester,node_mtf_main,node_mtf_backtester,node_mtf_logic toneAmber
class node_strategy_logic,node_pine,node_ingestion toneMint
class node_binance,node_gemini_feeds,node_human toneRose
class node_requirements toneNeutral
```

## Components

### Alertas en vivo

- [Scanner de alertas](https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py): Python entrypoint · Orquesta el análisis periódico multi-timeframe y emite alertas. · `live_alert_bot.py`
- **Matriz de velas**: Market data · Velas BTC/USDT de 1h, 30m, 15m y 5m.
- [Confluencia y riesgo](https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py): Alert logic · Usa 5m como gatillo y calcula entrada, stop y take-profit. · `live_alert_bot.py`
- [Profundidad al tocar OB](https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py): Liquidity check · Clasifica respaldo por volumen pasivo o ballena. · `live_alert_bot.py`
- [Consola y sonido](https://github.com/alejo24288-byte/trading-optimizer/blob/main/live_alert_bot.py): Alert output · No ejecuta órdenes automáticamente. · `live_alert_bot.py`
- [Agente macro](https://github.com/alejo24288-byte/trading-optimizer/blob/main/macro_analyst_agent.py): Python process · Actualiza sentimiento BULLISH, BEARISH o NEUTRAL cada ~15 minutos. · `macro_analyst_agent.py`

### Backtesting

- [Runner histórico](https://github.com/alejo24288-byte/trading-optimizer/blob/main/main.py): Python entrypoint · `main.py`
- [Backtester base](https://github.com/alejo24288-byte/trading-optimizer/blob/main/backtester.py): Historical engine · `backtester.py`
- [Runner MTF](https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_main.py): Python entrypoint · `mtf_main.py`
- [Backtester MTF](https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_backtester.py): Historical engine · `mtf_backtester.py`
- [Reglas MTF](https://github.com/alejo24288-byte/trading-optimizer/blob/main/mtf_backtest_logic.py): Strategy extension · `mtf_backtest_logic.py`

### Estrategia SMC

- [Lógica SMC](https://github.com/alejo24288-byte/trading-optimizer/blob/main/strategy_logic.py): Strategy core · Calcula estructura, BOS y Order Blocks reutilizables. · `strategy_logic.py`
- [Implementación Pine](https://github.com/alejo24288-byte/trading-optimizer/blob/main/SMC_Backtester.pine): TradingView script · Implementación separada para contraste y visualización. · `SMC_Backtester.pine`
- [Ingesta histórica](https://github.com/alejo24288-byte/trading-optimizer/blob/main/data_ingestion.py): Data acquisition · `data_ingestion.py`

### Servicios externos

- **Binance**: Exchange API · Fuente externa de velas y libro de órdenes.
- **Gemini y feeds**: AI/news services · Requiere credenciales y tiene coste/disponibilidad externos.
- **Validación humana y órdenes LIMIT**: Manual operation · La decisión final y ejecución quedan fuera del sistema.

### Other components

- [Dependencias Python](https://github.com/alejo24288-byte/trading-optimizer/blob/main/requirements.txt): Runtime manifest · Declara CCXT y librerías de Gemini/feeds. · `requirements.txt`

## Connections

- Binance → Matriz de velas: velas
- Matriz de velas → Scanner de alertas: datos de mercado
- Scanner de alertas → Lógica SMC: calcula OBs
- Lógica SMC → Confluencia y riesgo: OBs y estructura
- Scanner de alertas → Profundidad al tocar OB: al tocar zona
- Binance → Profundidad al tocar OB: libro de órdenes
- Profundidad al tocar OB → Confluencia y riesgo: liquidez pasiva
- Confluencia y riesgo → Consola y sonido: alerta clasificada
- Gemini y feeds → Agente macro: noticias e IA
- Agente macro → Scanner de alertas: contexto macro · Proceso independiente.
- Ingesta histórica → Backtester base: histórico
- Runner histórico → Backtester base: ejecuta
- Backtester base → Lógica SMC: evalúa
- Runner MTF → Backtester MTF: ejecuta
- Backtester MTF → Reglas MTF: aplica
- Reglas MTF → Lógica SMC: extiende
- Consola y sonido → Validación humana y órdenes LIMIT: requiere validación
- Dependencias Python → Scanner de alertas: runtime
- Dependencias Python → Agente macro: runtime