Hoox — Edge-Native Algorithmic Trading on the Cloudflare Edge

Hoox provides a comprehensive local development workspace designed to emulate your production Cloudflare edge environment. Developers can choose between running microservices natively on local Wrangler V8 isolates or inside completely isolated, containerized Docker stacks, with real-time log tailing and TUI diagnostics.

⚡ 1. Dev Runtime Selection: Native vs. Docker

The hoox dev start command orchestrates the boot sequence for all enabled workers and supports two execution runtimes:

Runtime Mode	Boot Command	Latency / Hot-Reload	Isolation Level	Ideal Use Case
Native	`wrangler dev`	< 10ms	Low (shares local host ports)	High-speed script tweaking, rapid feature iterations.
Docker	`docker compose up`	~100ms	High (isolated Linux containers)	Testing full integrations, database migrations, queue failovers.

The Guided Startup Flow

When you run hoox dev start:

Wrangler Version Verification: Probes your global/local Wrangler package. If Wrangler is outdated, it prompts an advisory upgrade warning. The warning shows the current vs minimum version and offers a one-line update command.
Docker Environment Probing: Checks if the Docker daemon is active and docker-compose.yml is present in the workspace.
Runtime Preference Lock: If both runtimes are available, the CLI prompts you to select your preference. This choice is written to your wrangler.jsonc file under the dev runtime block, bypassing future prompts.

# Override the saved runtime preference on the fly
hoox dev start --runtime native
hoox dev start --runtime docker

🐳 2. Docker Compose Orchestration & Profiles

For full stack containerized development, Hoox divides operations into three Docker Compose profiles in your root docker-compose.yml:

# Profile 1: All background workers (9 services — no dashboard UI)
docker compose --profile workers up

# Profile 2: Dashboard + its transitive worker dependencies (5 services:
#           hoox, d1-worker, trade-worker, agent-worker, dashboard).
#           trade-worker is pulled in because agent-worker depends on it.
docker compose --profile dashboard up

# Profile 3: Full Stack — all 10 services
docker compose --profile full up

Only hoox (8787) and dashboard (8794) are published to the host. The remaining workers are reachable only via service bindings on the hoox-net bridge network — the same topology as production Cloudflare Workers Service Bindings.

📍 3. Local Port Mapping Registry

In the local environment, each V8 dev instance mounts to a dedicated host port. Ensure no other applications are occupying these ports before launching:

Microservice	Default Port	Local Binding URL	Purpose
`hoox`	`8787`	`http://localhost:8787`	Ingress Gateway
`trade-worker`	`8789`	`http://localhost:8789`	Order Execution Engine
`telegram-worker`	`8791`	`http://localhost:8791`	Notifications Hub
`d1-worker`	`8792`	`http://localhost:8792`	Relational SQLite Manager
`web3-wallet`	`8793`	`http://localhost:8793`	On-Chain DeFi Node
`dashboard`	`8794`	`http://localhost:8794`	Next.js Dashboard SSR
`agent-worker`	`8795`	`http://localhost:8795`	Cron Risk Monitor
`email-worker`	`8796`	`http://localhost:8796`	Email Signal Parser
`report-worker`	`8797`	`http://localhost:8797`	PDF Portfolio Generator
`analytics-worker`	`8798`	`http://localhost:8798`	Analytics & Reporting

🛡️ 4. Local Environmental Mocking (`.dev.vars`)

Because production secrets are locked inside Cloudflare’s secured key vaults, Wrangler dev uses local .dev.vars files located inside each worker’s directory to mock API keys and credentials:

# 1. Copy the secure template
cp workers/hoox/.dev.vars.example workers/hoox/.dev.vars

# 2. Inject local mock keys for testing
echo 'INTERNAL_KEY_BINDING="local_test_key"' >> workers/hoox/.dev.vars

.dev.vars files contain local plaintext keys and are excluded from git index tracking via .gitignore. Never remove these files from .gitignore or check them into your repository.

If local tests fail with Time-Stamp Expired errors when calling exchange APIs, check that your local machine’s NTP system clock is synchronized: sudo ntpdate pool.ntp.org (or check date/time settings on macOS/Windows)!

🏃 5. Shell Helpers: Running Commands Across All Workers

The scripts/helpers.sh file provides a wx() function that runs any CLI command in every worker directory — useful for bulk operations like regenerating types, running typecheck, or installing dependencies.

