> ## 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.

# Local Development Setup

> Detailed operational guide for local development setups, covering Wrangler CLI native dev parameters, Docker Compose profiles, and local .dev.vars mocking.

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`:

<ol>
  <li>
    <strong>Wrangler Version Verification</strong>: 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.
  </li>

  <li>
    <strong>Docker Environment Probing</strong>: Checks if the Docker daemon is
    active and <code>docker-compose.yml</code> is present in the workspace.
  </li>

  <li>
    <strong>Runtime Preference Lock</strong>: If both runtimes are available,
    the CLI prompts you to select your preference. This choice is written to
    your <code>wrangler.jsonc</code> file under the dev runtime block, bypassing
    future prompts.
  </li>
</ol>

```bash theme={null}
# 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`:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Warning>
  `.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.
</Warning>

***

<Tip>
  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)!
</Tip>

***

## 🏃 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
# 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:

```text theme={null}
🔍 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

```bash theme={null}
# 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
```

<Tip>
  Use `graph.json` as AI/LLM context for codebase-aware queries, or paste
  `graph.dot` into [Edotor](https://edotor.net/) for instant browser
  visualization without installing Graphviz.
</Tip>

### 🔗 Next Steps

* [**Testing Standards**](testing) — Run unit and integration tests using Bun's native test runner.
* [**Debugging Runbook**](debugging) — Debug local and remote isolates, tail logs, and trace queries.