[Architecture Decision Records]

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. Build-time (.env.local + Workers Secrets):

   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:

Workers AI (free) -> Anthropic -> Google AI -> OpenAI -> Azure OpenAI

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