Cerbero-Bite/docs/02-architecture.md

# 02 — Architettura

## Vista a blocchi

```
                        ┌─────────────────────────────────┐
                        │        ADRIANO (utente)         │
                        └──────▲──────────────────────────┘
                               │ Telegram (notifiche post-fact)
                               │
┌─────────────────────────────────────────────────────────────────┐
│                       CERBERO BITE (rule engine)                │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐   ┌──────────────────┐    │
│  │  scheduler   │    │  state store │   │   audit logger   │    │
│  │ (APScheduler)│    │   (SQLite)   │   │   (append-only,  │    │
│  │              │    │              │   │   hash chain +   │    │
│  │              │    │              │   │   anchor SQLite) │    │
│  └──────┬───────┘    └──────┬───────┘   └──────┬───────────┘    │
│         │                   │                  │                │
│         ▼                   ▼                  ▼                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              decision orchestrator (core/)              │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │    │
│  │  │  entry   │  │  sizing  │  │  exit    │  │  greeks  │ │    │
│  │  │validator │  │  engine  │  │ decision │  │aggregator│ │    │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘ │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │    │
│  │  │liquidity │  │  combo   │  │ kelly    │               │    │
│  │  │  gate    │  │ builder  │  │ recalib  │               │    │
│  │  └──────────┘  └──────────┘  └──────────┘               │    │
│  └─────────────────────────────────────────────────────────┘    │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              MCP HTTP client wrappers (clients/)        │    │
│  │   Deribit │ Hyperliquid │ Macro │ Sentiment │ Portfolio │    │
│  │   Telegram                                              │    │
│  └─────────────────────────────────────────────────────────┘    │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTP (Bearer token, rete Docker
                         │   `cerbero-suite`)
                         ▼
        ┌──────────────────────────────────┐
        │         MCP servers              │
        │  (FastAPI, repo Cerbero_mcp)     │
        └────────────────────┬─────────────┘
                             │
                             ▼
                      ┌────────────────┐
                      │     Deribit    │
                      │ (testnet o     │
                      │  mainnet)      │
                      └────────────────┘
```

Cerbero Bite è completamente autonomo: l'esecuzione degli ordini
combo passa direttamente per `mcp-deribit.place_combo_order`, senza
intermediazioni. Telegram serve esclusivamente per notificare ad
Adriano gli eventi post-fact (entry placed, exit filled, alert).

## Stack tecnologico

| Strato | Scelta | Motivazione |
|---|---|---|
| Linguaggio | Python 3.13 | Allineato a `Cerbero_mcp` |
| Async runtime | `asyncio` | Necessario per i client HTTP MCP e lo scheduler |
| Scheduler | `APScheduler` `AsyncIOScheduler` | Cron-like + interval-based, in-process |
| Persistenza stato | SQLite (file singolo) con WAL + `synchronous=NORMAL` | Zero deploy overhead, transazionale, sufficiente per ≤ 4 posizioni |
| Persistenza log | File `.jsonl` rotativi giornalieri (gzip > 30 g) | Audit-friendly, append-only, parseable |
| Audit immutabile | `data/audit.log` con hash chain SHA-256 + anchor in `system_state.last_audit_hash` | Anti-tampering + anti-truncation |
| Validazione config | `pydantic` v2 | Schema a runtime su `strategy.yaml` |
| Test | `pytest` + `pytest-asyncio` + `pytest-httpx` + `hypothesis` | TDD, integration con MCP fake |
| Type checking | `mypy --strict` | Disciplina, niente sorprese a runtime |
| Format/lint | `ruff` | Standard del progetto |
| Dependency manager | `uv` | Coerente con `Cerbero_mcp` |
| Client MCP | `httpx.AsyncClient` long-lived (pooling) + `tenacity` per retry | HTTP REST diretto, non SDK `mcp` |
| Notifiche | Bot API Telegram in-process (notify-only) | Token e chat-id da env, no-op se non configurati |
| GUI | `streamlit` ≥ 1.40 + `plotly` (Fase 4.5) | Dashboard locale, processo separato |

