Hoox Docs

🗂️ Cloudflare Services Map

Hoox is built natively on a serverless microservice architecture powered by a suite of fully integrated Cloudflare® services. By offloading database scaling, messaging retry loops, file storage, and AI inference to Cloudflare’s global infrastructure, Hoox runs with zero server maintenance, ultra-low latency, and $0 monthly costs on the free tier.

Here is an architectural map of how each service functions in the Hoox monorepo.

🗄️ 1. D1 Database (Edge SQL Engine)

  • Concept: A serverless, globally distributed SQLite database engine natively hosted at Cloudflare’s edge locations.
  • Hoox Implementation: Used to store critical transactional data, including executed trades ledger, historical win rates, daily asset balances, and position tracking tables.
  • Why it Matters:
    • Writes are atomic and ACID-compliant.
    • Queries complete in under 5 milliseconds because the database runs in the same V8 isolate context as your worker logic.
    • No need to host, secure, patch, or configure connection pools for a separate database server (like PostgreSQL or MySQL).

🔑 2. KV Store (Sub-Millisecond Key-Value Configuration)

  • Concept: A highly available, globally distributed key-value store optimized for high-read/low-write operations.
  • Hoox Implementation: Houses the global 16-key runtime manifest, including the Global Kill Switch (trade:kill_switch), exchange routing paths, rate-limiter profiles, and authorized client IP ranges.
  • Why it Matters:
    • Read operations are cached directly at Cloudflare’s edge nodes, delivering sub-millisecond lookups.
    • Updates propagate worldwide in under 10 seconds. You can toggle settings in your terminal, and the change affects every worker globally in seconds, without code redeployment.

📨 3. Cloudflare Queues (Asynchronous Messaging Guard)

  • Concept: A high-integrity, serverless message broker guaranteeing at-least-once delivery with built-in retry schedules.
  • Hoox Implementation: Acts as an asynchronous buffer and retry buffer for signal executions (queue_failover mode).
  • Why it Matters:
    • If a centralized exchange (like Bybit or Binance) undergoes system maintenance or experiences rate limits, the Hoox Gateway intercepts the API error, serializes the trade payload, and enqueues it.
    • The queue automatically retries execution with an exponential backoff schedule (30s → 1m → 5m → 15m → 30m). Your trades never get lost due to internet dropouts or API errors.

🔒 4. Durable Objects (Distributed Coordination & Idempotency)

  • Concept: Single-threaded, in-memory compute isolates containing persistent local storage, ensuring that exactly one instance of an object runs globally.
  • Hoox Implementation: Drives the Gateway’s Idempotency Engine inside workers/hoox.
  • Why it Matters:
    • When TradingView fires multiple retries for the same alert (due to a transient network timeout), Durable Objects intercept the request, acquire an atomic mutex lock, and evaluate the trade’s unique hash.
    • Prevents disastrous duplicate trades (e.g. accidentally buying the same spot position twice) during moments of high market congestion.

📦 5. R2 Object Storage (Zero-Egress Asset Vault)

  • Concept: A fully S3-compatible, serverless object storage bucket featuring zero bandwidth egress fees.
  • Hoox Implementation: Stores large data payloads, verbose exchange API request/response packets, and compiled HTML/PDF reports.
  • Why it Matters:
    • Offloading heavy system logging to R2 saves massive write capacity on your D1 SQL database, keeping your database compact and responsive.
    • Zero-egress pricing means you can retrieve, export, and audit your historic trade logs as many times as you like without incurring network charges.

🧠 6. Vectorize & Workers AI (Embedded RAG & LLMs)

  • Concept: A serverless vector search database and an on-demand edge AI inference engine running specialized open-source models (like LLaMA 3, Qwen, and Mistral).
  • Hoox Implementation: Integrates with the Telegram Bot (telegram-worker) to provide semantic trade analysis and context-aware natural language conversations.
  • Why it Matters:
    • User chat queries are converted into high-dimensional vector embeddings, searched against historical trades inside Vectorize, and fed into Workers AI as context.
    • Deliver highly intelligent, context-aware risk analysis directly on your mobile chat without calling expensive external APIs.

🌐 7. Browser Rendering (Edge Puppeteer Renderer)

  • Concept: Serverless Chrome instances running at Cloudflare’s edge, allowing developers to automate browser actions, interact with websites, and convert web elements to documents.
  • Hoox Implementation: Deployed in report-worker to generate twice-daily, styled PDF portfolio reports.
  • Why it Matters:
    • Reads D1 database P&L records, renders a beautiful, secure HTML5 dashboard report, captures it via Puppeteer, converts it to PDF, saves the file to R2, and links it directly in your Telegram alert.
    • Completely automated, running entirely in the background near-instantaneously.

Tip: Every single one of these services is supported by the Hoox CLI! You can check database tables using hoox db query, provision R2 buckets with hoox infra r2 create, and sync your KV manifest using hoox config kv apply-manifest instantly.

🔗 Next Steps

  • Idempotency Mechanics — Dive into the V8 Durable Objects coordination engine.
  • AI Risk Manager — Understand how autonomous edge cron jobs evaluate drawdowns and manage trailing stops.