[Hoox Trading System — Complete Setup & Operations Guide]

Version: 2.0.0
Last Updated: 2026-05-12
Classification: Internal Operations Manual
Audience: DevOps Engineers, Senior TypeScript Developers, System Administrators

---

Table of Contents

1. System Overview
2. Pre-Flight Requirements
3. Complete Environment Matrix
4. Development Setup
5. Production Setup
6. Infrastructure Provisioning
7. Worker Deployment Sequence
8. Dashboard Setup & Deployment
9. Secret Management Reference
10. Validation & Health Checks
11. Repair & Recovery Procedures
12. Operational Runbook
13. Complete File Inventory
14. Troubleshooting Matrix

---

1. System Overview

1.1 Architecture

Hoox is an edge-deployed cryptocurrency trading system built on Cloudflare Workers. It consists of:

1.2 Communication Flow

External Webhook → hoox → [Queue] → trade-worker → D1 (via d1-worker)
                        ↓
                  telegram-worker (notifications)
                        ↓
                  analytics-worker (metrics)

agent-worker (cron) → trade-worker / d1-worker / telegram-worker
email-worker (cron) → trade-worker

1.3 Infrastructure Components

---

2. Pre-Flight Requirements

2.1 Required Accounts

2.2 Required Tools

2.3 Required Cloudflare Permissions

Your Cloudflare API Token needs these permissions:

2.4 Required Repository Access

You need access to clone with submodules:

# Main repository
git clone --recursive https://github.com/jango-blockchained/hoox-setup.git

# Or via CLI
hoox clone my-hoox-app

---

3. Complete Environment Matrix

3.1 Secret Inventory

3.2 Environment Variables by File

.env.local (Project Root)

# === CLOUDFLARE ACCOUNT ===
CLOUDFLARE_API_TOKEN="cfut_..."
CLOUDFLARE_ACCOUNT_ID="debc6545e63bea36be059cbc82d80ec8"
CLOUDFLARE_SECRET_STORE_ID="48433bc559a943f09d9d6c622e188fd5"
SUBDOMAIN_PREFIX="hoox"

# === INTERNAL AUTH KEYS ===
D1_INTERNAL_KEY="<generate-secure-random-string>"
TRADE_INTERNAL_KEY="<generate-secure-random-string>"
AGENT_INTERNAL_KEY="<generate-secure-random-string>"

# === TELEGRAM ===
TELEGRAM_BOT_TOKEN="<your-bot-token>"

# === AI PROVIDERS (optional) ===
AGENT_OPENAI_KEY="sk-..."
AGENT_ANTHROPIC_KEY="sk-ant-..."
AGENT_GOOGLE_KEY="..."

# === EXCHANGE API KEYS (optional) ===
BINANCE_API_KEY="..."
BINANCE_API_SECRET="..."
MEXC_API_KEY="..."
MEXC_API_SECRET="..."
BYBIT_API_KEY="..."
BYBIT_API_SECRET="..."

# === DASHBOARD AUTH ===
DASHBOARD_USER="admin"
DASHBOARD_PASS="<secure-password>"
SESSION_SECRET="<32-character-secure-random-string>"

workers/dashboard/.env.local (Dashboard Local Dev)

DASHBOARD_USER=admin
DASHBOARD_PASS=admin

workers/dashboard/.dev.vars (Wrangler Dev Mode)

DASHBOARD_USER=admin
DASHBOARD_PASS=admin

wrangler.jsonc (Central Configuration)