## Layout cartelle

```
Cerbero_Bite/
├── README.md
├── pyproject.toml
├── uv.lock
├── strategy.yaml                         # config golden + execution.environment
├── strategy.local.yaml.example           # override locale (gitignored)
├── Dockerfile                            # image runtime + HEALTHCHECK
├── docker-compose.yml                    # rete external cerbero-suite, env passthrough
├── .env.example                          # template variabili (token MCP, bot tag, modalità)
├── docs/                                  # questa documentazione
├── src/cerbero_bite/
│   ├── __init__.py
│   ├── __main__.py                        # entry point CLI
│   ├── cli.py                             # status, start, dry-run, stop,
│   │                                      # ping, healthcheck, kill-switch,
│   │                                      # state, audit, config
│   ├── core/                              # algoritmi puri (no I/O)
│   │   ├── entry_validator.py
│   │   ├── sizing_engine.py
│   │   ├── exit_decision.py
│   │   ├── greeks_aggregator.py
│   │   ├── liquidity_gate.py
│   │   ├── combo_builder.py
│   │   ├── kelly_recalibration.py
│   │   └── types.py                       # OptionQuote, OptionLeg
│   ├── clients/                           # wrapper HTTP sui MCP
│   │   ├── _base.py                       # HttpToolClient + retry/timeout
│   │   ├── _exceptions.py                 # McpError gerarchia
│   │   ├── deribit.py
│   │   ├── hyperliquid.py
│   │   ├── macro.py
│   │   ├── sentiment.py
│   │   ├── portfolio.py
│   │   └── telegram.py
│   ├── runtime/                           # I/O, scheduling, orchestrazione
│   │   ├── orchestrator.py                # façade boot/run_*
│   │   ├── dependencies.py                # RuntimeContext factory
│   │   ├── scheduler.py                   # APScheduler builder
│   │   ├── lockfile.py                    # fcntl.flock single-instance
│   │   ├── alert_manager.py               # severity routing
│   │   ├── health_check.py                # ping + 3-strikes kill switch
│   │   ├── entry_cycle.py                 # weekly entry auto-execute
│   │   ├── monitor_cycle.py               # 12h exit auto-execute
│   │   └── recovery.py                    # state reconcile al boot
│   ├── state/                             # persistenza
│   │   ├── repository.py
│   │   ├── models.py
│   │   ├── db.py                          # connect, transaction, run_migrations
│   │   └── migrations/
│   │       ├── 0001_init.sql
│   │       └── 0002_audit_anchor.sql
│   ├── config/                            # caricamento e validazione yaml
│   │   ├── schema.py
│   │   ├── loader.py
│   │   ├── mcp_endpoints.py               # URL + token + bot tag (da .env)
│   │   └── runtime_flags.py               # ENABLE_DATA_ANALYSIS / ENABLE_STRATEGY
│   ├── reporting/                         # report umani (Fase 5)
│   ├── gui/                               # Streamlit dashboard (Fase 4.5)
│   └── safety/                            # kill switch, dead man, audit
│       ├── kill_switch.py
│       ├── audit_log.py                   # hash chain + on_append callback
│       └── __init__.py
├── tests/
│   ├── unit/                              # test puri sui moduli core/
│   ├── integration/                       # test con MCP fake (httpx mock)
│   ├── golden/                            # scenari deterministici (Fase 6)
│   └── fixtures/
├── scripts/
│   ├── backup.py                          # VACUUM INTO orario
│   └── dead_man.sh                        # watchdog shell indipendente
└── data/                                  # gitignored
    ├── state.sqlite
    ├── audit.log
    ├── log/
    └── backups/
```

## Principio di separazione

