> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# hoox Gateway Isolate Profile

> Comprehensive engineering specification for the Hoox public gateway, covering ingress WAF rules, Durable Object idempotency stores, and Service Binding configurations.

The **`hoox`** gateway is the public-facing entry point of the trading ecosystem. Running as an ultra-low-latency Cloudflare Worker, the gateway is responsible for authorizing incoming trade signals (TradingView alerts, email routing, manual commands), executing rate-limiting checks, locking transaction trace IDs via Durable Objects to prevent duplicate fills, and routing validated events privately to background compute nodes.

***

## 🏗️ Architectural Topology

```mermaid theme={null}
graph TD
    Alert["🔔 External Webhook"] -->|Signal| WAF["🧱 Cloudflare WAF / Firewall"]
    WAF -->|IP & Auth Checks| Gateway["🔐 Gateway: hoox<br/>Public Isolate"]
    Gateway -->|V8 Service Bindings<br/>Private, Encrypted, Zero-TCP| Compute["Background Nodes"]

    subgraph Compute ["Background Compute Isolates"]
        Trade["📈 trade-worker"]
        Tele["💬 telegram-worker"]
        Anal["📊 analytics-worker"]
    end

    style Alert fill:#CCCCCC,stroke:#3b82f6,stroke-width:2
    style WAF fill:#CCCCCC,stroke:#f59e0b,stroke-width:2
    style Gateway fill:#CCCCCC,stroke:#ef4444,stroke-width:2
    style Trade fill:#CCCCCC,stroke:#10b981,stroke-width:1
    style Tele fill:#CCCCCC,stroke:#10b981,stroke-width:1
    style Anal fill:#CCCCCC,stroke:#10b981,stroke-width:1
```

***

## ⚡ 1. Declared Wrangler Configurations & Bindings

The gateway's `wrangler.jsonc` defines its private service binding links and resource bounds:

```jsonc theme={null}
{
  "name": "hoox",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-19",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "placement": {
    "mode": "smart",
  },
  "vars": {
    "ENVIRONMENT": "production",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
    {
      "binding": "SESSIONS_KV",
      "id": "ff70a58b492e45d79880a7a8213c745c",
    },
  ],
  "services": [
    { "binding": "TRADE_SERVICE", "service": "trade-worker" },
    { "binding": "TELEGRAM_SERVICE", "service": "telegram-worker" },
  ],
  "queues": {
    "producers": [{ "queue": "trade-execution", "binding": "TRADE_QUEUE" }],
  },
  "durable_objects": {
    "bindings": [
      { "name": "IDEMPOTENCY_STORE", "class_name": "IdempotencyStore" },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["IdempotencyStore"],
    },
  ],
}
```

***

## 🔑 2. Environmental Variables & Encrypted Secrets

For security, build-time credentials are never stored in plain text. They are bound at deploy time as encrypted secrets:

* **`WEBHOOK_API_KEY`**: The custom authentication passkey expected inside incoming signal payloads.
* **`INTERNAL_KEY_BINDING`**: The shared bearer authorization token used by `requireInternalAuth` middleware to invoke internal V8 isolates.

### Local Development Mocking (`.dev.vars`)

When running tests or starting local Wrangler dev, create a gitignored `.dev.vars` file in the gateway directory:

```bash theme={null}
WEBHOOK_API_KEY=dev_webhook_auth_passkey
INTERNAL_KEY_BINDING=dev_shared_internal_security_key
```

***

## 🛜 3. API Route Specifications

> **Note:** For the canonical endpoint directory with full request/response examples across all workers, see [`/docs/devops/api/endpoints`](../api/endpoints).

The gateway exposes three public entryways:

### A. Ingest Signal Webhook

* **Endpoint**: `/webhook`
* **Method**: `POST`
* **JSON Payload**:
  ```json theme={null}
  {
    "apiKey": "dev_webhook_auth_passkey",
    "exchange": "bybit",
    "action": "LONG",
    "symbol": "BTCUSDT",
    "quantity": 0.01,
    "leverage": 10,
    "idempotencyKey": "uuid-9b1deb4d-3b7d"
  }
  ```
* **Success Response (200 OK)**:
  ```json theme={null}
  {
    "success": true,
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "exchange": "bybit",
    "symbol": "BTCUSDT",
    "action": "LONG",
    "result": { "orderId": "18049284739", "status": "Filled" }
  }
  ```

***

### B. Gateway Health Diagnostics

* **Endpoint**: `/health`
* **Method**: `GET`
* **Success Response (200 OK)**:
  ```json theme={null}
  {
    "status": "ok",
    "timestamp": 1779261050000,
    "bindings": {
      "d1": "connected",
      "kv": "connected",
      "queue": "active"
    }
  }
  ```

***

<Tip>
  If exchange APIs experience high latency or go offline, the gateway intercepts
  the timeout error, serializes the payload, and pushes it to the `TRADE_QUEUE`
  producer in less than **2 milliseconds**, returning a `"status": "Enqueued"`
  (202 Accepted) response to TradingView.
</Tip>

### 🔗 Next Steps

* **[trade-worker Spec](trade-worker)** — Review how trade executions, order math, and margin settings compile on the edge.
* **[D1 Database Operations](../../enduser/guides/database-ops)** — Manage schema migrations, query ledgers, and execute SQL scripts.