{
  "global": {
    "cloudflare_api_token": "<USE_WRANGLER_SECRET_PUT>",
    "cloudflare_account_id": "debc6545e63bea36be059cbc82d80ec8",
    "cloudflare_secret_store_id": "48433bc559a943f09d9d6c622e188fd5",
    "subdomain_prefix": "hoox",
  },
  "workers": {
    "d1-worker": {
      "enabled": true,
      "path": "workers/d1-worker",
      "vars": { "database_name": "my-database" },
    },
    "telegram-worker": {
      "enabled": true,
      "path": "workers/telegram-worker",
      "vars": {},
      "secrets": ["TELEGRAM_BOT_TOKEN"],
    },
    "trade-worker": {
      "enabled": true,
      "path": "workers/trade-worker",
      "vars": {},
      "secrets": [
        "API_SERVICE_KEY",
        "BINANCE_API_KEY",
        "BINANCE_API_SECRET",
        "MEXC_API_KEY",
        "MEXC_API_SECRET",
        "BYBIT_API_KEY",
        "BYBIT_API_SECRET",
      ],
    },
    "web3-wallet-worker": {
      "enabled": true,
      "path": "workers/web3-wallet-worker",
      "vars": {},
      "secrets": ["WALLET_MNEMONIC_SECRET", "WALLET_PK_SECRET"],
    },
    "hoox": {
      "enabled": true,
      "path": "workers/hoox",
      "vars": {},
      "secrets": ["WEBHOOK_API_KEY_BINDING"],
    },
    "agent-worker": {
      "enabled": true,
      "path": "workers/agent-worker",
      "vars": {},
      "secrets": ["AGENT_INTERNAL_KEY"],
    },
    "email-worker": {
      "enabled": true,
      "path": "workers/email-worker",
      "vars": { "USE_IMAP": "false" },
      "secrets": ["EMAIL_HOST", "EMAIL_USER", "EMAIL_PASS", "INTERNAL_KEY"],
    },
    "analytics-worker": {
      "enabled": true,
      "path": "workers/analytics-worker",
      "vars": {},
      "secrets": ["CLOUDFLARE_API_TOKEN"],
    },
  },
  "dev": {
    "runtime": "native", // "native" (wrangler) or "docker" (compose) — hoox dev start preference
  },
}

3.3 KV Configuration Keys

These keys must be set in CONFIG_KV namespace:

---

4. Development Setup

4.1 Step 1: Clone Repository

# Option A: Via CLI (Recommended)
hoox clone my-hoox-app
cd my-hoox-app

# Option B: Direct git clone
git clone --recursive https://github.com/jango-blockchained/hoox-setup.git my-hoox-app
cd my-hoox-app

# If submodules are missing
git submodule update --init --recursive

4.2 Step 2: Verify Submodules

# Check all worker directories exist
bun run check:worker-submodules

# Expected directories:
# workers/hoox
# workers/trade-worker
# workers/agent-worker
# workers/d1-worker
# workers/telegram-worker
# workers/web3-wallet-worker
# workers/email-worker
# workers/analytics-worker
# workers/report-worker

4.3 Step 3: Install Dependencies

# Install all workspace dependencies
bun install

# Verify installation
bun run lint        # ESLint check
bun run typecheck   # TypeScript check

4.4 Step 4: Configure Local Environment

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your values
# At minimum, set:
# - CLOUDFLARE_API_TOKEN
# - CLOUDFLARE_ACCOUNT_ID
# - SUBDOMAIN_PREFIX

4.5 Step 5: Authenticate Wrangler

# Login to Cloudflare
wrangler login

# Verify authentication
wrangler whoami

4.6 Step 6: Create Infrastructure (Local)

For local development, some infrastructure is optional. You need:

Required:

• D1 database (for trade data)
• KV namespace (for config)

Optional for local dev:

• R2 buckets
• Queues
• Vectorize
• Analytics Engine

# Create D1 database
wrangler d1 create trade-data-db

# Create KV namespace
wrangler kv:namespace create CONFIG_KV
wrangler kv:namespace create SESSIONS_KV

# Note the IDs and update wrangler.jsonc files

4.7 Step 7: Apply Database Schema

# Apply trade worker schema to D1
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql

# Apply tracking schema
bun run migrate:tracking

4.8 Step 8: Start Development

# Start all workers (prompts for runtime: Native or Docker)
hoox dev start

