Skip to main content

​
📐 Architecture Decision Records (ADRs)

This directory contains the Architecture Decision Records for the Hoox trading platform. Each ADR documents a significant architectural choice, its context, the decision made, and its consequences.

​
ADR Index

​
ADR-001: Cloudflare Workers as Execution Platform

Status: Accepted Context: Algorithmic trading requires ultra-low latency between signal generation and order execution. Traditional VPS-based bots suffer from 200ms+ round-trip latency due to fixed geographic locations and heavy runtime overhead. Decision: Deploy all trading logic as Cloudflare Workers running on V8 isolates at the edge. Consequences:
  • Positive: 30-60% latency reduction vs. VPS
  • Negative: 128MB memory limit per isolate
  • Mitigation: Web3 wallet worker uses EVM-compatible RPC calls

​
ADR-002: SQLite-backed Durable Objects for Idempotency

Status: Accepted Context: Webhook-based trade execution is inherently unreliable — network timeouts can cause TradingView to retry the same signal, potentially resulting in duplicate trades. Financial systems require exactly-once execution semantics. Decision: Implement idempotency using Cloudflare Durable Objects with SQLite-backed state. Each incoming trade signal is hashed into a unique trace ID. A singleton DO instance per trace ID acts as a distributed mutex lock, atomically checking and recording whether the signal has been processed. Consequences:
  • Positive: Zero-race-condition dedup with single-threaded DO isolation
  • Negative: Adds one network hop per request
  • Mitigation: DO alarm scheduled at TTL for automatic garbage collection

​
ADR-003: 9-Microservice Architecture

Status: Accepted Context: Monolithic trading systems are fragile — a crash in any component (portfolio calculation, notification, database) takes down the entire system. Microservices provide isolation but increase operational complexity. Decision: Split the platform into 9 specialized workers, each with a single responsibility: Consequences:
  • Positive: Independent scaling; failure isolation; focused development; clean ownership boundaries
  • Negative: More deployment units to manage; Service Binding dependency chain complexity; inter-worker communication overhead
  • Mitigation: CLI automates dependency-ordered deployment; health check endpoints on every worker; TUI provides real-time status of all 9 workers

​
ADR-004: Dual-Layer Configuration (Environment + KV)

Status: Accepted Context: Configuration needs fall into two categories. Decision: Use two distinct configuration layers:
  1. API keys, internal auth keys, dashboard credentials. Managed via hoox secrets set and hoox config env.
  2. Runtime (Cloudflare KV): Kill switch, exchange routing, rate-limiter thresholds, email regex patterns. Managed via hoox config kv set and propagates globally in under 10 seconds.
Consequences:
  • Positive: Kill switch takes effect on next request
  • Negative: Config values are eventually consistent
  • Mitigation: KV manifest with documented defaults; hoox config kv apply-manifest for one-command sync; documentation clearly separates the two layers

​
ADR-005: Multi-Provider AI Gateway with Fallback Chain

Status: Accepted Context: The agent-worker needs LLM capabilities for risk assessment, market analysis, and user chat. Single-provider AI introduces single points of failure and cost concentration. Decision: Implement a 5-provider fallback chain ordered by cost and availability:
Each provider is health-checked before use. On failure, the gateway automatically retries with the next provider. Usage and costs are tracked per-provider. Consequences:
  • Positive: Zero single point of failure for AI; cost optimization (use free tier first); resilience against provider outages; vision + reasoning + chat in one gateway
  • Negative: Complex provider abstraction layer; potential for inconsistent response quality across providers; harder to optimize prompts for all providers simultaneously
  • Mitigation: Provider selection per-request (caller specifies preferred provider); standardized response schemas; usage dashboard for cost monitoring

​
ADR-006: Bun Workspaces for Monorepo Management

Status: Accepted Context: The project contains multiple packages (CLI, TUI, shared library, 9 workers) that need to share types, utilities, and be tested/developed locally. Decision: Use Bun Workspaces as the monorepo manager instead of npm/yarn/pnpm workspaces. Rationale:
  • Native TypeScript compilation (no separate tsconfig complexity)
  • Built-in test runner (no Jest/Mocha dependency)
  • Fastest install times among JS package managers
  • Single bun.lockb lockfile for all workspaces
  • Native script runner for CI pipeline
Consequences:
  • Positive: Zero-config TypeScript; fast CI; unified tooling; shared types resolve at compile time
  • Negative: Bun is less mature than npm ecosystem; some packages may have compatibility issues; harder to onboard developers unfamiliar with Bun
  • Mitigation: Comprehensive hoox check prerequisites validation; Docker runtime as fallback; documentation covers both native and Docker workflows
Last modified on July 5, 2026