​

HOOX Enterprise Architecture

Important – Open Core Model This document describes the commercial Enterprise extension layer. HOOX follows an Open Core model:

• The core architecture, most workers, packages/shared, CLI, TUI, and the majority of documentation are open source.
• Advanced multi-tenancy, proprietary features, full compliance stacks, hosted SaaS platform, and certain advanced implementations live in a separate closed-source commercial repository.

See:

• OPEN_CORE.md
• OPEN_CORE_FEATURE_SPLIT.md

The documents in this folder describe how the commercial layer is built on top of the open core. They are published publicly for transparency and to support the academic paper.

​

Vision & Principles

• Everything at the Edge, Amplified: Preserve the current zero-server, Service Binding, Smart Placement, DO-based model. Enterprise unlocks scale, isolation, compliance, and durability without introducing traditional infra.
• Multi-Tenancy First: Support hosted SaaS (funds, prop shops, platforms) or dedicated high-volume Enterprise deployments with strong isolation.
• Durable + Event-Driven: Move from cron-heavy to Workflows + real-time WS-driven.
• Audit & Compliance by Default: Every action logged immutably.
• Bleeding Edge but Practical: Use features that are GA or recently stabilized (WfP dashboard improvements, synchronous User Worker deploys, Workflows enhancements, Logpush one-click + custom fields, etc.).
• Evolutionary: Existing single-tenant HOOX remains for retail/self-hosted. Enterprise is additive/parallel.

​

Core Levers (Enterprise / Paid Unlocks)

1. Workers for Platforms (WfP)
   • Dynamic Dispatch Worker routes to isolated “User Workers” (per tenant, per strategy, per fund).
   • Namespaces, tags for metering/billing/isolation.
   • User Workers can have their own bindings, DOs, Queues (isolated).
   • Recent improvements: Dashboard support for namespaces/dispatch/templates/tags (Dec 2025), static assets support, synchronous first-time uploads (Feb 2025) so deploys are immediately routable.
   • Perfect for “bring your own strategy” or multi-fund platforms.
   • Enterprise: higher scale, custom limits, better support for customer code execution.
2. Workflows (Durable Execution)
   • Long-running (hours/days), stateful, automatically retrying, pause-for-external-events.
   • Step-level persistence, input/output gates.
   • Integrates with Agents (real-time) and existing DOs.
   • Use cases:
     • Full trade lifecycle (validate → risk → execute → reconcile → report).
     • Kill switch + position flattening sequences that must complete atomically.
     • Daily compliance/report generation with human approval gates.
     • Post-trade reconciliation across exchanges/D1/R2.
   • Recent enhancements: step context (retry count), dynamic workflows, AgentWorkflow integration.
   • Enterprise: higher execution volume, longer durations, more steps.
3. Observability & Audit (Logpush + Traces + Observability suite)
   • Full Workers Trace Events, HTTP, WAF, Queue, DO, etc. pushed to R2 (or external SIEM like SentinelOne).
   • One-click R2 setup, custom fields (raw/transformed headers), daily partitions.
   • Workers Logs (dashboard), Real-time logs, Tail Workers for sampling/filtering/enrichment.
   • End-to-end traces across Service Bindings, DOs, Queues, Workflows.
   • Analytics Engine remains for high-cardinality metrics; Logpush for compliance/audit.
   • Enterprise: higher log volume, longer retention, dedicated support, integration options.
4. Enterprise Security Stack
   • Bot Management (Enterprise): bot scores, verified bots, corporate proxy detection, JA4/JA3, JS detection. Protect signal sources (TradingView webhooks, Telegram, email).
   • API Shield: schema validation, JWT validation, mTLS for clients (dashboard or partner APIs), sequence mitigation.
   • Advanced WAF + Rulesets: 100+ rate limit rules, custom high-cardinality rules, managed rules for trading threats.
   • Zero Trust / Access: Enforce identity for dashboard, CLI mgmt, internal tools. SCIM, device posture, etc.
   • mTLS / Mutual TLS: Between services or for outbound.
   • Data Loss Prevention / Gateway if needed for sensitive configs.
   • Existing 5-layer model (WAF → Gateway auth → Service Bindings → Internal key → DO mutex) is extended with Ent controls.
