┌─────────────────────────────────────────────────────────────────────────────┐
│                           Retail Order Sync Hub                             │
│                                                                             │
│  ┌─────────┐   outbox   ┌──────────────┐    ┌────────────┐                │
│  │  Odoo   │──pattern──▶│ Outbox Worker│───▶│ Adapters   │──▶ MercadoLibre│
│  │  (ERP)  │            │  retry/DLQ   │    │ ML · Paris │──▶ paris-mock  │
│  └─────────┘            └──────────────┘    └────────────┘                │
│       ▲                        │                   │                       │
│       │                   sync.dlq            webhooks                     │
│  reconcile              (Pub/Sub)           (signed · idempotent)         │
│       │                                           │                        │
│  ┌────┴────────────┐                    ┌─────────▼──────┐                │
│  │ Subscriber +    │◀── marketplace ────│ Webhook         │               │
│  │ Reconciler      │      .events       │ Receiver        │               │
│  │ (silver orders) │    (Pub/Sub)       │ (bronze · dedup)│               │
│  └────────┬────────┘                    └────────┬────────┘               │
│           │                                      │                         │
│     ┌─────▼──────────────────────────────────────▼──────┐                 │
│     │                   BigQuery                         │                 │
│     │   bronze (raw) → silver (clean) → gold (SLA/KPIs) │                 │
│     │   dbt models · contracts · singular tests          │                 │
│     └─────────────────────────┬──────────────────────────┘                │
│                               │                                            │
│  ┌────────────────────────────▼──────────────────────────┐                │
│  │                    MCP Server                          │                │
│  │  get_order_status · trace_order · get_dlq_depth        │                │
│  │  get_sla_metrics · find_failed_orders                  │                │
│  │  replay_dlq_message · retry_failed_sync · drain_dlq    │                │
│  │  IAM (scopes: orders.read / dlq.replay / dlq.admin)    │                │
│  │  Audit log (mcp_audit_log, transacción separada)       │                │
│  └────────────────────────────▲──────────────────────────┘                │
│                               │ MCP protocol (stdio)                       │
│                          Claude Code / Desktop                             │
│                                                                            │
│  ┌──────────────────────────────────────────────────────┐                 │
│  │  Observabilidad: OTel Collector → Prometheus + Tempo  │                │
│  │  Grafana: Comex Ops dashboard · Pipeline Health       │                │
│  └──────────────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────────────┘

make console   # abre http://localhost:8501

git clone https://github.com/JulioPradenas/retail-order-sync-hub.git
cd retail-order-sync-hub
uv sync --dev

make up         # Odoo, Postgres, Pub/Sub emulator, paris-mock
make migrate    # aplica migraciones Alembic
make seed       # carga órdenes demo en Odoo

# Check de código + tests (85%+ cobertura)
make check

# Odoo disponible en
open http://localhost:8069  # admin / admin

# Paris-mock en
curl http://localhost:9100/orders -H "X-API-Key: change-me"

# Webhook receiver
curl http://localhost:8000/health

make obs-up     # Grafana + Prometheus + Tempo + OTel Collector
open http://localhost:3000  # Grafana — admin / admin

make up && make migrate
ROSH_INTEGRATION=1 uv run pytest -m integration -v

cp dbt/profiles.yml.template ~/.dbt/profiles.yml
# Edita con tu project_id y credenciales
cd dbt && uv run dbt run && uv run dbt test

{
  "mcpServers": {
    "retail-order-sync-hub": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_server"],
      "cwd": "/ruta/al/retail-order-sync-hub",
      "env": {
        "MCP_STATIC_TOKENS": "mi-token:orders.read,metrics.read,outbox.retry,dlq.replay",
        "APP_DB_HOST": "localhost",
        "APP_DB_PORT": "5433"
      }
    }
  }
}

¿Por qué la orden ML-12345 no llegó a MercadoLibre?
trace_order("ML-12345")

¿Cuántas órdenes están bloqueadas en DLQ en este momento?
get_dlq_depth()

Hay 3 órdenes atascadas — reintentar todas con retry
retry_failed_sync("12345")

src/
  adapters/          # Paris + MercadoLibre adapters (Protocol-based)
  bq_sync/           # BigQuery watermark sync (bronze)
  common/            # Config, DB, models, logging, OTel, signing
  mcp_server/        # FastMCP server (read + write tools, IAM, audit)
  outbox_worker/     # Outbox processor con retry exponencial + DLQ
  paris_mock/        # Mock del marketplace Paris (FastAPI)
  reconciler/        # Reconciliación silver → Odoo
  subscriber/        # Pub/Sub subscriber → normalize → silver
  webhook_receiver/  # Inbound webhooks (HMAC, dedupe, bronze)
infra/
  docker-compose.yml        # Stack operacional
  docker-compose.obs.yml    # Stack de observabilidad
  grafana/                  # Dashboards y datasources
dbt/                        # Modelos bronze/silver/gold + contratos
migrations/                 # Alembic migrations
tests/
  unit/              # 141 tests unitarios (85%+ cobertura)
  integration/       # Tests contra el stack real (ROSH_INTEGRATION=1)
docs/
adr/