# Or force a specific runtime
hoox dev start --runtime docker   # docker compose
hoox dev start --runtime native   # wrangler dev

# Docker Compose directly (with profiles)
docker compose --profile workers up        # workers only
docker compose --profile full up           # workers + dashboard
docker compose --profile dashboard up      # dashboard only

# Or start individual workers
hoox dev worker <name> [--runtime native|docker]
hoox dev dashboard                         # dashboard only

# TUI (interactive terminal UI)
./hoox-tui

4.9 Step 9: Dashboard Local Dev

# Start dashboard dev server
hoox dev dashboard

# Or manually
cd workers/dashboard && bun run dev

The dashboard runs at http://localhost:3000.

---

5. Production Setup

5.1 Phase 1: Account & Tooling

1. Create Cloudflare account
2. Generate API Token with required permissions (see Section 2.3)
3. Install Bun, Wrangler CLI
4. Authenticate: wrangler login

5.2 Phase 2: Repository Setup

# Clone with submodules
git clone --recursive https://github.com/jango-blockchained/hoox-setup.git
cd hoox-setup

# Install dependencies
bun install

# Verify structure
bun run check:worker-submodules

5.3 Phase 3: Infrastructure Provisioning

See Section 6 for detailed commands.

5.4 Phase 4: Configuration

# Copy and edit environment
cp .env.example .env.local
# Set all required values

# Update wrangler.jsonc
# - Set your account_id
# - Set your secret_store_id
# - Set your subdomain_prefix
# - Enable/disable workers as needed

5.5 Phase 5: Secret Deployment

# Push all secrets to Cloudflare
hoox secrets update-cf

# Or set individually per worker:
wrangler secret put WEBHOOK_API_KEY_BINDING --config workers/hoox/wrangler.jsonc
wrangler secret put INTERNAL_KEY_BINDING --config workers/hoox/wrangler.jsonc
wrangler secret put AGENT_INTERNAL_KEY --config workers/agent-worker/wrangler.jsonc
# ... etc for all secrets

5.6 Phase 6: Database Setup

# Apply schema
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

# Apply tracking schema
bun run migrate:tracking

5.7 Phase 7: KV Configuration

# Set required KV keys
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "webhook:tradingview:ip_check_enabled" "false"

wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "trade:kill_switch" "false"

wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d \
  "trade:max_daily_drawdown_percent" "10"

5.8 Phase 8: Worker Deployment

See Section 7 for the exact sequence.

5.9 Phase 9: Dashboard Deployment

cd workers/dashboard

# Build with OpenNext
bun run opennext:build

# Deploy to Cloudflare Workers
bun run opennext:deploy

5.10 Phase 10: Verification

See Section 10 for validation procedures.

---

6. Infrastructure Provisioning

6.1 D1 Database

# Create database
wrangler d1 create trade-data-db

# Note the database_id from output
# Update in:
# - workers/trade-worker/wrangler.jsonc
# - workers/d1-worker/wrangler.jsonc

# Apply schema
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

Schema Tables:

• trade_signals — Incoming signal tracker
• trades — Executed trades log
• positions — Active & closed positions
• balances — Exchange balance snapshots
• system_logs — System observability logs

6.2 KV Namespaces

# Create CONFIG_KV (shared across all workers)
wrangler kv:namespace create CONFIG_KV
# ID: c5917667a21745e390ff969f32b1847d

# Create SESSIONS_KV (for hoox gateway)
wrangler kv:namespace create SESSIONS_KV
# ID: ff70a58b492e45d79880a7a8213c745c

# Update all wrangler.jsonc files with these IDs

6.3 R2 Buckets

# Create trade reports bucket
wrangler r2 bucket create trade-reports

# Create system logs bucket
wrangler r2 bucket create hoox-system-logs

# Create user uploads bucket
wrangler r2 bucket create user-uploads

6.4 Queue

# Create trade execution queue
wrangler queues create trade-execution

6.5 Vectorize Index

