[System Topology & Overview]

Hoox is an enterprise-grade, serverless algorithmic trading platform built entirely on Cloudflare® Edge V8 isolates and globally distributed resources. By using a modular, service-oriented architecture, Hoox decomposes complex trading processes into 11 compute surfaces: gateway, trade, agent, dashboard (Next.js), telegram, d1, web3, email, analytics, report, and pyne (Python Pine Script™ edge evaluate).

Most workers communicate privately via Service Bindings in microseconds, auto-scale globally near exchange servers, and store transaction logs in localized databases—all while running within Cloudflare® free tiers. pyne-worker is a tooling isolate: public evaluate/management routes use API_KEY auth (not mesh INTERNAL_KEY_BINDING); live strategy forwards to trade-worker use mesh internal auth.

---

🗺️ High-Level System Architecture

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

Rendering…

---

📊 Comprehensive Micro-Worker Catalog

Public tooling vs mesh-private workers: Mesh workers (trade-worker, d1-worker, agent-worker, etc.) expose no public HTTP and require INTERNAL_KEY_BINDING / X-Internal-Auth-Key on service-to-service calls. pyne-worker is a tooling isolate: its evaluate and management APIs use API_KEY, not mesh INTERNAL_KEY on public routes. When pyne forwards strategy events to trade-worker, that hop uses mesh internal auth.

---

🛡️ 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) expose zero public HTTP endpoints. They cannot be targeted or accessed from the public internet. They can only be invoked internally by other V8 isolates using Cloudflare Service Bindings.

---

Layer 4: Standardized Internal Authorization

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

• All internal workers (hoox, trade-worker, d1-worker, agent-worker, telegram-worker) are bound to the same INTERNAL_KEY_BINDING secret.
• Every service-to-service invocation is audited by the shared requireInternalAuth middleware from @hoox-sh/hoox-shared/middleware, dropping unauthorized calls.

---

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 to lock the request trace ID. If the transaction ID has already been logged, the duplicate is dropped before hitting exchange APIs, preventing double-ordering.

---

---

📊 Codebase Dependency Graph

Hoox ships with an automated function-level dependency graph extractor that maps every exported symbol, import, call, type reference, and service binding across all 917 source files and 14 workspaces.

Generating the Graph

# From repository root
bun run graph

This runs scripts/extract-graph.ts (powered by ts-morph) and scans 917 source files across all 14 workspaces in ~20–25s.

During extraction, an 8-phase live progress bar reports each stage with timing:

  [██░░░░░░░░░░░░░░░░░░] 13%  exports: 1667 nodes             10.6s
  [██████████░░░░░░░░░░] 50%  type refs: 2536 edges            1.7s
  [████████████░░░░░░░░] 63%  calls: 445 edges                 9.7s
  [████████████████████] 100% Done                             22.0s

⏱  Total time: 22.0s

Node Types & Color Coding (DOT)

Entry points (top-level workspace exports) are highlighted with double borders.

Edge Color Legend

Rendering to SVG

# Requires Graphviz installed
dot -Tsvg graph.dot -o graph.svg

# Or paste graph.dot into edotor.net / viz-js.com

Key Extraction Rules

• Export-only nodes: Only exported symbols appear in the graph (684 unexported symbols filtered out).
• Call edge fallback: Method calls like router.post resolve via TypeChecker; when the symbol name (post) doesn't match a top-level export, the edge falls back to the target file's first container node.
• Self-reference filtering: Calls within the same file are excluded.
• Deduplication: Duplicate edges are collapsed into a single entry.
• Service bindings: Parsed from each worker's wrangler.jsonc configuration.

---

🔗 Next Steps

• Worker Communication Specifications — Deep dive into service bindings, zero-TCP routing, and V8 engines.
• Data Flow Maps — Step-by-step sequence charts of trade executions and cron risk evaluations.
• Codebase Dependency Graph — Generate a live architecture map of all exports, calls, and bindings.

Enterprise / Institutional Scale

For the full bleeding-edge Enterprise architecture (Workers for Platforms multi-tenancy, Workflows, Logpush audit, AI Gateway, Bot Management, etc.) — the commercial layer on top of the open core — see:

• docs/enterprise/architecture.mdx
• docs/enterprise/multi-tenancy.mdx
• docs/enterprise/observability-audit.mdx
• docs/enterprise/security-compliance.mdx

See also root OPEN_CORE.md and OPEN_CORE_FEATURE_SPLIT.md.

These build directly on the current retail architecture while unlocking Cloudflare Enterprise features and 2025-2026 primitives.