# minculusofia-wq/apex-predator architecture

> Architecture diagram of the GitHub repository minculusofia-wq/apex-predator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minculusofia-wq/apex-predator
- Repository: https://github.com/minculusofia-wq/apex-predator

## Overview

APEX PREDATOR is a Polymarket crypto-market trading bot with Gabagool arbitrage and Smart Ape momentum strategies, Kelly sizing, optimization, and operational controls. Its principal workflow is market scanning, opportunity analysis, strategy evaluation and order execution through Polymarket; a web API and terminal UI provide control and monitoring. The README documents the high-level routing and capabilities, while sampled source confirms scanner/API behavior and supporting modules. Some strategy-to-executor wiring is unsampled, so uncertain links are omitted or marked unverified.

Main entry points: [`core/scanner.py`](https://github.com/minculusofia-wq/apex-predator/blob/main/core/scanner.py) (Market scanner), [`web/server.py`](https://github.com/minculusofia-wq/apex-predator/blob/main/web/server.py) (Web API and dashboard), [`core/gabagool.py`](https://github.com/minculusofia-wq/apex-predator/blob/main/core/gabagool.py) (Gabagool arbitrage), [`core/executor.py`](https://github.com/minculusofia-wq/apex-predator/blob/main/core/executor.py) (Order executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market discovery"]
  node_scanner["Market scanner<br/>[scanner.py]"]
  node_public_api["Public market API"]
  node_gamma["Gamma market data<br/>[gamma_client.py]"]
  node_websocket["Price feed<br/>[websocket_feed.py]"]
  node_analyzer["Opportunity analyzer<br/>[analyzer.py]"]
  node_binance["Binance prices<br/>[binance_client.py]"]
end

subgraph group_trading["Trading strategies"]
  node_gabagool["Gabagool arbitrage<br/>[gabagool.py]"]
  node_smart_ape["Smart Ape momentum<br/>[smart_ape.py]"]
  node_kelly["Kelly sizing<br/>[kelly.py]"]
  node_optimizer["Auto optimizer<br/>[auto_optimizer.py]"]
end

subgraph group_operations["Execution and controls"]
  node_executor["Order executor<br/>[executor.py]"]
  node_private_api["Private trading API"]
  node_order_queue["Order queue<br/>[order_queue.py]"]
  node_resilience["Resilience controls<br/>[resilience.py]"]
  node_lifecycle["Health and metrics<br/>[lifecycle.py]"]
  node_settings["Trading configuration<br/>[trading_params.py]"]
end

subgraph group_interfaces["Operator interfaces"]
  node_web["Web API and dashboard<br/>[server.py]"]
  node_terminal["Terminal UI<br/>[app.py]"]
end

subgraph group_simulation["Paper trading"]
  node_paper_config["Simulation configuration<br/>[config.py]"]
  node_paper_executor["Paper executor<br/>[paper_executor.py]"]
  node_fill_sim["Fill simulator<br/>[fill_simulator.py]"]
  node_capital["Virtual capital<br/>[capital_manager.py]"]
  node_trade_store[("Trade history store<br/>[trade_store.py]")]
  node_reporter["Paper reports<br/>[reporter.py]"]
end

node_operator(("Trader"))
node_markets(("Polymarket markets"))

node_operator -->|"starts bot"| node_scanner
node_markets -->|"market data"| node_public_api
node_scanner -->|"fetches markets"| node_public_api
node_scanner -->|"fetches listings"| node_gamma
node_scanner -->|"receives updates"| node_websocket
node_scanner -.->|"triggers analysis"| node_analyzer
node_analyzer -.->|"evaluates opportunities"| node_gabagool
node_analyzer -.->|"evaluates opportunities"| node_smart_ape
node_gabagool -->|"submits trades"| node_executor
node_smart_ape -->|"submits trades"| node_executor
node_gabagool -.->|"sizes positions"| node_kelly
node_smart_ape -.->|"sizes positions"| node_kelly
node_optimizer -->|"tunes strategy"| node_gabagool
node_optimizer -->|"tunes strategy"| node_smart_ape
node_optimizer -->|"reads prices"| node_binance
node_executor -.->|"places orders"| node_private_api
node_executor -.->|"queues orders"| node_order_queue
node_executor -.->|"uses safeguards"| node_resilience
node_operator -->|"controls bot"| node_web
node_web -->|"controls strategy"| node_gabagool
node_web -->|"controls strategy"| node_smart_ape
node_web -->|"controls optimizer"| node_optimizer
node_web -->|"configures sizing"| node_kelly
node_operator -->|"operates bot"| node_terminal
node_terminal -.->|"controls scanning"| node_scanner
node_settings -->|"configures strategy"| node_gabagool
node_settings -->|"serves configuration"| node_web
node_scanner -.->|"reports health"| node_lifecycle
node_paper_executor -->|"simulates fills"| node_fill_sim
node_paper_executor -->|"allocates capital"| node_capital
node_paper_executor -->|"persists trades"| node_trade_store
node_fill_sim -->|"uses settings"| node_paper_config
node_capital -->|"uses settings"| node_paper_config
node_reporter -->|"reads history"| node_trade_store
node_reporter -->|"reads capital stats"| node_capital

click node_scanner "https://github.com/minculusofia-wq/apex-predator/blob/main/core/scanner.py"
click node_public_api "https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/polymarket_public.py"
click node_gamma "https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/gamma_client.py"
click node_websocket "https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/websocket_feed.py"
click node_analyzer "https://github.com/minculusofia-wq/apex-predator/blob/main/core/analyzer.py"
click node_binance "https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/binance_client.py"
click node_gabagool "https://github.com/minculusofia-wq/apex-predator/blob/main/core/gabagool.py"
click node_smart_ape "https://github.com/minculusofia-wq/apex-predator/blob/main/core/smart_ape.py"
click node_kelly "https://github.com/minculusofia-wq/apex-predator/blob/main/core/kelly.py"
click node_optimizer "https://github.com/minculusofia-wq/apex-predator/blob/main/core/auto_optimizer.py"
click node_executor "https://github.com/minculusofia-wq/apex-predator/blob/main/core/executor.py"
click node_private_api "https://github.com/minculusofia-wq/apex-predator/blob/main/api/private/polymarket_private.py"
click node_order_queue "https://github.com/minculusofia-wq/apex-predator/blob/main/core/order_queue.py"
click node_resilience "https://github.com/minculusofia-wq/apex-predator/blob/main/core/resilience.py"
click node_lifecycle "https://github.com/minculusofia-wq/apex-predator/blob/main/core/lifecycle.py"
click node_settings "https://github.com/minculusofia-wq/apex-predator/blob/main/config/trading_params.py"
click node_web "https://github.com/minculusofia-wq/apex-predator/blob/main/web/server.py"
click node_terminal "https://github.com/minculusofia-wq/apex-predator/blob/main/ui/app.py"
click node_paper_config "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/config.py"
click node_paper_executor "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/paper_executor.py"
click node_fill_sim "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/fill_simulator.py"
click node_capital "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/capital_manager.py"
click node_trade_store "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/trade_store.py"
click node_reporter "https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/reporter.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_scanner,node_public_api,node_gamma,node_websocket,node_analyzer,node_binance toneBlue
class node_gabagool,node_smart_ape,node_kelly,node_optimizer toneAmber
class node_executor,node_private_api,node_order_queue,node_resilience,node_lifecycle,node_settings toneMint
class node_web,node_terminal toneRose
class node_paper_config,node_paper_executor,node_fill_sim,node_capital,node_trade_store,node_reporter,node_operator,node_markets toneIndigo
```

## Components

### Market discovery

- [Market scanner](https://github.com/minculusofia-wq/apex-predator/blob/main/core/scanner.py): `core/scanner.py`
- [Public market API](https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/polymarket_public.py): `api/public/polymarket_public.py`
- [Gamma market data](https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/gamma_client.py): `api/public/gamma_client.py`
- [Price feed](https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/websocket_feed.py): `api/public/websocket_feed.py`
- [Opportunity analyzer](https://github.com/minculusofia-wq/apex-predator/blob/main/core/analyzer.py): `core/analyzer.py`
- [Binance prices](https://github.com/minculusofia-wq/apex-predator/blob/main/api/public/binance_client.py): `api/public/binance_client.py`

### Trading strategies

- [Gabagool arbitrage](https://github.com/minculusofia-wq/apex-predator/blob/main/core/gabagool.py): `core/gabagool.py`
- [Smart Ape momentum](https://github.com/minculusofia-wq/apex-predator/blob/main/core/smart_ape.py): `core/smart_ape.py`
- [Kelly sizing](https://github.com/minculusofia-wq/apex-predator/blob/main/core/kelly.py): `core/kelly.py`
- [Auto optimizer](https://github.com/minculusofia-wq/apex-predator/blob/main/core/auto_optimizer.py): `core/auto_optimizer.py`

### Execution and controls

- [Order executor](https://github.com/minculusofia-wq/apex-predator/blob/main/core/executor.py): `core/executor.py`
- [Private trading API](https://github.com/minculusofia-wq/apex-predator/blob/main/api/private/polymarket_private.py): `api/private/polymarket_private.py`
- [Order queue](https://github.com/minculusofia-wq/apex-predator/blob/main/core/order_queue.py): `core/order_queue.py`
- [Resilience controls](https://github.com/minculusofia-wq/apex-predator/blob/main/core/resilience.py): `core/resilience.py`
- [Health and metrics](https://github.com/minculusofia-wq/apex-predator/blob/main/core/lifecycle.py): `core/lifecycle.py`
- [Trading configuration](https://github.com/minculusofia-wq/apex-predator/blob/main/config/trading_params.py): `config/trading_params.py`

### Operator interfaces

- [Web API and dashboard](https://github.com/minculusofia-wq/apex-predator/blob/main/web/server.py): `web/server.py`
- [Terminal UI](https://github.com/minculusofia-wq/apex-predator/blob/main/ui/app.py): `ui/app.py`

### Paper trading

- [Simulation configuration](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/config.py): `core/paper_trading/config.py`
- [Paper executor](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/paper_executor.py): `core/paper_trading/paper_executor.py`
- [Fill simulator](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/fill_simulator.py): `core/paper_trading/fill_simulator.py`
- [Virtual capital](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/capital_manager.py): `core/paper_trading/capital_manager.py`
- [Trade history store](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/trade_store.py): `core/paper_trading/trade_store.py`
- [Paper reports](https://github.com/minculusofia-wq/apex-predator/blob/main/core/paper_trading/reporter.py): `core/paper_trading/reporter.py`

### Other components

- **Trader**
- **Polymarket markets**

## Connections

- Trader → Market scanner: starts bot (evidence: `README.md`)
- Polymarket markets → Public market API: market data (evidence: `README.md`)
- Market scanner → Public market API: fetches markets (evidence: `core/scanner.py`)
- Market scanner → Gamma market data: fetches listings (evidence: `core/scanner.py`)
- Market scanner → Price feed: receives updates (evidence: `core/scanner.py`)
- Market scanner → Opportunity analyzer: triggers analysis (evidence: `core/analyzer.py`)
- Opportunity analyzer → Gabagool arbitrage: evaluates opportunities
- Opportunity analyzer → Smart Ape momentum: evaluates opportunities
- Gabagool arbitrage → Order executor: submits trades (evidence: `README.md`)
- Smart Ape momentum → Order executor: submits trades (evidence: `README.md`)
- Gabagool arbitrage → Kelly sizing: sizes positions
- Smart Ape momentum → Kelly sizing: sizes positions
- Auto optimizer → Gabagool arbitrage: tunes strategy (evidence: `README.md`)
- Auto optimizer → Smart Ape momentum: tunes strategy (evidence: `README.md`)
- Auto optimizer → Binance prices: reads prices (evidence: `core/auto_optimizer.py`)
- Order executor → Private trading API: places orders
- Order executor → Order queue: queues orders
- Order executor → Resilience controls: uses safeguards
- Trader → Web API and dashboard: controls bot (evidence: `README.md`)
- Web API and dashboard → Gabagool arbitrage: controls strategy (evidence: `web/server.py`)
- Web API and dashboard → Smart Ape momentum: controls strategy (evidence: `web/server.py`)
- Web API and dashboard → Auto optimizer: controls optimizer (evidence: `README.md`)
- Web API and dashboard → Kelly sizing: configures sizing (evidence: `web/server.py`)
- Trader → Terminal UI: operates bot (evidence: `README.md`)
- Terminal UI → Market scanner: controls scanning (evidence: `ui/app.py`)
- Trading configuration → Gabagool arbitrage: configures strategy (evidence: `core/gabagool.py`)
- Trading configuration → Web API and dashboard: serves configuration (evidence: `web/server.py`)
- Market scanner → Health and metrics: reports health
- Paper executor → Fill simulator: simulates fills (evidence: `core/paper_trading/paper_executor.py`)
- Paper executor → Virtual capital: allocates capital (evidence: `core/paper_trading/paper_executor.py`)
- Paper executor → Trade history store: persists trades (evidence: `core/paper_trading/paper_executor.py`)
- Fill simulator → Simulation configuration: uses settings (evidence: `core/paper_trading/fill_simulator.py`)
- Virtual capital → Simulation configuration: uses settings (evidence: `core/paper_trading/capital_manager.py`)
- Paper reports → Trade history store: reads history (evidence: `core/paper_trading/reporter.py`)
- Paper reports → Virtual capital: reads capital stats (evidence: `core/paper_trading/reporter.py`)