# Create RAG vector index
wrangler vectorize create my-rag-index --dimensions=768 --metric=cosine

6.6 Analytics Engine

# Create analytics dataset
# Via Cloudflare Dashboard: Workers & Pages > Analytics Engine
# Name: hoox-analytics

6.7 Durable Objects Migration

The hoox worker requires a Durable Object migration:

// Already defined in workers/hoox/wrangler.jsonc
"durable_objects": {
  "bindings": [
    {
      "name": "IDEMPOTENCY_STORE",
      "class_name": "IdempotencyStore"
    }
  ]
},
"migrations": [
  {
    "tag": "v1",
    "new_sqlite_classes": ["IdempotencyStore"]
  }
]

This is automatically applied on first deploy.

---

7. Worker Deployment Sequence

7.1 Deployment Order

1. analytics-worker    (no dependencies)
2. report-worker       (depends on: analytics-worker)
3. d1-worker           (depends on: analytics-worker)
4. telegram-worker     (depends on: trade-worker, hoox, analytics-worker)
5. web3-wallet-worker  (depends on: telegram-worker, analytics-worker)
6. email-worker        (depends on: trade-worker, analytics-worker)
7. trade-worker        (depends on: d1-worker, telegram-worker, analytics-worker)
8. agent-worker        (depends on: d1-worker, trade-worker, telegram-worker, analytics-worker)
9. hoox                (depends on: trade-worker, telegram-worker, analytics-worker)
10. dashboard          (depends on: all services being live)

7.2 Deployment Commands

# Deploy all workers in correct order
hoox workers deploy analytics-worker
hoox workers deploy report-worker
hoox workers deploy d1-worker
hoox workers deploy telegram-worker
hoox workers deploy web3-wallet-worker
hoox workers deploy email-worker
hoox workers deploy trade-worker
hoox workers deploy agent-worker
hoox workers deploy hoox

# Or deploy all enabled workers (CLI handles order)
hoox workers deploy --all

7.3 Post-Deployment: Telegram Webhook

# Set Telegram webhook after telegram-worker is deployed
curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://telegram-worker.<SUBDOMAIN_PREFIX>.workers.dev/webhook",
    "secret_token": "<TELEGRAM_SECRET_TOKEN>"
  }'

7.4 Post-Deployment: Update Internal URLs

# Update service URLs in dashboard wrangler.jsonc
hoox workers update-internal-urls

---

8. Dashboard Setup & Deployment

8.1 Configuration Files

8.2 Wrangler Configuration

// workers/dashboard/wrangler.jsonc
{
  "name": "hoox-dashboard",
  "main": ".open-next/worker.js",
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "compatibility_date": "2026-04-17",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "vars": {
    "D1_WORKER_URL": "https://d1-worker.hoox.workers.dev",
    "AGENT_SERVICE_URL": "https://agent-worker.hoox.workers.dev",
    "TRADE_SERVICE_URL": "https://trade-worker.hoox.workers.dev",
    "TELEGRAM_SERVICE_URL": "https://telegram-worker.hoox.workers.dev",
  },
}

8.3 Local Development

cd workers/dashboard

# Install dashboard dependencies (if not done at root)
bun install

# Set credentials
cp .env.local.example .env.local
# Edit: DASHBOARD_USER, DASHBOARD_PASS

# Start dev server
bun run dev
# Access: http://localhost:3000

8.4 Production Build & Deploy

cd workers/dashboard

# Install dependencies
bun install

# Build with OpenNext
bun run opennext:build
# Output: .open-next/worker.js and .open-next/assets

# Deploy to Cloudflare Workers
bun run opennext:deploy

# Or from root:
bun run pages:deploy

8.5 Dashboard Environment Variables

---

9. Secret Management Reference

9.1 Setting Secrets via CLI

# Set a secret for a specific worker
wrangler secret put <SECRET_NAME> --config workers/<worker>/wrangler.jsonc
# You will be prompted to enter the value (hidden input)

