docs/ARCHITECTURE.md

Architecture

System context

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 -. advisory only .-> A[External AI]

Container and filesystem architecture

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	No	Advisory explanation only.
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 modifies the existing Hermes dashboard code to include:

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.

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.