# UI Architecture — Trading / Paper / Calibration Modes

## Objetivo General
Construir una UI web unificada para el bot de trading con **tres modos claramente separados**, cada uno con un propósito distinto:

1) **Trading Mode** — Supervisión de trading real (LIVE)
2) **Paper Mode** — Supervisión de simulación en tiempo real
3) **Calibration Mode** — Workflow guiado de investigación y calibración

El selector de modo será global (dropdown en navbar) y cada modo tendrá sus propios tabs y vistas.

---

## Navegación Global

### Selector de Modo (Dropdown obligatorio)
Ubicado en la barra superior:

- Mode
  - Trading
  - Paper
  - Calibration

Reglas:
- El modo activo define completamente la UI.
- Cada modo tiene su propio set de tabs.
- Persistir el modo seleccionado en `localStorage`.
- URLs separadas:
  - `/ui/trading/...`
  - `/ui/paper/...`
  - `/ui/calibrate/...`

---

## 🔵 Trading Mode (LIVE)

### Propósito
Supervisar **trading real** con foco en:
- estabilidad
- riesgo
- latencia
- seguridad

Este modo debe ser **sobrio y conservador**.

---

### Tabs — Trading Mode

#### 1) Overview
**Pregunta que responde:**  
> ¿El bot está operando correctamente ahora mismo?

Componentes:
- KPIs (obligatorios):
  - Equity
  - Realized PnL
  - Max Drawdown (según rango)
  - **Latency (obligatoria)**  
    - exchange latency
    - data latency
    - execution latency (si existe)
  - Bot State (RUNNING / PAUSED / ERROR)
  - Last heartbeat / last update timestamp
- Gráfica:
  - Equity curve (simplificada)
  - Rango: 1h / 6h / 24h / ALL
- Alertas críticas:
  - Latency > threshold
  - Exchange unreachable
  - No new data
  - Errors

---

#### 2) Positions
- Open Positions
- Closed Positions
Datos mínimos:
- Symbol
- Side
- Size / Notional
- Entry / Exit
- PnL
- Strategy
- Duration

Fuente de verdad:
- `broker_snapshot` (preferido)

---

#### 3) Trades
Log detallado de ejecución:
- timestamp
- symbol
- side
- price
- qty
- fee
- latency (si existe)
- strategy

---

#### 4) Risk / Performance
- Max DD
- Current DD
- Exposure
- Win rate
- Avg trade
- Expectancy

---

#### 5) Events / Logs
- INFO / WARN / ERROR
- búsqueda y filtros
- útil para incidentes

---

## 🟢 Paper Mode (SIMULATION)

### Propósito
Validar comportamiento del bot **en tiempo real sin riesgo**.

Este modo es **más analítico y visual** que Trading Mode.

---

### Tabs — Paper Mode

#### 1) Overview
(Ya implementado en gran parte)

Componentes:
- KPIs:
  - Equity
  - Realized PnL
  - Max DD
  - **Latency (obligatoria también aquí)**
  - Bot State
- Gráfica avanzada:
  - Equity + Cash
  - Drawdown shading (toggle)
  - Markers BUY / SELL
  - Tooltips ricos
  - Zoom / Pan
  - Rango: 1h / 6h / 24h / ALL

---

#### 2) Positions
Igual que Trading Mode, pero en simulación.

---

#### 3) Trades
Igual que Trading Mode, con más detalle si se desea.

---

#### 4) Performance
Más libertad que en Trading:
- Distribución de retornos
- Drawdown curve
- Rolling metrics

---

#### 5) Events
Eventos del loop de paper trading:
- señales
- ejecuciones
- warnings

---

## 🟣 Calibration Mode (WORKFLOW)

### Propósito
Convertir el proceso manual de investigación/calibración en un **pipeline reproducible y guiado**.

Este modo **no es realtime**.

---

### Filosofía
- Cada calibración = una sesión
- Cada paso = un run
- Todo genera artefactos versionados
- Reproducibilidad total

---

### Tabs — Calibration Mode (Wizard)

1) Select Asset
2) Download / Prepare Data
3) Market Regimes / Filters (opcional)
4) Stops / Risk Model
5) Strategy Selection
6) Parameter Search / Optimization
7) Walk-Forward Validation
8) Portfolio Builder
9) Export / Deploy

Cada tab:
- inputs controlados
- botón “Run”
- logs del run
- outputs:
  - tablas
  - gráficas
  - métricas
- artefactos persistidos

---

## Backend — Principios

- Trading/Paper: endpoints read-only + polling
- Calibration: jobs asincrónicos
- No ejecutar procesos largos en requests síncronas

Persistencia mínima:
- calibration_sessions
- calibration_runs
- calibration_artifacts

Artefactos:
- `data/calibration/{session_id}/{run_id}/`

---

## Frontend — Principios

- Modo define layout y navegación
- Tabs solo dentro del modo
- Componentes reutilizables:
  - KPICard
  - DataTable
  - ChartPanel
  - LogViewer
  - ArtifactViewer

---

## Roadmap de Implementación

### Fase 1 — Paper Mode completo
- Overview (hecho)
- Positions
- Trades
- Performance
- Events

### Fase 2 — Trading Mode
- Reutilizar vistas
- Añadir latencia + alertas
- UX más conservadora

### Fase 3 — Calibration Mode (Skeleton)
- Session management
- Select Asset
- Download Data

### Fase 4 — Calibration Core
- Stops
- Strategies
- Params
- Walk Forward

### Fase 5 — Portfolio + Export
- Construcción de portfolio
- Export a configs
- Reproducibilidad

---

## Decisiones Abiertas
- Modelo exacto de latencia (qué medir y cómo)
- Fuente final de posiciones (broker_snapshot vs derivado)
- Motor de jobs (threads vs celery)
- Formato final de export (json/yaml)