# Set secret via hoox CLI
hoox secrets update-cf <SECRET_NAME> <WORKER_NAME>

# Set all secrets from wrangler.jsonc
hoox secrets update-cf

9.2 Local Development Secrets

For local development with wrangler dev, create .dev.vars in each worker directory:

# workers/hoox/.dev.vars
WEBHOOK_API_KEY_BINDING=dev-webhook-key
INTERNAL_KEY_BINDING=dev-internal-key

# workers/trade-worker/.dev.vars
INTERNAL_KEY_BINDING=dev-internal-key
MEXC_KEY_BINDING=dev-mexc-key
MEXC_SECRET_BINDING=dev-mexc-secret
# ... etc

9.3 Secret Security Best Practices

1. Never commit secrets — Use .gitignore for .env.local, .dev.vars, .keys/
2. Use wrangler secret put — Never pass secrets as CLI arguments
3. Rotate regularly — Exchange API keys every 90 days
4. Use least privilege — Create exchange API keys with minimal permissions
5. Enable IP restrictions — Restrict exchange API keys to Cloudflare IP ranges
6. Monitor usage — Review analytics-worker logs for unusual patterns

---

10. Validation & Health Checks

10.1 Automated Validation Commands

# Check overall setup
hoox check-setup

# Check secrets
hoox secrets list

# Check worker health
hoox check health

# Run tests
bun test
bun run tests:coverage

# Type checking
bun run typecheck
bun run build

# Lint
bun run lint

10.2 Manual Health Checks

10.2.1 Gateway Health

# Check hoox gateway
curl https://hoox.<SUBDOMAIN_PREFIX>.workers.dev/health

# Expected: {"status":"ok"}

10.2.2 Trade Worker Health

# Check trade worker
curl https://trade-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

# Check signals endpoint
curl https://trade-worker.<SUBDOMAIN_PREFIX>.workers.dev/api/signals \
  -H "Authorization: Bearer <API_SERVICE_KEY>"

10.2.3 Agent Worker Health

# Check agent health
curl https://agent-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

# Check status
curl https://agent-worker.<SUBDOMAIN_PREFIX>.workers.dev/status

10.2.4 D1 Worker Health

# Test D1 query
curl -X POST https://d1-worker.<SUBDOMAIN_PREFIX>.workers.dev/query \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth-Key: <D1_INTERNAL_KEY>" \
  --data '{"query":"SELECT 1"}'

10.2.5 Telegram Worker Health

# Check telegram worker
curl https://telegram-worker.<SUBDOMAIN_PREFIX>.workers.dev/health

10.2.6 Analytics Worker Health

# Track a test event
curl -X POST https://analytics-worker.<SUBDOMAIN_PREFIX>.workers.dev/track/test \
  -H "Content-Type: application/json" \
  --data '{"event":"test","value":1}'

10.2.7 Dashboard Health

# Check dashboard
curl https://hoox-dashboard.<SUBDOMAIN_PREFIX>.workers.dev/api/health

10.3 Database Validation

# List tables
wrangler d1 execute trade-data-db --command="SELECT name FROM sqlite_master WHERE type='table'" --remote

# Check trade_signals count
wrangler d1 execute trade-data-db --command="SELECT COUNT(*) FROM trade_signals" --remote

# Check recent logs
wrangler d1 execute trade-data-db --command="SELECT * FROM system_logs ORDER BY timestamp DESC LIMIT 10" --remote

10.4 KV Validation

# List KV keys
wrangler kv:key list --namespace-id=c5917667a21745e390ff969f32b1847d

# Check kill switch
wrangler kv:key get --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch"

10.5 Complete System Validation Checklist

• All workers deployed and returning HTTP 200 on /health
• D1 database has all required tables
• KV namespace has required configuration keys
• Secrets are set for all enabled workers
• Service bindings resolve correctly (no 502/503 errors)
• Queue is configured and consumer is registered
• Telegram webhook is set and responding
• Dashboard accessible and authenticated
• Analytics Engine receiving data points
• Cron triggers scheduled (agent-worker: every 5min, email-worker: every 5min)