5. Real-time & Persistent Connections
   • Hibernatable WebSockets in Durable Objects (keep connections alive cheaply while DO sleeps).
   • Evolve ExchangeConnectionManager DO to maintain persistent WS to Binance/Bybit/etc. for live fills, partials, order books.
   • Drive risk management, notifications, and analytics from real events instead of (or alongside) 5-min cron.
   • Combined with Workflows for durable handling of streams.
6. Scale, Limits & Performance (Enterprise Unlocks)
   • Significantly higher CPU time, memory, subrequests, concurrent connections, Worker size, # of Workers/crons per account.
   • Custom limit increases via account team.
   • Higher D1 storage/reads/writes, R2 operations, Queue throughput, Vectorize dimensions/index size.
   • DO: higher concurrency per namespace, more DOs, better SQLite performance at scale.
   • Smart Placement + Enterprise routing hints for even lower jitter to exchange regions.
   • Hyperdrive for accelerating any external data sources (if hybrid Postgres/etc. used for large historical data).
7. AI at Institutional Scale
   • AI Gateway: logging, caching, rate limiting, fallbacks, cost control, prompt sanitization in front of Workers AI or external providers (OpenAI, etc.).
   • Workers AI + Vectorize at Enterprise volumes (large strategy corpus, market embeddings, RAG for compliance docs or historical trades).
   • Integration with Workflows/Agents for sophisticated risk agents, anomaly detection, natural language strategy config.
   • Existing simple RAG in telegram-worker becomes production-grade with Gateway + fallbacks.
8. Storage & Data Sovereignty
   • R2: Event Notifications (trigger Workflows on new trade logs/reports), jurisdiction controls (data residency), larger scale, lifecycle policies for immutable audit logs.
   • D1: Enterprise storage/throughput, point-in-time recovery, read replicas (if/when available), larger DBs per tenant.
   • KV + DO SQLite for low-latency config/state.
   • Immutable audit: Logpush + R2 WORM-like + cryptographic hashes/signatures in D1.
9. Other Bleeding Edge
   • Browser Rendering at scale (more concurrent renders for compliance reports).
   • Builds (CI/CD for User Workers in WfP).
   • Email Workers / advanced routing for signal ingestion.
   • Magic Transit / Spectrum if private connectivity to exchanges or on-prem required (rare for CEX but useful for some prop shops).
   • Queues + Workflows for reliable backpressure and exactly-once-ish semantics at high volume.

​

High-Level Target Topology (Enterprise)

Public Ingress (WAF + Bot Mgmt + API Shield)
          │
          ▼
Dispatch Worker (Workers for Platforms)  ← Tenant/Strategy routing + auth (Zero Trust)
          │
    ┌─────┴─────┐
    ▼           ▼
User Workers / System Workers (isolated per tenant/strategy)
    │
    ├──► Service Bindings (still <1µs, now tenant-scoped)
    │
    ├──► Durable Objects (per-tenant DO namespaces)
    │     - Idempotency (SQLite)
    │     - ExchangeConnectionManager (Hibernatable WS for live data)
    │     - Risk state / position managers
    │
    ├──► Workflows (durable lifecycles)
    │     - Trade execution + reconciliation
    │     - Kill-switch sequences
    │     - Daily compliance reports
    │
    ├──► Queues (higher throughput, with Workflows consumers)
    │
    └──► Storage (tenant-partitioned)
          - D1 (per-tenant or sharded)
          - R2 (immutable logs + jurisdiction)
          - Vectorize (filtered by tenant)
          - Analytics Engine (tagged)

