🌊 System Data Routing Spec

Hoox operates as a highly orchestrated distributed event loop. Because execution logic is split into isolated compute nodes, data flows recursively through multiple V8 transitions, asynchronous queues, time-series datasets, and database ledgers.

This document provides complete, low-level technical specifications and Mermaid sequence diagrams for our four primary data routing pipelines: Webhook Trade execution, AI Risk management, PDF browser rendering, and Observability tracking.

1. Webhook to Trade Execution Flow (High-Speed Path)

This is the primary transaction pipeline. When a trade signal is received, the system validates the payload, locks the trace ID, executes the order at the edge closest to the exchange, records the fill, and alerts the user.

sequenceDiagram
    autonumber
    actor TV as Signal Source (TradingView)
    participant GW as hoox Gateway
    participant DO as IdempotencyStore (Durable Object)
    participant TW as trade-worker
    participant D1 as d1-worker
    participant TG as telegram-worker
    participant AE as analytics-worker

    TV->>GW: POST /webhook (Ingest raw JSON signal)
    Note over GW: Extract Trace ID & check KV Rate Limiter
    GW->>DO: lockTransaction(traceId) (SQLite atomic mutex check)
    alt Mutex Lock Denied (Trace ID Already Logged)
        DO-->>GW: Fail (Conflict: Duplicate Request)
        GW-->>TV: 409 Conflict (Duplicate Request)
    else Mutex Lock Granted (Unique Request)
        DO->>GW: Lock Acquired (Success)
        GW->>TW: Service Binding invoke: POST /webhook (X-Internal-Auth-Key)
        Note over TW: Fetch encrypted Secrets & calculate HMAC-SHA256 signature
        TW->>D1: Service Binding invoke: POST /query (Write "TRADE_PENDING" row)
        TW->>TW: Send Order to Centralized Exchange API
        Note over TW: Exchange fills order & returns status details
        TW->>D1: Service Binding invoke: POST /query (Update Status to "Filled")
        TW->>TG: Service Binding invoke: POST /alert (Format alert template)
        TG-->>TV: Dispatch Telegram Push Alert to User's phone
        TW-->>GW: Return Executed Order JSON
        GW->>AE: Service Binding invoke: POST /track (Log latency & status metrics)
        GW-->>TV: 200 OK (Filled order metadata)
    end

2. Autonomous AI Risk Monitoring Flow (Cron Cycle)

Running on a strict 5-minute Cron schedule, the risk management loop queries SQLite records, audits active exposures, calculates trailing stop deviations, and manages emergency halts.

sequenceDiagram
    autonumber
    participant Cron as Cloudflare Cron Trigger
    participant AW as agent-worker (AI Risk Manager)
    participant D1 as d1-worker (SQL Hub)
    participant TW as trade-worker (Execution)
    participant TG as telegram-worker (Alerts)

    Cron->>AW: Fire trigger: */5 * * * *
    AW->>D1: Service Binding invoke: POST /query (Get open margin positions)
    D1-->>AW: Return position matrices (Average price, leverage, unrealized P&L)
    Note over AW: Evaluate Max Daily Drawdown threshold against balance
    alt Drawdown Limit Hit (USDT Daily loss > max_daily_drawdown_percent)
        Note over AW: EMERGENCY HALT TRIGGERED 🚨
        AW->>AW: Set trade:kill_switch = true in CONFIG_KV
        AW->>TW: Service Binding invoke: POST /close-all (Flatten all active exposure)
        TW-->>AW: All positions flattened successfully
        AW->>TG: Service Binding invoke: POST /alert (Dispatch Emergency Alert)
        TG-->>AW: User notified on phone
    else Normal Operation (Within Safe Margins)
        Note over AW: Calculate Trailing Stop-Loss price deviations
        alt Deviation Triggered (Price crossed dynamic stop-loss boundary)
            AW->>TW: Service Binding invoke: POST /order (Close target position)
            TW-->>AW: Order filled
            AW->>TG: Service Binding invoke: POST /alert (Stop-Loss Triggered Notification)
        end
    end

3. PDF Portfolio Report Rendering Flow

Runs twice daily to automate HTML dashboard rendering, compile PDFs via Puppeteer on the edge, offload to R2 storage, and dispatch download corridors.

sequenceDiagram
    autonumber
    participant Cron as Cloudflare Cron Trigger
    participant RP as report-worker
    participant BR as Browser Rendering API (Chrome Isolate)
    participant R2 as R2 Object Storage Bucket
    participant TG as telegram-worker

    Cron->>RP: Fire trigger: 06:00 & 18:00 UTC
    RP->>RP: Query D1 P&L history & compile HTML5 template
    RP->>BR: POST /browser-rendering/pdf (HTML string payload)
    Note over BR: Spin up headless Puppeteer Chrome & render viewport
    BR-->>RP: Return compiled PDF Buffer stream
    RP->>R2: PutObject: reports/daily-report-{timestamp}.pdf
    RP->>TG: Service Binding invoke: POST /alert (P&L report link)
    TG-->>RP: Dispatch report download link to user

4. Observability & Time-Series Analytics Flow

To maintain complete cross-worker telemetry without blocking critical order threads, Hoox routes analytics data points asynchronously to a dedicated metrics warehouse.

sequenceDiagram
    autonumber
    participant W as Any Compute Worker (hoox, trade, agent, etc.)
    participant AN as analytics-worker (SQL Analytics Ingest)
    participant AE as Cloudflare Analytics Engine

    W->>AN: Service Binding invoke: POST /track/api-call (Trace ID, latencyMs, success)
    Note over AN: Sanitize metrics inputs & format structural time-series logs
    AN->>AE: writeDataPoint({ blobs: [worker, endpoint], doubles: [latencyMs] })
    Note over AE: Persistent logging in time-series warehouse for Next.js dashboard

💾 5. Global Data Persistence Mapping

🔗 Next Steps

• Bindings Catalog — Check wrangler settings and resource declarations.
• Storage Engineering Manual — Dive into Drizzle database schemas and SQLite properties.