---

11. Repair & Recovery Procedures

11.1 Complete System Repair Checklist

# 1. Verify repository integrity
bun run check:worker-submodules
bun run lint:scripts

# 2. Verify dependencies
bun install

# 3. Verify TypeScript
bun run typecheck

# 4. Verify tests
bun test

# 5. Verify infrastructure exists
wrangler d1 list
wrangler kv:namespace list
wrangler r2 bucket list
wrangler queues list
wrangler vectorize list

# 6. Verify secrets
hoox secrets list

# 7. Verify worker health
hoox check health

# 8. Redeploy if needed
hoox deploy workers

11.2 Individual Worker Repair

# Redeploy a single worker
hoox workers deploy <worker-name>

# Check worker logs
hoox workers logs <worker-name>

# Tail logs in real-time
wrangler tail --config workers/<worker-name>/wrangler.jsonc

11.3 Database Repair

# Reset database schema (WARNING: Destructive)
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

# Apply tracking schema
bun run migrate:tracking

# Check for missing tables
wrangler d1 execute trade-data-db --command="SELECT name FROM sqlite_master WHERE type='table'" --remote

11.4 Secret Repair

# If secrets are missing, re-upload all from wrangler.jsonc
hoox secrets update-cf

# Or set individual secrets
wrangler secret put <SECRET_NAME> --config workers/<worker>/wrangler.jsonc

11.5 KV Configuration Repair

# Reset critical KV keys
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "false"
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "webhook:tradingview:ip_check_enabled" "false"
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:max_daily_drawdown_percent" "10"

11.6 Dashboard Repair

cd workers/dashboard

# Rebuild
bun run opennext:build

# Redeploy
bun run opennext:deploy

# Clear browser cache and cookies if auth issues

11.7 Complete Rebuild from Scratch

# 1. Backup any important data from D1/R2

# 2. Delete and recreate D1
wrangler d1 delete trade-data-db
wrangler d1 create trade-data-db

# 3. Delete and recreate KV (note: data loss)
# KV namespaces cannot be renamed, create new ones if needed

# 4. Redeploy all workers
hoox workers deploy --all

# 5. Re-apply schema
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote

# 6. Reconfigure KV
# Set all required keys (see Section 3.3)

# 7. Reconfigure Telegram webhook
# (see Section 7.3)

# 8. Redeploy dashboard
cd workers/dashboard && bun run opennext:build && bun run opennext:deploy

---

12. Operational Runbook

12.1 Daily Operations

# Check system health
hoox check health

# Check recent trades
wrangler d1 execute trade-data-db --command="SELECT * FROM trades ORDER BY timestamp DESC LIMIT 5" --remote

# Check system logs
wrangler d1 execute trade-data-db --command="SELECT * FROM system_logs ORDER BY timestamp DESC LIMIT 20" --remote

12.2 Kill Switch Operations

# Emergency stop all trading
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "true"

# Resume trading
wrangler kv:key put --namespace-id=c5917667a21745e390ff969f32b1847d "trade:kill_switch" "false"

12.3 Updating Workers

# Pull latest code
git pull --recurse-submodules

# Update dependencies
bun install

# Run checks
bun run lint
bun run typecheck
bun test

# Deploy updated workers
hoox deploy workers

# Verify deployment
hoox check health

12.4 Rotating Secrets

# Generate new key
hoox keys generate <SECRET_NAME>

# Update in Cloudflare
hoox secrets update-cf <SECRET_NAME> <WORKER_NAME>

# Update any local .dev.vars files

# Verify functionality
bun test

12.5 Monitoring

12.6 Backup Procedures

# Export D1 database
wrangler d1 export trade-data-db --output=backup-$(date +%Y%m%d).sql --remote

# Export KV (manual script needed)
# R2 buckets can be synced with rclone