- **`core/`** contiene **funzioni pure**: input → output, niente I/O,
  niente MCP, niente time. Testabili con dati statici. Sono il cuore
  della strategia e devono restare riproducibili al byte.
- **`clients/`** contiene wrapper HTTP sui server MCP. Ogni client
  espone una API tipizzata che usa internamente `httpx.AsyncClient`.
  Mai logica di business qui.
- **`runtime/`** orchestrazione: composizione di `clients/` + `core/`
  + `state/` + `safety/`. È l'unico strato che può fare I/O e ha
  effetti collaterali. Espone `Orchestrator` come façade per il CLI.
- **`state/`** persistenza. Mai logica di business. Solo CRUD.
- **`config/`** caricamento di `strategy.yaml`, validazione,
  esposizione immutabile dei parametri. Risolve gli URL MCP, legge
  il bearer token + il bot tag al boot ed espone i due interruttori
  operativi `RuntimeFlags(data_analysis_enabled, strategy_enabled)`.
- **`safety/`** controlli trasversali (vedere `07-risk-controls.md`).
- **`reporting/`** generazione di stringhe per Telegram. Niente
  logica di trading, solo formatting.

## Decision orchestrator — sequenza tipo per "Lunedì 14:00 UTC"

```python
async def run_entry_cycle(ctx: RuntimeContext, *, eur_to_usd_rate, now):
    if ctx.kill_switch.is_armed():
        return EntryCycleResult(status="kill_switch_armed", ...)
    if ctx.repository.count_concurrent_positions() > 0:
        return EntryCycleResult(status="has_open_position", ...)

    # 1. Snapshot dati di mercato in parallelo (asyncio.gather)
    snap = await _gather_snapshot(
        deribit, hyperliquid, sentiment, macro, portfolio, cfg, now
    )

    # 2. Algoritmi puri
    entry_decision = validate_entry(EntryContext(...), cfg)
    if not entry_decision.accepted:
        return EntryCycleResult(status="no_entry", reason=entry_decision.reasons)

    bias = compute_bias(TrendContext(...), cfg)
    if bias is None:
        return EntryCycleResult(status="no_entry", reason="no_bias")

    chain = await deribit.options_chain(currency="ETH", expiry_from=..., expiry_to=...)
    quotes = await _build_quotes(deribit, chain)
    selection = select_strikes(chain=quotes, bias=bias, spot=spot, now=now, cfg=cfg)
    if selection is None:
        return EntryCycleResult(status="no_entry", reason="no_strike")

    short, long_ = selection
    sizing = compute_contracts(SizingContext(...), cfg)
    if sizing.n_contracts < 1:
        return EntryCycleResult(status="no_entry", reason="undersize")

    if not check(short_leg=..., long_leg=..., credit=..., n_contracts=...).accepted:
        return EntryCycleResult(status="no_entry", reason="illiquid")

    proposal = build(short=short, long_=long_, n_contracts=..., spot=spot, ...)

    # 3. Persistenza + auto-execute
    repo.create_position(proposal, status="proposed")
    order = await deribit.place_combo_order(legs=[short, long_], side="sell", ...)

    if order.state in {"filled", "open"}:
        repo.update_position_status(proposal_id, status="open" if filled else "awaiting_fill")
        repo.create_instruction(InstructionRecord(...))
        await telegram.notify_position_opened(...)
        audit.append("ENTRY_PLACED", {...})
    else:
        repo.update_position_status(proposal_id, status="cancelled")
        await alert_manager.high(source="entry_cycle", message="broker_reject")
```

## Sequenza tipo per "monitoring 12h"