Installation

# One-time install (adds to ~/.zshrc or ~/.bashrc)
bash scripts/install.sh

# Or source it manually in your current session
source scripts/helpers.sh

Usage

# Regenerate Wrangler types in every worker
wx "wrangler types"

# Run typecheck across all workers
wx "pnpm run typecheck"

# Inspect package names
wx "cat package.json | jq .name"

# List source files per worker
wx "ls -la src/"

Filtering

Use WX_FILTER to target specific workers by glob pattern:

# Only wrangler-based workers (excludes dashboard, hoox)
WX_FILTER='*-worker' wx "wrangler types"

# Single worker
WX_FILTER='trade-worker' wx "pnpm run typecheck"

Custom Path

Set WX_WORKERS_DIR if your workers live elsewhere:

WX_WORKERS_DIR=~/other-project/workers wx "some command"

🕸️ 6. Codebase Dependency Graph

Hoox includes a function-level dependency graph extractor that maps all exported symbols, imports, calls, type references, and service bindings across the entire monorepo.

# Regenerate graph.json and graph.dot
bun run graph

This runs scripts/extract-graph.ts (ts-morph) and scans 917 source files across all 14 workspaces. During extraction, a live progress bar shows each phase with elapsed time:

🔍 Extracting exported declarations...
  [██░░░░░░░░░░░░░░░░░░] 13%  exports: 1667 nodes             10.6s
🔍 Extracting import relationships...
  [█████░░░░░░░░░░░░░░░] 25%  imports: 2524 edges              0.1s
🔍 Extracting type references...
  [██████████░░░░░░░░░░] 50%  type refs: 2536 edges            1.7s
🔍 Extracting cross-file call expressions...
  [████████████░░░░░░░░] 63%  calls: 445 edges                 9.7s
  [████████████████████] 100% Done                             22.0s

⏱  Total time: 22.0s

The 8 extraction phases (exports → imports → extends/implements → type refs → calls → service bindings → workspace deps → filtering) complete in ~20–25s on average.

Outputs

File	Contents
`graph-metadata.json`	Human-authored worker/infra semantics (tracked in git)
`graph.json`	Full machine-readable graph — generated, not committed
`graph.dot`	Graphviz DOT — generated, not committed (`bun run graph`)

Quick Render

# Install Graphviz if missing
# macOS: brew install graphviz
# Ubuntu: sudo apt install graphviz

# Render to SVG
dot -Tsvg graph.dot -o graph.svg && open graph.svg

Use graph.json as AI/LLM context for codebase-aware queries, or paste graph.dot into Edotor for instant browser visualization without installing Graphviz.

🔗 Next Steps

Testing Standards — Run unit and integration tests using Bun’s native test runner.
Debugging Runbook — Debug local and remote isolates, tail logs, and trace queries.

DevOps

Local Development Setup

⚡ 1. Dev Runtime Selection: Native vs. Docker

The Guided Startup Flow

🐳 2. Docker Compose Orchestration & Profiles

📍 3. Local Port Mapping Registry

🛡️ 4. Local Environmental Mocking (`.dev.vars`)

🏃 5. Shell Helpers: Running Commands Across All Workers

Installation

Usage

Filtering

Custom Path

🕸️ 6. Codebase Dependency Graph

Outputs

Quick Render

🔗 Next Steps

​⚡ 1. Dev Runtime Selection: Native vs. Docker

​The Guided Startup Flow

​🐳 2. Docker Compose Orchestration & Profiles

​📍 3. Local Port Mapping Registry

​🛡️ 4. Local Environmental Mocking (.dev.vars)

​🏃 5. Shell Helpers: Running Commands Across All Workers

​Installation

​Usage

​Filtering

​Custom Path

​🕸️ 6. Codebase Dependency Graph

​Outputs

​Quick Render

​🔗 Next Steps

⚡ 1. Dev Runtime Selection: Native vs. Docker

The Guided Startup Flow

🐳 2. Docker Compose Orchestration & Profiles

📍 3. Local Port Mapping Registry

🛡️ 4. Local Environmental Mocking (`.dev.vars`)

🏃 5. Shell Helpers: Running Commands Across All Workers

Installation

Usage

Filtering

Custom Path

🕸️ 6. Codebase Dependency Graph

Outputs

Quick Render

🔗 Next Steps