Observability Layer (always on)
- Workers Traces (cross everything)
- Logpush → R2 (full audit, custom fields)
- Tail Workers (sampling, enrichment)
- AI Gateway (for any AI calls)
- Dashboard (Zero Trust protected, multi-tenant views)

​

Key New / Evolved Components

​

1. Dispatch + User Workers (WfP)

• Central Dispatch Worker inspects request (tenant id from subdomain, header, or JWT), looks up namespace, dispatches to User Worker.
• Each User Worker can contain strategy-specific logic or a full lightweight HOOX instance.
• Static assets support for per-tenant dashboards/UI if needed.
• Tagging for billing/quotas.

​

2. Workflows Definitions

• TradeLifecycleWorkflow: validate → pre-risk → execute (with retries) → persist → post-risk → notify → reconcile.
• ReconciliationWorkflow: runs daily, compares D1 vs exchange reports (via Browser Rendering or API), flags discrepancies.
• ComplianceReportWorkflow: gathers logs (from R2), generates PDF (Browser), signs, uploads, notifies.

​

3. Enhanced DOs

• IdempotencyStore generalized with tenant/strategy prefix.
• ExchangeConnectionManager uses hibernatableWebSockets + alarms for cleanup.
• New DOs for per-tenant risk engines, session state, etc.
• RPC methods + SQLite for best DX/performance.

​

4. Observability Pipeline

• Every Worker/Workflow/DO emits structured events.
• Logpush jobs (one-click or API) to R2 with output_options for relevant fields.
• Tail Worker example for redacting secrets or adding tenant context.
• Full traces for root-causing a missed fill across 5+ Workers.

​

5. Security Hardening

• Bot score checks early in gateway/dispatch.
• API Shield schemas for all public + internal-ish endpoints.
• Zero Trust policies for dashboard + mgmt APIs.
• Per-tenant secrets (using Workers secrets or Secret Store at scale).
• mTLS where Services talk to trusted partners.

​

Tenant Isolation Model

• Namespace per tenant (or per “fund” / “book”).
• DOs, Queues, KV, R2 paths, D1 databases prefixed or bound per namespace.
• User Workers run in isolated isolates with their own limits.
• Billing/quotas via tags + custom dashboards (Enterprise).
• Cross-tenant leakage prevented at Dispatch + binding auth layers (evolved requireInternalAuth with tenant claims).

​

Migration & Coexistence

• Retail HOOX stays as-is (free/paid friendly).
• Enterprise customers get:
  • Dedicated Enterprise CF account + templates, or
  • Onboarded into hosted WfP platform.
• Existing code in packages/shared, workers, etc. is reused as libraries/templates.
• Gradual: start with WfP + Logpush + one Workflow, then add real-time WS, Bot Mgmt, etc.

​

Open Decisions (from plan review)

• Primary target: Hosted SaaS (heavy WfP) vs Power-user self-hosted on Ent account vs both?
• Migration strategy for existing users?
• Specific compliance jurisdictions / external SIEM requirements?
• Depth of “user code” execution (full arbitrary strategies vs safe DSL / config-driven)?

​

Next Steps / Implementation Order

1. Create docs/devops/enterprise/ docs (this + security, multi-tenancy, observability).
2. Prototype Dispatch Worker + minimal User Worker + one Workflow (trade-lifecycle).
3. Extend @jango-blockchained/hoox-shared with tenant context, Workflow client, AI Gateway wrapper.
4. Add Logpush config examples + a Tail Worker.
5. Update root architecture docs, ADRs, and papers (new section or companion Enterprise paper).
6. wrangler templates in examples/enterprise/.
7. (Later) Full implementation, tests, bun run graph validation, academic paper updates.

• Workers for Platforms
• Workflows
• Logpush / Observability
• AI Gateway
• Durable Objects (SQLite, WS, Alarms, RPC)
• Enterprise limits & features (higher everything + dedicated support)
• Zero Trust, Bot Management, API Shield