---

13. Complete File Inventory

13.1 Required Configuration Files

13.2 Worker Configuration Files

13.3 Dashboard Files

13.4 Package Files

13.5 Script Files

13.6 Documentation Files

---

14. Troubleshooting Matrix

---

Appendix A: Quick Reference Commands

# Setup
bun install
hoox onboard                  # One-shot full bootstrap (recommended)
hoox secrets sync             # Push .dev.vars to Cloudflare

# Development
hoox dev start                # Start all workers (choose runtime)
hoox dashboard dev            # Dashboard only
hoox tui                      # Interactive TUI
hoox workers dev <name>       # Dev single worker
bun run dev                   # Dashboard dev

# Testing
bun test                      # Unit tests
bun run tests:coverage        # Coverage
bun run test:integration      # Integration tests

# Deployment
hoox deploy workers           # Deploy all workers
hoox deploy worker <name>     # Deploy one worker
hoox dashboard deploy         # Deploy dashboard
# OR (equivalent): hoox deploy dashboard

# Operations
hoox check health             # Check worker health (single source of truth)
hoox workers logs <name>      # View worker logs
hoox check setup              # Validate setup
hoox secrets list <worker>    # Check secrets

# Database
wrangler d1 execute trade-data-db --file=workers/trade-worker/schema.sql --remote
bun run migrate:tracking

# KV
wrangler kv:key put --namespace-id=<ID> <key> <value>
wrangler kv:key list --namespace-id=<ID>

# Secrets
wrangler secret put <NAME> --config workers/<worker>/wrangler.jsonc
hoox secrets update-cf

# Health Checks
curl https://<worker>.<prefix>.workers.dev/health

Appendix B: Directory Structure

hoox-setup/
├── .opencode/                    # Project intelligence hub
├── .env.local                    # Local environment (gitignored)
├── .env.example                  # Environment template
├── wrangler.jsonc                 # Central worker config
├── package.json                  # Root workspace manifest
├── bunfig.toml                   # Bun config
├── tsconfig.json                 # TypeScript config
├── vitest.config.ts              # Vitest config
├── hoox-tui                      # TUI launcher (if exists)
│
├── packages/
│   ├── cli/                 # CLI tool
│   │   ├── bin/hoox.js           # CLI entry
│   │   └── src/
│   │       ├── index.ts          # Command dispatcher
│   │       ├── commands/         # CLI commands
│   │       ├── adapters/         # Cloudflare/Bun adapters
│   │       └── core/             # Engine, observer, types
│   └── shared/                   # Shared types/utilities
│       └── src/
│           ├── types.ts          # Core types
│           ├── router.ts         # Custom router
│           ├── middleware/       # Auth, rate-limit, logger
│           └── errors.ts         # Error factories
│
├── workers/
│   ├── hoox/                     # Gateway worker
│   ├── trade-worker/             # Trading execution
│   │   └── schema.sql            # D1 schema
│   ├── agent-worker/             # AI risk manager
│   ├── d1-worker/                # Database service
│   ├── telegram-worker/          # Telegram notifications
│   ├── web3-wallet-worker/       # DeFi operations
│   ├── email-worker/             # Email signal parsing
│   ├── analytics-worker/         # Analytics collection
│   ├── report-worker/            # PDF reports
│   └── dashboard/                # Next.js 16 dashboard
│       ├── next.config.ts
│       ├── wrangler.jsonc
│       ├── src/middleware.ts
│       └── src/app/              # Next.js app routes
│
├── scripts/
│   ├── migrate-tracking.sh       # D1 tracking migration
│   ├── check-worker-submodules.ts
│   └── purge-credentials.sh      # Emergency credential purge
│
└── docs/                         # Documentation
    ├── getting-started/
    ├── deployment/
    ├── development/
    ├── workers/
    └── architecture/

---

Document Version: 1.0.0
Last Updated: 2026-05-05
Maintainer: Hoox Development Team