# santhosh144awc/openbull architecture

> Architecture diagram of the GitHub repository santhosh144awc/openbull, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santhosh144awc/openbull
- Repository: https://github.com/santhosh144awc/openbull

## Overview

OpenBull is a self-hosted options-trading platform for Indian markets. Users configure a broker, inspect live market data and options analytics, then place orders or build and run strategies in Live or Sandbox mode. The backend exposes both a typed external API and session-authenticated web features, with broker plugins and a shared streaming proxy. Sandbox execution, strategy runtime, persistence, and caching are important internal layers. The README documents the main capabilities; several subsystem paths below are directory-level because their individual implementations were not sampled.

Main entry points: [`backend/services/sandbox_service.py`](https://github.com/santhosh144awc/openbull/blob/main/backend/services/sandbox_service.py) (Sandbox Service), [`backend/strategy/engine.py`](https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/engine.py) (Strategy Engine), [`backend/sandbox/execution_engine.py`](https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/execution_engine.py) (Sandbox Execution), [`backend/services/trading_mode_service.py`](https://github.com/santhosh144awc/openbull/blob/main/backend/services/trading_mode_service.py) (Trading Mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Experience"]
  node_frontend["Web App<br/>[App.tsx]"]
  node_client_api["API Clients"]
end

subgraph group_api["API and Analytics"]
  node_web_routes["Web Routes"]
  node_external_api["Trading API"]
  node_analytics["Options Analytics"]
  node_market_data["Market Data"]
end

subgraph group_trading["Trading Runtime"]
  node_broker_plugins["Broker Plugins"]
  node_broker_services["Broker Services"]
  node_mode_dispatch["Trading Mode"]
  node_sandbox_service["Sandbox Service<br/>[sandbox_service.py]"]
  node_sandbox_execution["Sandbox Execution"]
  node_sandbox_orders["Sandbox Orders<br/>[order_manager.py]"]
  node_sandbox_positions["Sandbox Positions"]
  node_strategy_webhook["Strategy Webhooks<br/>[webhook_handler.py]"]
  node_strategy_engine["Strategy Engine<br/>[engine.py]"]
  node_strategy_scheduler["Strategy Scheduler<br/>[scheduler.py]"]
end

subgraph group_platform["Platform Services"]
  node_ws_proxy["WebSocket Proxy<br/>[server.py]"]
  node_market_cache["Market Data Cache"]
  node_redis[("Redis Cache<br/>[redis_client.py]")]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_event_bus["Strategy Events<br/>[strategy_events.py]"]
end

node_user(("Trader"))
node_broker_systems["Broker Systems"]
node_tradingview(("TradingView"))

node_user -->|"uses"| node_frontend
node_frontend -->|"requests through"| node_client_api
node_client_api -->|"calls web API"| node_web_routes
node_client_api -->|"calls trading API"| node_external_api
node_web_routes -->|"serves analytics"| node_analytics
node_external_api -->|"serves analytics"| node_analytics
node_external_api -->|"dispatches by mode"| node_mode_dispatch
node_web_routes -->|"dispatches by mode"| node_mode_dispatch
node_mode_dispatch -->|"routes live calls"| node_broker_services
node_mode_dispatch -->|"routes sandbox calls"| node_sandbox_service
node_broker_services -->|"uses broker adapters"| node_broker_plugins
node_broker_plugins -->|"connects to"| node_broker_systems
node_broker_plugins -->|"publishes market data"| node_ws_proxy
node_ws_proxy -->|"feeds ticks"| node_market_cache
node_market_data -->|"uses shared cache"| node_market_cache
node_sandbox_service -->|"starts execution"| node_sandbox_execution
node_sandbox_execution -->|"fills orders"| node_sandbox_orders
node_sandbox_execution -->|"applies fills"| node_sandbox_positions
node_sandbox_execution -->|"subscribes to ticks"| node_market_cache
node_sandbox_service -->|"manages orders"| node_sandbox_orders
node_sandbox_service -->|"manages positions"| node_sandbox_positions
node_tradingview -->|"sends signals"| node_strategy_webhook
node_strategy_webhook -->|"dispatches actions"| node_strategy_engine
node_strategy_scheduler -->|"runs strategies"| node_strategy_engine
node_strategy_engine -->|"emits events"| node_event_bus
node_strategy_engine -->|"places sandbox orders"| node_sandbox_service
node_market_cache -.->|"optional cache"| node_redis
node_sandbox_service -->|"persists sandbox state"| node_database
node_strategy_engine -->|"stores strategy state"| node_database

click node_frontend "https://github.com/santhosh144awc/openbull/blob/main/frontend/src/App.tsx"
click node_client_api "https://github.com/santhosh144awc/openbull/tree/main/frontend/src/api"
click node_web_routes "https://github.com/santhosh144awc/openbull/tree/main/backend/routers"
click node_external_api "https://github.com/santhosh144awc/openbull/tree/main/backend/api"
click node_analytics "https://github.com/santhosh144awc/openbull/tree/main/backend/services"
click node_market_data "https://github.com/santhosh144awc/openbull/blob/main/backend/services/market_data_service.py"
click node_broker_plugins "https://github.com/santhosh144awc/openbull/tree/main/backend/broker"
click node_broker_services "https://github.com/santhosh144awc/openbull/tree/main/backend/services"
click node_mode_dispatch "https://github.com/santhosh144awc/openbull/blob/main/backend/services/trading_mode_service.py"
click node_sandbox_service "https://github.com/santhosh144awc/openbull/blob/main/backend/services/sandbox_service.py"
click node_sandbox_execution "https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/execution_engine.py"
click node_sandbox_orders "https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/order_manager.py"
click node_sandbox_positions "https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/position_manager.py"
click node_strategy_webhook "https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/webhook_handler.py"
click node_strategy_engine "https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/engine.py"
click node_strategy_scheduler "https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/scheduler.py"
click node_ws_proxy "https://github.com/santhosh144awc/openbull/blob/main/backend/websocket_proxy/server.py"
click node_market_cache "https://github.com/santhosh144awc/openbull/blob/main/backend/services/market_data_cache.py"
click node_redis "https://github.com/santhosh144awc/openbull/blob/main/backend/utils/redis_client.py"
click node_database "https://github.com/santhosh144awc/openbull/blob/main/backend/database.py"
click node_event_bus "https://github.com/santhosh144awc/openbull/blob/main/backend/events/strategy_events.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_client_api,node_tradingview toneBlue
class node_web_routes,node_external_api,node_analytics,node_market_data toneAmber
class node_broker_plugins,node_broker_services,node_mode_dispatch,node_sandbox_service,node_sandbox_execution,node_sandbox_orders,node_sandbox_positions,node_strategy_webhook,node_strategy_engine,node_strategy_scheduler toneMint
class node_ws_proxy,node_market_cache,node_redis,node_database,node_event_bus toneRose
class node_user,node_broker_systems toneIndigo
```

## Components

### User Experience

- [Web App](https://github.com/santhosh144awc/openbull/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Clients](https://github.com/santhosh144awc/openbull/tree/main/frontend/src/api): `frontend/src/api`

### API and Analytics

- [Web Routes](https://github.com/santhosh144awc/openbull/tree/main/backend/routers): `backend/routers`
- [Trading API](https://github.com/santhosh144awc/openbull/tree/main/backend/api): `backend/api`
- [Options Analytics](https://github.com/santhosh144awc/openbull/tree/main/backend/services): `backend/services`
- [Market Data](https://github.com/santhosh144awc/openbull/blob/main/backend/services/market_data_service.py): `backend/services/market_data_service.py`

### Trading Runtime

- [Broker Plugins](https://github.com/santhosh144awc/openbull/tree/main/backend/broker): `backend/broker`
- [Broker Services](https://github.com/santhosh144awc/openbull/tree/main/backend/services): `backend/services`
- [Trading Mode](https://github.com/santhosh144awc/openbull/blob/main/backend/services/trading_mode_service.py): `backend/services/trading_mode_service.py`
- [Sandbox Service](https://github.com/santhosh144awc/openbull/blob/main/backend/services/sandbox_service.py): `backend/services/sandbox_service.py`
- [Sandbox Execution](https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/execution_engine.py): `backend/sandbox/execution_engine.py`
- [Sandbox Orders](https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/order_manager.py): `backend/sandbox/order_manager.py`
- [Sandbox Positions](https://github.com/santhosh144awc/openbull/blob/main/backend/sandbox/position_manager.py): `backend/sandbox/position_manager.py`
- [Strategy Webhooks](https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/webhook_handler.py): `backend/strategy/webhook_handler.py`
- [Strategy Engine](https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/engine.py): `backend/strategy/engine.py`
- [Strategy Scheduler](https://github.com/santhosh144awc/openbull/blob/main/backend/strategy/scheduler.py): `backend/strategy/scheduler.py`

### Platform Services

- [WebSocket Proxy](https://github.com/santhosh144awc/openbull/blob/main/backend/websocket_proxy/server.py): `backend/websocket_proxy/server.py`
- [Market Data Cache](https://github.com/santhosh144awc/openbull/blob/main/backend/services/market_data_cache.py): `backend/services/market_data_cache.py`
- [Redis Cache](https://github.com/santhosh144awc/openbull/blob/main/backend/utils/redis_client.py): `backend/utils/redis_client.py`
- [PostgreSQL](https://github.com/santhosh144awc/openbull/blob/main/backend/database.py): `backend/database.py`
- [Strategy Events](https://github.com/santhosh144awc/openbull/blob/main/backend/events/strategy_events.py): `backend/events/strategy_events.py`

### Other components

- **Trader**
- **Broker Systems**
- **TradingView**

## Connections

- Trader → Web App: uses (evidence: `README.md`)
- Web App → API Clients: requests through (evidence: `README.md`)
- API Clients → Web Routes: calls web API (evidence: `README.md`)
- API Clients → Trading API: calls trading API (evidence: `README.md`)
- Web Routes → Options Analytics: serves analytics (evidence: `README.md`)
- Trading API → Options Analytics: serves analytics (evidence: `README.md`)
- Trading API → Trading Mode: dispatches by mode (evidence: `README.md`)
- Web Routes → Trading Mode: dispatches by mode (evidence: `README.md`)
- Trading Mode → Broker Services: routes live calls (evidence: `README.md`)
- Trading Mode → Sandbox Service: routes sandbox calls (evidence: `README.md`)
- Broker Services → Broker Plugins: uses broker adapters (evidence: `README.md`)
- Broker Plugins → Broker Systems: connects to (evidence: `README.md`)
- Broker Plugins → WebSocket Proxy: publishes market data (evidence: `README.md`)
- WebSocket Proxy → Market Data Cache: feeds ticks (evidence: `backend/websocket_proxy/server.py`)
- Market Data → Market Data Cache: uses shared cache (evidence: `README.md`)
- Sandbox Service → Sandbox Execution: starts execution (evidence: `backend/services/sandbox_service.py`)
- Sandbox Execution → Sandbox Orders: fills orders (evidence: `backend/sandbox/execution_engine.py`)
- Sandbox Execution → Sandbox Positions: applies fills (evidence: `backend/sandbox/execution_engine.py`)
- Sandbox Execution → Market Data Cache: subscribes to ticks (evidence: `backend/sandbox/execution_engine.py`)
- Sandbox Service → Sandbox Orders: manages orders (evidence: `backend/services/sandbox_service.py`)
- Sandbox Service → Sandbox Positions: manages positions (evidence: `backend/services/sandbox_service.py`)
- TradingView → Strategy Webhooks: sends signals (evidence: `README.md`)
- Strategy Webhooks → Strategy Engine: dispatches actions (evidence: `backend/strategy/webhook_handler.py`)
- Strategy Scheduler → Strategy Engine: runs strategies (evidence: `backend/strategy/scheduler.py`)
- Strategy Engine → Strategy Events: emits events (evidence: `backend/strategy/engine.py`)
- Strategy Engine → Sandbox Service: places sandbox orders (evidence: `backend/strategy/engine.py`)
- Market Data Cache → Redis Cache: optional cache (evidence: `backend/services/market_data_cache.py`)
- Sandbox Service → PostgreSQL: persists sandbox state (evidence: `backend/services/sandbox_service.py`)
- Strategy Engine → PostgreSQL: stores strategy state (evidence: `backend/strategy/engine.py`)
