System Topology & Overview

Hoox is a serverless algorithmic trading platform on Cloudflare® Workers. Version 0.16.0 splits the system into 11 compute surfaces: 10 workers under workers/* plus the dashboard (Next.js 16 / OpenNext). pyne-worker is Python; the rest are TypeScript V8 isolates.

Most workers talk over Service Bindings (no public HTTP). Public ingress is the hoox gateway (POST /webhook, GET /health, operator /v1/* and /wallet/*) and the dashboard. pyne-worker is a tooling isolate: public evaluate/management routes use API_KEY (X-API-Key); live strategy forwards to trade-worker use mesh internal auth.

Spot execution covers CEX (Binance, Bybit, MEXC) and spot DEX (uniswap-ethereum, uniswap-arbitrum via Uniswap V3 SwapRouter02, jupiter-solana via Jupiter Swap V2). DEX orders leave trade-worker as WEB3_WALLET_SERVICE POST /swap. Perps are not supported.

Opt-in tenant isolation (TenantEnv: TENANT_MODE + TENANT_ID) shipped in 0.14 and is off by default. Entitlement scope types exist in @hoox-sh/hoox-shared; they are classification helpers only — not live enforcement.

🗺️ High-Level System Architecture

The ecosystem splits public-facing ingress points from private internal compute layers:

📊 Comprehensive Micro-Worker Catalog

Public vs mesh-private: Mesh workers (trade-worker, d1-worker, agent-worker, web3-wallet-worker, …) expose no public HTTP. Service-to-service calls send X-Internal-Auth-Key. The hoox gateway is public for webhooks and health; operator Bearer (OPERATOR_API_KEY) gates /v1/* and /wallet/*. pyne-worker public routes use API_KEY, not mesh INTERNAL_KEY. When pyne forwards strategy events to trade-worker, that hop uses mesh internal auth.

Smart Placement (placement.mode: "smart") is on every isolate except the dashboard, which stays close to operators rather than backend services.

🛡️ The 5-Layer Security Architecture

Security is designed as concentric protective corridors:

[ WAF: IP Range Allow-list ] -> [ Gateway: Webhook Passkey ] -> [ Isolation: Service Bindings ] -> [ Worker Auth: INTERNAL_KEY ] -> [ Mutex: Durable Objects ]

Layer 1: Edge-Level Firewall & WAF

Cloudflare® global WAF drops connections immediately at the edge if:

• The payload does not originate from verified TradingView® webhook IP ranges.
• The request rate exceeds threshold ceilings (10 requests/minute).

Layer 2: Webhook Passkey Authentication

The hoox gateway validates that the payload apiKey string exactly matches the encrypted webhooks:api_key stored inside your CONFIG_KV namespace. Mismatched signals are instantly dropped with a 401 Unauthorized response.

Layer 3: Service Binding Encrypted Isolation

Internal workers (trade-worker, d1-worker, agent-worker, web3-wallet-worker, …) expose zero public HTTP endpoints. Reach them only through Service Bindings. The gateway’s /wallet/* proxy is the operator-facing path onto the wallet isolate — it still injects mesh auth on the binding hop.

Layer 4: Standardized Internal Authorization

To prevent internal bypass or privilege escalation, all internal microservice boundaries enforce a strict bearer authorization check:

• Mesh workers bind INTERNAL_KEY_BINDING. Scoped aliases (WALLET_EXECUTE_KEY_BINDING, TRADE_EXECUTE_KEY_BINDING, D1_READ_KEY_BINDING / D1_WRITE_KEY_BINDING) are preferred when set and fall back to the shared key.
• Service-to-service calls go through requireInternalAuth / authenticatedServiceFetch from @hoox-sh/hoox-shared. Unauthorized calls are dropped.

Layer 5: Durable Object Idempotency Locks

If the network drops after an order fill, TradingView® will resend the webhook. The gateway uses a single-threaded Durable Object (IdempotencyStore) in two phases: reserve (pending) before dispatch, commit on true success, release on soft-fail. Duplicates and in-flight keys return 409. Missing DO binding is fail-closed (503).

Opt-in tenant isolation

Set TENANT_MODE to true or 1 and a valid TENANT_ID ([A-Za-z0-9_-]{1,64}) to namespace KV/DO keys (t/<id>/…), R2 keys (t-<id>/…), and D1 tenant_id rows. TENANT_ID alone does nothing. Self-host installs leave both unset.

Entitlement scope types (EntitlementScope, hasScope()) in @hoox-sh/hoox-shared classify bearers. They do not enforce product entitlements on the request path.

Bindings graph (local)

bun run graph at the repo root extracts Service Bindings from each worker’s wrangler.jsonc into generated graph.json / graph.dot (not committed). Use it to inspect the mesh locally; do not treat generated node counts as product docs.

Next Steps

• Worker Communication Specifications — Service Bindings and internal auth.
• Data Flow Maps — Webhook, DEX swap, wallet proxy, and cron sequences.
• Workers — Per-isolate profiles.

Enterprise overlays (Workers for Platforms, Logpush, dedicated tenancy) live under Enterprise.