# minculusofia-wq/scanner-polymarket-bot-automatique architecture

> Architecture diagram of the GitHub repository minculusofia-wq/scanner-polymarket-bot-automatique, 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/scanner-polymarket-bot-automatique
- Repository: https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique

## Overview

Polymarket Scanner + Bot is a market-opportunity dashboard and automated trading system. Users inspect multi-strategy signals and quantitative analyses, then configure or operate the bot in paused, semi-automatic, or full-automatic mode; the bot scans, evaluates risk, executes trades, and manages positions and exits. The graph includes the documented whale, arbitrage, fade, Monte Carlo, volume-spike, and combined strategies, plus news and history capabilities. Some feature links are documented rather than visible in sampled call sites; those links cite the README.

Main entry points: [`backend/app/services/trading/bot_engine.py`](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/bot_engine.py) (Bot Orchestrator), [`backend/app/services/trading/signal_scanner.py`](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/signal_scanner.py) (Unified Scanner), [`frontend/src/app/page.tsx`](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/app/page.tsx) (Scanner Dashboard), [`backend/app/api/trading_bot.py`](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/trading_bot.py) (Bot API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Scanner Dashboard<br/>[page.tsx]"]
  node_bot_ui["Bot Controls"]
  node_ws_hook["Live Updates<br/>[useWebSocket.ts]"]
end

subgraph group_scanner["Opportunity Scanner"]
  node_scanner["Unified Scanner<br/>[signal_scanner.py]"]
  node_whales["Whale Detection<br/>[detector.py]"]
  node_whale_tracker["Whale Tracking<br/>[whale_tracker.py]"]
  node_arb_fade["Arbitrage and Fade"]
  node_volume["Volume Analysis<br/>[analyzer.py]"]
  node_monte["Monte Carlo Analysis<br/>[calculator.py]"]
  node_combined["Combined Signals<br/>[combiner.py]"]
  node_news["News Aggregation<br/>[aggregator.py]"]
  node_polymarket_client["Market Data Client<br/>[client.py]"]
end

subgraph group_trading["Automated Trading"]
  node_bot_engine["Bot Orchestrator<br/>[bot_engine.py]"]
  node_confluence["Confluence Detection"]
  node_regime["Market Regime<br/>[market_regime.py]"]
  node_entry["Entry Optimizer<br/>[entry_optimizer.py]"]
  node_sizer["Smart Sizing<br/>[smart_sizer.py]"]
  node_risk["Risk Manager<br/>[risk_manager.py]"]
  node_performance["Strategy Performance"]
  node_feedback["Signal Feedback<br/>[feedback_loop.py]"]
  node_executor["Order Executor<br/>[executor.py]"]
  node_positions["Position Manager"]
  node_exits["Exit Manager<br/>[exit_manager.py]"]
end

subgraph group_platform["API and Persistence"]
  node_signal_api["Signal API<br/>[signals.py]"]
  node_bot_api["Bot API<br/>[trading_bot.py]"]
  node_market_api["Market API<br/>[markets.py]"]
  node_news_api["News API<br/>[news.py]"]
  node_history_api["History API<br/>[history.py]"]
  node_monte_api["Monte Carlo API<br/>[monte_carlo.py]"]
  node_volume_api["Volume API<br/>[volume.py]"]
  node_whale_api["Whale API<br/>[whales.py]"]
  node_database[("Database<br/>[database.py]")]
end

node_user(("User"))
node_polymarket{{"Polymarket APIs"}}

node_user -.->|"views markets"| node_dashboard
node_user -.->|"controls bot"| node_bot_ui
node_dashboard -.->|"requests signals"| node_signal_api
node_bot_ui -.->|"controls bot"| node_bot_api
node_dashboard -.->|"requests markets"| node_market_api
node_dashboard -.->|"requests analysis"| node_monte_api
node_dashboard -.->|"requests news"| node_news_api
node_dashboard -.->|"requests history"| node_history_api
node_ws_hook -.->|"provides updates"| node_dashboard
node_bot_api -->|"controls"| node_bot_engine
node_bot_api -->|"reads positions"| node_positions
node_bot_api -->|"checks executor"| node_executor
node_signal_api -->|"uses tracking"| node_whale_tracker
node_monte_api -->|"calculates edge"| node_monte
node_news_api -->|"aggregates news"| node_news
node_whale_api -->|"reads tracking"| node_whale_tracker
node_history_api -->|"reads history"| node_database
node_scanner -->|"scans whales"| node_whales
node_scanner -->|"scans strategies"| node_arb_fade
node_scanner -->|"scans volume"| node_volume
node_scanner -->|"calculates edge"| node_monte
node_scanner -.->|"scans combined"| node_combined
node_scanner -->|"fetches markets"| node_polymarket_client
node_whales -->|"fetches trades"| node_polymarket_client
node_volume -->|"fetches market data"| node_polymarket_client
node_polymarket_client -->|"requests data"| node_polymarket
node_bot_engine -->|"runs scans"| node_scanner
node_bot_engine -->|"detects agreement"| node_confluence
node_bot_engine -->|"weights signals"| node_regime
node_bot_engine -->|"validates entries"| node_entry
node_bot_engine -->|"sizes positions"| node_sizer
node_bot_engine -->|"checks risk"| node_risk
node_bot_engine -->|"tracks performance"| node_performance
node_bot_engine -->|"updates feedback"| node_feedback
node_bot_engine -->|"executes orders"| node_executor
node_bot_engine -->|"manages positions"| node_positions
node_bot_engine -->|"manages exits"| node_exits
node_exits -->|"places exit orders"| node_executor
node_exits -->|"reads positions"| node_positions
node_executor -.->|"places orders"| node_polymarket
node_history_api -->|"queries store"| node_database
node_positions -->|"stores positions"| node_database
node_risk -->|"reads exposure"| node_database

click node_dashboard "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/app/page.tsx"
click node_bot_ui "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/components/TradingBotPanel.tsx"
click node_ws_hook "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_signal_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/signals.py"
click node_bot_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/trading_bot.py"
click node_market_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/markets.py"
click node_news_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/news.py"
click node_history_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/history.py"
click node_monte_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/monte_carlo.py"
click node_volume_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/volume.py"
click node_whale_api "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/whales.py"
click node_scanner "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/signal_scanner.py"
click node_whales "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/whale/detector.py"
click node_whale_tracker "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/whale_tracker.py"
click node_volume "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/volume/analyzer.py"
click node_monte "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/monte_carlo/calculator.py"
click node_combined "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/signals/combiner.py"
click node_news "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/news/aggregator.py"
click node_bot_engine "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/bot_engine.py"
click node_confluence "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/confluence_detector.py"
click node_regime "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/market_regime.py"
click node_entry "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/entry_optimizer.py"
click node_sizer "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/smart_sizer.py"
click node_risk "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/risk_manager.py"
click node_performance "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/strategy_performance.py"
click node_feedback "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/feedback_loop.py"
click node_executor "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/executor.py"
click node_positions "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/position_manager.py"
click node_exits "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/exit_manager.py"
click node_polymarket_client "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/polymarket/client.py"
click node_database "https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/core/database.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_dashboard,node_bot_ui,node_ws_hook,node_user toneBlue
class node_scanner,node_whales,node_whale_tracker,node_arb_fade,node_volume,node_monte,node_combined,node_news,node_polymarket_client toneAmber
class node_bot_engine,node_confluence,node_regime,node_entry,node_sizer,node_risk,node_performance,node_feedback,node_executor,node_positions,node_exits,node_polymarket toneMint
class node_signal_api,node_bot_api,node_market_api,node_news_api,node_history_api,node_monte_api,node_volume_api,node_whale_api,node_database toneRose
```

## Components

### Dashboard

- [Scanner Dashboard](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Bot Controls](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/components/TradingBotPanel.tsx): `frontend/src/components/TradingBotPanel.tsx`
- [Live Updates](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`

### Opportunity Scanner

- [Unified Scanner](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/signal_scanner.py): `backend/app/services/trading/signal_scanner.py`
- [Whale Detection](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/whale/detector.py): `backend/app/services/whale/detector.py`
- [Whale Tracking](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/whale_tracker.py): `backend/app/services/whale_tracker.py`
- **Arbitrage and Fade**
- [Volume Analysis](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/volume/analyzer.py): `backend/app/services/volume/analyzer.py`
- [Monte Carlo Analysis](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/monte_carlo/calculator.py): `backend/app/services/monte_carlo/calculator.py`
- [Combined Signals](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/signals/combiner.py): `backend/app/services/signals/combiner.py`
- [News Aggregation](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/news/aggregator.py): `backend/app/services/news/aggregator.py`
- [Market Data Client](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/polymarket/client.py): `backend/app/services/polymarket/client.py`

### Automated Trading

- [Bot Orchestrator](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/bot_engine.py): `backend/app/services/trading/bot_engine.py`
- [Confluence Detection](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/confluence_detector.py): `backend/app/services/trading/confluence_detector.py`
- [Market Regime](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/market_regime.py): `backend/app/services/trading/market_regime.py`
- [Entry Optimizer](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/entry_optimizer.py): `backend/app/services/trading/entry_optimizer.py`
- [Smart Sizing](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/smart_sizer.py): `backend/app/services/trading/smart_sizer.py`
- [Risk Manager](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/risk_manager.py): `backend/app/services/trading/risk_manager.py`
- [Strategy Performance](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/strategy_performance.py): `backend/app/services/trading/strategy_performance.py`
- [Signal Feedback](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/feedback_loop.py): `backend/app/services/trading/feedback_loop.py`
- [Order Executor](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/executor.py): `backend/app/services/trading/executor.py`
- [Position Manager](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/position_manager.py): `backend/app/services/trading/position_manager.py`
- [Exit Manager](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/services/trading/exit_manager.py): `backend/app/services/trading/exit_manager.py`

### API and Persistence

- [Signal API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/signals.py): `backend/app/api/signals.py`
- [Bot API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/trading_bot.py): `backend/app/api/trading_bot.py`
- [Market API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/markets.py): `backend/app/api/markets.py`
- [News API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/news.py): `backend/app/api/news.py`
- [History API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/history.py): `backend/app/api/history.py`
- [Monte Carlo API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/monte_carlo.py): `backend/app/api/monte_carlo.py`
- [Volume API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/volume.py): `backend/app/api/volume.py`
- [Whale API](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/api/whales.py): `backend/app/api/whales.py`
- [Database](https://github.com/minculusofia-wq/scanner-polymarket-bot-automatique/blob/main/backend/app/core/database.py): database · `backend/app/core/database.py`

### Other components

- **User**
- **Polymarket APIs**

## Connections

- User → Scanner Dashboard: views markets
- User → Bot Controls: controls bot
- Scanner Dashboard → Signal API: requests signals
- Bot Controls → Bot API: controls bot
- Scanner Dashboard → Market API: requests markets
- Scanner Dashboard → Monte Carlo API: requests analysis
- Scanner Dashboard → News API: requests news
- Scanner Dashboard → History API: requests history
- Live Updates → Scanner Dashboard: provides updates
- Bot API → Bot Orchestrator: controls (evidence: `backend/app/api/trading_bot.py`)
- Bot API → Position Manager: reads positions (evidence: `backend/app/api/trading_bot.py`)
- Bot API → Order Executor: checks executor (evidence: `backend/app/api/trading_bot.py`)
- Signal API → Whale Tracking: uses tracking (evidence: `backend/app/api/signals.py`)
- Monte Carlo API → Monte Carlo Analysis: calculates edge (evidence: `backend/app/api/monte_carlo.py`)
- News API → News Aggregation: aggregates news (evidence: `backend/app/api/news.py`)
- Whale API → Whale Tracking: reads tracking (evidence: `backend/app/api/whales.py`)
- History API → Database: reads history (evidence: `backend/app/api/history.py`)
- Unified Scanner → Whale Detection: scans whales (evidence: `backend/app/services/trading/signal_scanner.py`)
- Unified Scanner → Arbitrage and Fade: scans strategies (evidence: `backend/app/services/trading/signal_scanner.py`)
- Unified Scanner → Volume Analysis: scans volume (evidence: `backend/app/services/trading/signal_scanner.py`)
- Unified Scanner → Monte Carlo Analysis: calculates edge (evidence: `backend/app/services/trading/signal_scanner.py`)
- Unified Scanner → Combined Signals: scans combined
- Unified Scanner → Market Data Client: fetches markets (evidence: `backend/app/services/trading/signal_scanner.py`)
- Whale Detection → Market Data Client: fetches trades (evidence: `backend/app/services/whale/detector.py`)
- Volume Analysis → Market Data Client: fetches market data (evidence: `backend/app/services/volume/analyzer.py`)
- Market Data Client → Polymarket APIs: requests data (evidence: `backend/app/services/polymarket/client.py`)
- Bot Orchestrator → Unified Scanner: runs scans (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Confluence Detection: detects agreement (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Market Regime: weights signals (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Entry Optimizer: validates entries (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Smart Sizing: sizes positions (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Risk Manager: checks risk (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Strategy Performance: tracks performance (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Signal Feedback: updates feedback
- Bot Orchestrator → Order Executor: executes orders (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Position Manager: manages positions (evidence: `backend/app/services/trading/bot_engine.py`)
- Bot Orchestrator → Exit Manager: manages exits (evidence: `backend/app/services/trading/bot_engine.py`)
- Exit Manager → Order Executor: places exit orders (evidence: `backend/app/services/trading/exit_manager.py`)
- Exit Manager → Position Manager: reads positions (evidence: `backend/app/services/trading/exit_manager.py`)
- Order Executor → Polymarket APIs: places orders
- History API → Database: queries store (evidence: `backend/app/api/history.py`)
- Position Manager → Database: stores positions (evidence: `backend/app/services/trading/position_manager.py`)
- Risk Manager → Database: reads exposure (evidence: `backend/app/services/trading/risk_manager.py`)