```python
async def run_monitor_cycle(ctx: RuntimeContext, *, now):
    if ctx.kill_switch.is_armed():
        return MonitorCycleResult(outcomes=[])

    spot = await deribit.index_price_eth()
    dvol = await deribit.latest_dvol(currency="ETH", now=now)
    return_4h = await _fetch_return_4h(ctx, now=now)  # usa dvol_history o
                                                     # fallback get_historical
    repo.record_dvol_snapshot(DvolSnapshot(timestamp=now, dvol=dvol, eth_spot=spot))

    for record in repo.list_positions(status="open"):
        snapshot = await _build_position_snapshot(...)
        decision = evaluate(snapshot, cfg)
        if decision.action == "HOLD":
            audit.append("HOLD", {...}); continue

        repo.update_position_status(record.proposal_id, status="closing")
        order = await deribit.place_combo_order(
            legs=[short_buy, long_sell], side="buy", ...
        )
        if order.state in {"filled", "open"}:
            repo.update_position_status(record.proposal_id, status="closed", ...)
            audit.append("EXIT_FILLED", {...})
            await telegram.notify_position_closed(...)
        else:
            repo.update_position_status(record.proposal_id, status="open")
            await alert_manager.critical(source="monitor_cycle", ...)
```

## Failure modes e retry

| Modalità | Risposta |
|---|---|
| MCP non risponde (timeout) | Retry esponenziale 3 tentativi (1 s, 5 s, 30 s); poi `McpTimeoutError` propagato e tradotto in alert HIGH dal modulo che ha originato la chiamata |
| MCP risponde con dato palesemente rotto (es. `mark_iv == 7%`) | Wrapper solleva `McpDataAnomalyError`; alert HIGH e ciclo saltato |
| Stato SQLite corrotto al boot | Recovery riconcilia con il broker; se non possibile arma kill switch CRITICAL |
| Mismatch testnet/mainnet rispetto a `strategy.execution.environment` | Kill switch CRITICAL al boot, prima di qualsiasi ciclo trading |
| Mismatch hash anchor tra `system_state.last_audit_hash` e tail del file `audit.log` | Kill switch CRITICAL al boot (truncation o tampering del log) |
| `place_combo_order` respinto dal broker | Posizione marcata `cancelled`, alert HIGH; in monitor la posizione torna a `open` per ritentare al ciclo successivo |
| Lock file occupato | Boot fallisce con `LockError`, exit immediato (un'altra istanza è già attiva) |

Vedi `07-risk-controls.md` per il dettaglio completo dei kill switch.

## Concorrenza e idempotenza

- Una sola istanza dell'engine alla volta (`fcntl.flock` esclusivo su
  `data/.lockfile`).
- Lo scheduler è in-process e i job sono coalesce + misfire grace
  300 s, quindi un riavvio del container non duplica l'ultimo
  trigger perso.
- Tutti i ticker dello scheduler sono **idempotenti**: se il sistema
  crasha durante un'apertura, al riavvio il `recover_state` ricostruisce
  lo stato confrontando SQLite con `deribit.get_positions()` e prosegue.
- Ogni proposta ha un `proposal_id` UUID; il `label` inviato a Deribit
  contiene questo id, così posso correlare gli ordini sul broker con
  la riga `positions` in caso di indagine forense.

## Lifecycle del container

1. `docker compose up cerbero-bite` → `cerbero-bite start` con
   `enforce_hash=True` su `strategy.yaml`.
2. `Orchestrator.run_forever` acquisisce `data/.lockfile`.
3. `boot()` esegue, in ordine: verifica anchor audit chain → recover
   state → environment check → primo health probe → log
   `ENGINE_START`.
4. Lo scheduler arma i 4 job documentati (entry, monitor, health,
   backup).
5. `asyncio.Event` blocca il main task fino a SIGTERM/SIGINT.
6. Alla ricezione del segnale: `scheduler.shutdown(wait=False)` →
   `RuntimeContext.aclose()` (chiude `httpx.AsyncClient` condiviso) →
   uscita pulita; il lock file viene rilasciato dal context manager.
7. Il container Docker, in modalità `restart: unless-stopped`,
   resta down se l'engine ha ricevuto SIGTERM dal compose `stop`;
   riparte automaticamente solo se il processo è morto per crash.