docs/ARCHITECTURE.md

# Architecture

## System context

```mermaid
flowchart LR
    U[Authenticated browser] -->|same-origin HTTPS| H[Hermes dashboard / FastAPI :7860]
    T[Telegram webhook] --> H
    H --> R[Futures dashboard router]
    R --> C[Deterministic trade cycle]
    R --> S[Dashboard state]
    C --> D[Dual datasource client]
    D --> DS4[Datasource 4\nAuthoritative]
    D --> B[Binance public\nFallback]
    D --> DS2[Datasource 2\nComplementary]
    C --> K[Risk / sizing]
    C --> E[Paper execution]
    C -. optional context only .-> A[Hermes auxiliary\nfutures_advisory task]
```

## Container and filesystem architecture

```mermaid
flowchart TD
    I[Docker image] --> O1[/opt/hermesface_overlay\nimmutable current-image overlay]
    I --> O2[/opt/data/hermes_overlay\npersisted/restored copy]
    I --> S[/opt/data/scripts]
    B[scripts/entrypoint.sh] --> Y[scripts/sync_hf.py]
    Y -->|prefer| O1
    Y -->|fallback only| O2
    Y -->|copy modules| H[/opt/hermes]
    Y --> M[overlay manifest]
    Y --> P[patch existing dashboard router]
    P --> W[Hermes dashboard :7860]
```

The immutable `/opt/hermesface_overlay` is preferred so a restored dataset containing an older overlay cannot downgrade the current image.

## Layer responsibilities

### HTTP and UI layer

`futures_dashboard_api.py` owns request validation, authentication dependency, response shaping, runtime diagnostics, and browser-facing error semantics. It does not implement signal scoring or sizing.

### Datasource layer

`dual_datasource_client.py` owns:

- HTTP acquisition;
- KuCoin-compatible time range construction;
- nested payload discovery;
- field normalization;
- source priority;
- field provenance;
- source health metadata;
- `noTradeGuard`, missing-field, stale-field, merge, and readiness results.

### Decision layer

`trade_cycle.py` owns deterministic score calculation, decision thresholds, SL/TP construction, risk module orchestration, plan expiry, and optional execution handoff.

### Risk layer

`risk.py` owns risk profile lookup, leverage caps, volatility haircut, quantity calculation, margin/notional gates, daily-loss and position-count gates.

### Execution layer

`futures_execution.py` owns Paper mode, account/position state, exchange adapter boundaries, slippage estimation, and protective order behavior. The dashboard route never directly constructs an exchange order.

### State layer

`state.py` stores only a bounded view of the latest context/plan for the dashboard. It removes raw exchange payloads and does not authorize any decision.

## Trust boundaries

| Boundary | Trusted for decisions? | Notes |
|---|---|---|
| Browser controls and localStorage | No | Convenience only; server revalidates everything. |
| Datasource 4 | Yes, for verification/safety | Still subject to parsing, freshness, and completeness checks. |
| Binance public | No, as authority | Field fallback only; cannot clear DS4 guard. |
| Datasource 2 | No, as authority | Complementary context only. |
| External AI (Hermes auxiliary) | No | Optional `futures_advisory` task output only; never alters decisions. |
| Telegram input | No | Authorized, rate-limited, analysis-only commands. |
| Server-side latest plan | Partially | Must still pass freshness and execution revalidation. |

## Router installation

`sync_hf.py` patches the existing Hermes dashboard application (Option A — preserve URLs) to include:

```python
from tools.futures_dashboard_api import router as _futures_dashboard_router
app.include_router(_futures_dashboard_router)
from tools.telegram_bot import router as _telegram_router
app.include_router(_telegram_router)
```

The patch is idempotent and must not create a new FastAPI app. Tool registration does **not** use a `toolsets.py` patch; read-only Futures tools and the `futures_advisory` auxiliary task are registered via `$HERMES_HOME/plugins/futures_trading/`.

## Advisory layer

Optional market context is requested only when the dashboard or analyze call sets `include_external_context=true`. The flow is:

1. `trade_cycle.run_futures_cycle(..., include_external_context=True)` calls `external_ai.advisory.get_advisory(snapshot)`.
2. `get_advisory` invokes Hermes `agent.auxiliary_client.async_call_llm` with task **`futures_advisory`** (registered by the futures_trading plugin).
3. The response is parsed against `external_ai/advisory_schema.py` and attached as `external_advisory` on the plan.
4. Advisory outcomes may be logged durably via `advisory_outcomes_repo` hooks on plan/position events.

Advisory output cannot modify decision, risk approval, geometry, or execution eligibility. See [Security and Safety](SECURITY_AND_SAFETY.md).

## Persistence

Hermes data under `/opt/data` may be synchronized to a private Hugging Face Dataset. The repository overlay is also copied into the image, but the immutable image overlay is the source used for installation. Runtime state such as Telegram owner data and symbol cache lives under `/opt/data` and must not be committed.

## Failure behavior

- DS4 unreachable: merge may use fallback data for display, but Futures verification/readiness remains blocked.
- Binance HTTP 451: source status is restricted/unavailable; no bypass is attempted.
- DS2 unavailable: complementary context is degraded; it does not independently block a plan unless it was the only attempted fill for a still-missing field.
- Market endpoint exception: HTTP 503 with structured `API_UNAVAILABLE` payload.
- Analysis exception: HTTP 503, state becomes `ANALYSIS_FAILED`, previous plan is cleared from current state.
- Template read failure: minimal fallback page is served and trading remains blocked.