Architecture
HedgeVision system architecture: Domain-Driven Design, Hexagonal Architecture, 24 modules, and Docker container orchestration.
Key Numbers
24
Modules
5
Docker containers
9 GB+
TimescaleDB data
35k+
DB chunks
Architectural Philosophy
HedgeVision is built on Domain-Driven Design (DDD) combined with the Ports & Adapters (Hexagonal Architecture) pattern. Every module contains distinct layers:
module/ ├── domain/ # Pure business logic — no infrastructure dependencies │ ├── models/ # Entities, Value Objects, Aggregates │ ├── logic/ # Domain services, orchestrators │ └── repositories # Ports (abstract interfaces) ├── application/ # Use cases, application services ├── infrastructure/ # Adapters (DB, external APIs, message queues) └── api/ # FastAPI routers (HTTP endpoints)
Null Object Pattern is used extensively: when optional external services (LLMs, brokers, OSINT APIs) are unavailable, the system substitutes a silent null adapter that returns safe defaults rather than raising exceptions.
Module Inventory (Selected)
| Module | Path | Primary Responsibility |
|---|---|---|
| analytics | backend/modules/analytics/ | Statistical analysis: cointegration, correlation, discovery, screening, Perplexity sentiment |
| api | backend/api/ | FastAPI REST API + WebSocket — 30+ routers, all external HTTP interfaces |
| approval | backend/modules/approval/ | Human-in-the-loop approval workflow: tiered auto/trader/senior routing |
| brain | backend/modules/brain/ | PPO RL meta-controller — dynamic sub-model weight adjustment |
| execution | backend/modules/execution/ | Order routing, lifecycle management, broker adapter composition |
| intelligence_hub | backend/modules/intelligence_hub/ | WhaleScout OSINT, OpenBB dark pool, transcript scanner |
| microstructure | backend/modules/microstructure/ | Databento Level 2 order book veto agent |
| orchestration | backend/modules/orchestration/ | Master orchestrator + LangGraph workflow + decision gateway + circuit breakers |
| pipelines | backend/modules/pipelines/ | Multi-tier data ingestion (Crypto Core, Macro Monitor, Gap Assets) |
| prediction | backend/modules/prediction/ | 22+ ML models, ensemble combiner, debate coordinator, critique layer |
| risk | backend/modules/risk/ | CVaR, portfolio optimizer, stress testing, chaos simulation, tail hedging |
| trading | backend/modules/trading/ | Backtesting, Jesse bridge, exchange mapper, broker adapters |
Docker Container Architecture
Five primary containers are defined in docker-compose.yml:
| Container | Configuration | Resource Limits |
|---|---|---|
| timescaledb | TimescaleDB pg17, port 127.0.0.1:5433 | 2 CPU / 4 GB RAM |
| redis | Redis 7, port 127.0.0.1:6379, maxmemory 1gb | 0.5 CPU / 1 GB RAM |
| ibkr-gateway | ghcr.io/extrange/ibkr:stable, 127.0.0.1:4002 | 2 GB RAM |
| mt4-bridge | Custom MT4 REST bridge, 127.0.0.1:8005 | - |
| backend | FastAPI + Uvicorn (Python 3.12+) | - |
Host: Oracle Cloud Always Free — ARM Ampere A1, 4 OCPU, 24 GB RAM.
Security Architecture
- Database binding: 127.0.0.1 only — no external DB exposure
- Broker ports: 127.0.0.1 only for MT4 (8005), IBKR (4002)
- API authentication: auth module — API key / JWT based
- Secrets: Environment variables via .env (never committed)
- Container isolation: All services on superintel-network bridge; no public ports except API
- Rate limiting: Redis-backed rate limiter in FastAPI middleware