OrderFlow Analysis Pro

Real-time orderflow trading system — tick-level microstructure analysis, 5 pattern detectors, volume profile framing, state machine trade lifecycle, dual data feeds (MT5 + Bybit), FastAPI dashboard with WebSocket, Telegram alerts. Built on Fabio Testa's methodology.

Table of Contents

• What Is OrderFlow Analysis?
• System Overview
• Architecture
• The 5 Core Patterns
• Volume Profile Framing
• State Machine Trade Lifecycle
• Supported Instruments (29)
• Data Sources
• Dashboard
• Telegram Alerts
• Database
• Installation
• Configuration
• Usage
• Project Structure
• File Inventory
• API Reference
• Demo Mode
• Signal Output Examples
• How Pattern Detection Works
• Composite Scoring System
• Contributing
• License
• Disclaimer

What Is OrderFlow Analysis?

OrderFlow analysis reads market microstructure — the tick-by-tick footprint of buyers and sellers — to understand who is in control before price reflects it. Unlike traditional technical analysis that looks at candles and indicators, orderflow looks inside the candle:

Traditional Analysis              OrderFlow Analysis
─────────────────────             ─────────────────────
Looks at: OHLC candles             Looks at: Every tick (price + volume + side)
Timeframe: 1m, 5m, 1H             Timeframe: Tick-level (milliseconds)
Answers: What happened?            Answers: WHO did it and WHY?
Indicators: RSI, MACD, MA         Engines: Delta, Footprint, Volume Profile, Orderbook
Lagging: Yes (averages)            Leading: No (real-time microstructure)

Key Concepts

| Concept | What It Measures | Why It Matters | |---------|-----------------|----------------| | Delta | Buy volume minus sell volume per candle/level | Who is aggressive — buyers or sellers? | | Cumulative Delta | Running total of delta over time | Is buying/selling pressure building or fading? | | Footprint | Volume at each price level split by bid/ask | Where did the heavy trading happen inside the candle? | | Volume Profile | Total volume traded at each price over a session | Where is the "fair value" — POC, VAH, VAL? | | Orderbook | Limit orders waiting at each price level | Where are the walls? Thin levels = easy to sweep. | | Absorption | Aggressive volume with no price movement | Someone is defending a level with limit orders. | | Initiative | Aggressive volume WITH price movement | Institutional conviction pushing price. |

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OrderFlow Analysis Pro                              │
│                                                                             │
│  ┌──────────────────────┐     ┌──────────────────────────────────────┐      │
│  │   DATA SOURCES       │     │   ANALYTICS ENGINES (per instrument) │      │
│  │                      │     │                                      │      │
│  │  ┌────────┐ ┌──────┐ │     │  Volume Profile  ── POC, VAH, VAL,  │      │
│  │  │  MT5   │ │Bybit │ │────▶│  Delta Engine    ── vertical, horiz,│      │
│  │  │  Feed  │ │ Feed │ │     │  Footprint       ── bid/ask/level,  │      │
│  │  └────────┘ └──────┘ │     │  Orderbook       ── L2 depth, thin  │      │
│  └──────────────────────┘     └───────────────┬──────────────────────┘      │
│                                               │                              │
│  ┌────────────────────────────────────────────▼──────────────────────────┐  │
│  │                    5 PATTERN DETECTORS                                 │  │
│  │  Absorption · Initiative · Sweep · Exhaustion · Divergence            │  │
│  └────────────────────────────────────────────┬──────────────────────────┘  │
│                                               │                              │
│  ┌────────────────────────────────────────────▼──────────────────────────┐  │
│  │                    SIGNAL PROCESSING                                   │  │
│  │  Profile Framing (P/b/D shapes) → Qualified Levels → Daily Bias      │  │
│  │  Signal Aggregator (state machine) → Composite Score (0-100)         │  │
│  └────────────┬──────────────────────────────────┬───────────────────────┘  │
│               │                                  │                          │
│  ┌────────────▼──────────┐  ┌───────────────────▼────────────────────┐     │
│  │   Telegram Alerts     │  │   FastAPI Dashboard                    │     │
│  │   Entry/BE/Trail/Exit │  │   16 REST endpoints + WebSocket        │     │
│  │   Daily Bias updates  │  │   Charts, VP, Footprint, Orderbook     │     │
│  └───────────────────────┘  │   Scanner, Strategy Status, Tape       │     │
│                              └───────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │   SQLite Database (WAL mode)                                       │     │
│  │   ticks · candles · volumeprofiles · signals · tradejournal     │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Architecture

Data Flow Pipeline

┌─────────────┐
                     │  MT5 Feed   │──── Tick polling (100ms)
                     │  (495L)     │──── Market Book (DOM)
                     │             │──── Historical download
                     └──────┬──────┘
                            │
     ┌──────────────┐       │       ┌──────────────┐
     │  Bybit Feed  │───────┤       │   Database   │
     │  (209L)      │       ├──────▶│  (278L)      │
     │  WebSocket   │       │       │  SQLite WAL  │
     │  Free, no key│       │       └──────────────┘
     └──────────────┘       │
                            ▼
                   ┌─────────────────┐
                   │ Candle Builder  │ ← Tick → 1m aggregation
                   │ (133L)          │ ← Footprint per level
                   └────────┬────────┘
                            │
              ┌─────────────┼──────────────┐
              ▼             ▼              ▼
     ┌──────────────┐ ┌──────────┐ ┌──────────────┐
     │ Volume Prof. │ │  Delta   │ │  Footprint   │
     │ Engine (258L)│ │Engine    │ │  Engine      │
     │              │ │ (197L)   │ │ (181L)       │
     │ POC/VAH/VAL  │ │ Vert/Hor│ │ Bid/Ask/Lvl  │
     │ LVN/Shape    │ │ Cumul.   │ │ Imbalance    │
     └──────┬───────┘ └────┬─────┘ └──────┬───────┘
            │              │              │
            ▼              ▼              ▼
     ┌─────────────────────────────────────────┐
     │        ORDERBOOK TRACKER (208L)          │
     │  L2 depth · Thin levels · Consumptions  │
     │  Path of least resistance               │
     └──────────────────┬──────────────────────┘
                        │
        ┌───────┬───────┼───────┬───────┬───────┐
        ▼       ▼       ▼       ▼       ▼       │
   ┌────────┐┌────────┐┌──────┐┌────────┐┌────────┐
   │Absorp- ││Initia- ││Sweep ││Exhaus- ││Diverg- │
   │tion    ││tive    ││      ││tion    ││ence    │
   │(257L)  ││(133L)  ││(142L)││(228L)  ││(159L)  │
   └───┬────┘└───┬────┘└──┬───┘└───┬────┘└───┬────┘
       │         │        │        │         │
       └─────────┴────┬───┴────────┴─────────┘
                      ▼
            ┌─────────────────────┐
            │  Profile Framing    │ ← P/b/D shape → Daily Bias
            │  (343L)             │ ← Qualified Levels (VAH/VAL/POC/LVN/Merged)
            └─────────┬───────────┘
                      ▼
            ┌─────────────────────┐
            │  Signal Aggregator  │ ← State machine (6 states)
            │  (516L)             │ ← Composite scoring (0-100)
            │                     │ ← SL/TP calculation
            └──────┬──────────────┘
                   │
       ┌───────────┼───────────────┐
       ▼           ▼               ▼
 ┌──────────┐ ┌──────────┐  ┌───────────────┐
 │ Telegram │ │Dashboard │  │  Database     │
 │ Bot      │ │ FastAPI  │  │  Journal      │
 │ (202L)   │ │ (1015L)  │  │  Logging      │
 └──────────┘ └──────────┘  └───────────────┘

Module Dependency Graph

main.py (666L) ─── System orchestrator
    │
    ├── config/settings.py (946L) ─── 29 instrument configs, 10 config dataclasses
    │
    ├── data/
    │   ├── models.py (290L) ─── 7 dataclasses: Tick, Candle, Signal, TradeState...
    │   ├── candle_builder.py (133L) ─── Tick → 1m aggregation + footprint
    │   ├── mt5_feed.py (495L) ─── MT5 terminal: ticks, book, history
    │   ├── bybit_feed.py (209L) ─── Bybit WebSocket: trades + orderbook
    │   └── database.py (278L) ─── SQLite: 5 tables, WAL mode
    │
    ├── analytics/
    │   ├── volume_profile.py (258L) ─── POC/VAH/VAL/LVN/shape
    │   ├── delta.py (197L) ─── Vertical + horizontal + cumulative delta
    │   ├── footprint.py (181L) ─── Bid/ask per level, imbalance detection
    │   └── orderbook.py (208L) ─── L2 depth, thin levels, consumption tracking
    │
    ├── patterns/
    │   ├── absorption.py (257L) ─── Effort >> result detection
    │   ├── initiative.py (133L) ─── Effort = result (momentum)
    │   ├── sweep.py (142L) ─── Thin book displacement
    │   ├── exhaustion.py (228L) ─── Declining volume at extremes
    │   └── divergence.py (159L) ─── Price vs delta disagreement
    │
    ├── signals/
    │   ├── profile_framing.py (343L) ─── Daily bias + qualified levels
    │   └── aggregator.py (516L) ─── State machine + composite scoring
    │
    ├── alerts/
    │   └── telegram_bot.py (202L) ─── Telegram notifications
    │
    └── dashboard/
        ├── app.py (1015L) ─── FastAPI REST + WebSocket server
        ├── websocket_manager.py (186L) ─── 9-channel broadcast with throttling
        ├── demo_data.py (782L) ─── Deterministic demo data generator
        ├── main.py (35L) ─── Standalone launcher
        └── static/ ─── HTML/JS/CSS frontend (8 files, 4,420L)

The 5 Core Patterns

The system detects 5 microstructure patterns based on Fabio Testa's methodology. Each outputs a strength score (0-100) and directional bias (BUY/SELL).

Pattern Overview

┌─────────────────────────────────────────────────────────────────────┐
│                     5 PATTERN DETECTORS                             │
│                                                                     │
│  1. ABSORPTION        2. INITIATIVE       3. SWEEP                  │
│  Effort >> Result     Effort = Result     Thin Book Displacement    │
│  ██████████           ██████████          ██████                    │
│  ██████████  (no      ██████████  (price  ██░░░░░░░ (price          │
│  ██████████   move)   ██████████   moves) ░░░░░░░░   moves fast)   │
│  Buyers/Sellers       Directional         Low volume                │
│  defending level      conviction          through empty levels      │
│                                                                     │
│  4. EXHAUSTION        5. DIVERGENCE                                 │
│  Declining Effort     Price vs Delta Disagreement                   │
│  ██  █  █            Price: ↗↗↗ NEW HIGH                            │
│  █  █  ▓             Delta: ↗↗↘  (failing)                         │
│  █  ▓  ░             Trend reversal warning                        │
│  ▓  ░  ░                                                           │
│  Volume fading                                                     │
│  at extremes                                                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Detection Details

| # | Pattern | Detection Logic | Source Data | Signal Purpose | |---|---------|----------------|-------------|----------------| | 1 | Absorption | 2 methods: (a) Delta/price mismatch — positive delta + red candle = sellers absorbing, (b) High volume at level + low displacement + repeated attempts | Delta, Footprint, Price | Entry signal at VAH/VAL | | 2 | Initiative | 5 criteria: delta ≥ threshold, volume ≥ 1.5x average, body ≥ 3 ticks, delta/price aligned, one-sided imbalance bonus | Delta, Footprint, Volume | Break-even / trail trigger | | 3 | Sweep | Price through ≥3 thin orderbook levels + low volume per level + thin book confirmation (≥2 thin levels on swept side) | Orderbook, Price | Liquidity grab / reversal alert | | 4 | Exhaustion | Price trending + volume declining >30% + negative volume/delta trend + optional contrarian imbalance at extreme | Volume trend, Delta ROC, Footprint | Exit warning — momentum fading | | 5 | Divergence | Price new high/low but cumulative delta peak/trough fails to confirm (<80% of prior) | Price, Cumulative Delta peaks | Trend reversal warning |

Strength Score Calculation

| Pattern | Score Formula | Range | |---------|--------------|-------| | Absorption | (volume / minaggressive) 40 or (vol / minaggressive) 30 + attempts * 15 | 0-75 | | Initiative | (delta/threshold)20 + volaccel15 + bodyticks5 + imbalance_count10 | 0-50+ | | Sweep | levels15 + efficiency20 + displacement1000 + thin_confirm15 | 30-100 | | Exhaustion | 40 + |voltrend|5 + |deltaroc|5 + contrarian_bonus(20) | 40-70 | | Divergence | 30 + (1 - ratio)40 + pricenewextreme10 | 30-80 |

Volume Profile Framing (Daily Bias)

Implements Fabio Testa's profile shape analysis to determine the daily directional bias and identify qualified levels to trade from.

Profile Shapes

P-SHAPE (Buyers in Control)        b-SHAPE (Sellers in Control)
Volume │                           Volume │
  █    │                                  │ █
  ██   │                                  │ ██
  ███  │     POC > 65%                    │ ███     POC < 35%
  ████ │     Bias: LONG                   │ ████    Bias: SHORT
  █████│                                  │ ██████
───────┼────────── Price            ──────┼────────── Price
  VAL  │  POC  VAH                         VAH  POC  VAL
D-SHAPE (Balanced)                  DOUBLE DISTRIBUTION Volume │                           Volume │   █    │       █                          │ ████    ████   ██   │      ██                          │ ████    ████   ███  │     ███   POC ~50%               │  ░░░░░░░░░░   (valley)   ████ │    ████  Bias: NEUTRAL           │ ████    ████  Bias: TRANSITION ───────┼────────── Price            ──────┼────────────────── Price   VAL  │ POC │ VAH                         VAH₁  VAL₁  VAH₂  VAL₂

| Shape | POC Position | Bias | Confidence Base | Trading Plan | |-------|-------------|------|----------------|-------------| | P-shape | >65% from bottom | LONG | 40 + poc_pct×30 | Buyers in control, buy dips to VAL | | b-shape | <35% from bottom | SHORT | 40 + (1-poc_pct)×30 | Sellers in control, sell rallies to VAH | | D-shape | ~50% | NEUTRAL | 20 | Balanced, fade extremes | | Double Distribution | Bimodal (valley <50% of peaks) | NEUTRAL | 30 | Transition — watch for breakout |

Qualified Levels

┌─────────────────────────────────────────────────────────────────┐
│                  QUALIFIED LEVELS (Trade From These)             │
│                                                                  │
│  Price ▲                                                         │
│       │     ┌─── VAH (Value Area High) ─── SELL ZONE            │
│       │     │                                                    │
│       │     │    ┌── MERGED VAH ─── Strong SELL (str=70)        │
│       │     │    │  (confluent across multiple days)             │
│       │     │                                                    │
│       │     │  ┌── LVN (Low Volume Node) ─── Rebalancing        │
│       │     │  │  (price magnet — gaps fill fast)                │
│       │     │  │                                                │
│       │  ┌──┤  │  ┌── POC (Point of Control) ─── Pivot          │
│       │  │  │  │  │  (highest volume = fair value)               │
│       │  │  │  │  │                                            │
│       │  │  ├──┤  │  ┌── MERGED VAL ─── Strong BUY (str=70)    │
│       │  │  │  │  │  │  (confluent across multiple days)        │
│       │  │  │  │  │  │                                        │
│       │  └──┤  │  │  │  └── VAL (Value Area Low) ─── BUY ZONE  │
│       │     │  │  │                                           │
│       └─────┘  │  └────────────────────────────────────         │
│                │                                                 │
│  Confluence Bonus: +20 strength when level matches across days  │
│  Multi-day merge: overlapping profiles (>30% VA overlap) merged │
└─────────────────────────────────────────────────────────────────┘

Multi-Day Context Checks

| Check | What It Does | Effect | |-------|-------------|--------| | Value accepted higher | Current VA above prior VA | +15 confidence if aligned with bias | | VAH rejection | Price rejected at VAH across multiple days | Bias → WARNING, -10 penalty to composite score | | Failed auction ("hooks") | Bullish hook below VAL, bearish hook above VAH | Reduces confidence |

State Machine Trade Lifecycle

Every instrument runs an independent state machine. The system watches qualified levels, detects absorption entries, manages the trade through break-even and trailing stops, and auto-closes on strong exit signals.

╔══════════════════════════════════════════════════════════════════════════╗
║                    STATE MACHINE TRADE LIFECYCLE                        ║
╠══════════════════════════════════════════════════════════════════════════╣
║                                                                          ║
║   ┌─────────────────────────────────────────────────────────────┐        ║
║   │  NO ACTIVE TRADE                                            │        ║
║   │  Price approaches qualified level (strength >= 50)          │        ║
║   │  Aggregator auto-watches level                              │        ║
║   └────────────────────────┬────────────────────────────────────┘        ║
║                            │                                             ║
║                            ▼                                             ║
║   ┌─────────────────────────────────────────────────────────────┐        ║
║   │  WATCHING                                                   │        ║
║   │  Monitoring level for absorption or sweep signals           │        ║
║   └───────┬────────────────────────────────┬────────────────────┘        ║
║           │ ABSORPTION detected            │ SWEEP detected              ║
║           │ (composite >= 40)              │ (thin book displacement)    ║
║           ▼                                 ▼                            ║
║   ┌──────────────┐               ┌──────────────────────┐               ║
║   │ ABSORPTION   │               │ ALERT ONLY           │               ║
║   │ DETECTED     │               │ (sweep notification, │               ║
║   │ (transient)  │               │  no entry)           │               ║
║   └──────┬───────┘               └──────────────────────┘               ║
║          │ Entry signal sent, SL/TP calculated                            ║
║          ▼                                                                ║
║   ┌─────────────────────────────────────────────────────────────┐        ║
║   │  POSITION_OPEN                                              │        ║
║   │  Trade entered. Waiting for initiative (BE trigger)         │        ║
║   │  OR watching for exit warnings (exhaustion/divergence)      │        ║
║   └───────┬────────────────────────────────┬────────────────────┘        ║
║           │ INITIATIVE (same dir)          │ EXIT WARNING (opposite dir) ║
║           │ Move SL to entry price         │ str >= 70 → auto-close      ║
║           ▼                                 ▼                            ║
║   ┌──────────────┐               ┌──────────────────────┐               ║
║   │ BREAK_EVEN   │               │ CLOSED               │               ║
║   │ SL = entry   │               │ (auto-close on strong │               ║
║   │ Risk-free    │               │  exit signal)         │               ║
║   └──────┬───────┘               └──────────────────────┘               ║
║          │ INITIATIVE (same dir)                                             ║
║          │ Trail SL to candle extreme                                        ║
║          ▼                                                                  ║
║   ┌─────────────────────────────────────────────────────────────┐         ║
║   │  TRAILING                                                   │         ║
║   │  SL trails to candle low (longs) or high (shorts)           │         ║
║   │  Each new initiative print moves the trail                  │         ║
║   └───────┬────────────────────────────────┬────────────────────┘         ║
║           │ More INITIATIVE               │ EXIT WARNING (str>=70)        ║
║           │ Keep trailing                 │ or SL hit                     ║
║           ▼                                 ▼                              ║
║   ┌──────────────┐               ┌──────────────────────┐                ║
║   │ (loop back)  │               │ CLOSED               │                ║
║   │ TRAILING     │──────────────▶│ Trade logged to      │                ║
║   │              │               │ journal + Telegram   │                ║
║   └──────────────┘               └──────────────────────┘                ║
║                                                                            ║
╚══════════════════════════════════════════════════════════════════════════╝

Supported Instruments (29)

Each instrument has pre-tuned thresholds for all 5 pattern detectors, optimized for its volatility and tick size.

Index Futures (9)

| Instrument | Tick Size | Absorption Min Vol | Initiative Min Delta | VP Tick Size | Session | |-----------|-----------|-------------------|---------------------|-------------|---------| | NAS100 | 0.1 | 50 | 30 | 1.0 | NY Cash | | SP500 | 0.1 | 40 | 25 | 1.0 | NY Cash | | DJ30 | 1.0 | 40 | 25 | 5.0 | NY Cash | | UK100 | 0.1 | 30 | 20 | 1.0 | London | | DAX40 | 0.1 | 30 | 20 | 2.0 | London | | NIKKEI225 | 1.0 | 30 | 20 | 50.0 | Asian | | CAC40 | 0.1 | 25 | 18 | 1.0 | London | | ASX200 | 0.1 | 25 | 18 | 1.0 | Asian | | HK50 | 1.0 | 25 | 18 | 5.0 | Asian |

Metals, Energy, Crypto

| Instrument | Category | Tick Size | VP Tick Size | Session | |-----------|----------|-----------|-------------|---------| | XAUUSDT (Gold) | Metal | 0.01 | 0.50 | NY Cash | | XAGUSD (Silver) | Metal | 0.001 | 0.05 | Full Day | | USOIL | Energy | 0.01 | 0.10 | NY Cash | | UKOIL | Energy | 0.01 | 0.10 | London | | BTCUSDT | Crypto | 0.01 | 10.0 | Full Day |

Forex (10 Pairs)

| Instrument | Tick Size | VP Tick Size | Session | |-----------|-----------|-------------|---------| | EURUSD | 0.00001 | 0.0005 | Full Day | | GBPUSD | 0.00001 | 0.0005 | Full Day | | USDJPY | 0.001 | 0.05 | Full Day | | AUDUSD | 0.00001 | 0.0005 | Full Day | | USDCAD | 0.00001 | 0.0005 | Full Day | | USDCHF | 0.00001 | 0.0005 | Full Day | | NZDUSD | 0.00001 | 0.0005 | Full Day | | EURGBP | 0.00001 | 0.0005 | Full Day | | EURJPY | 0.001 | 0.05 | Full Day | | GBPJPY | 0.001 | 0.05 | Full Day |

US Stocks (7)

| Instrument | Tick Size | VP Tick Size | Session | |-----------|-----------|-------------|---------| | AAPL | 0.01 | 0.50 | NY Cash | | TSLA | 0.01 | 0.50 | NY Cash | | AMZN | 0.01 | 0.50 | NY Cash | | MSFT | 0.01 | 0.50 | NY Cash | | NVDA | 0.01 | 0.50 | NY Cash | | META | 0.01 | 0.50 | NY Cash | | GOOGL | 0.01 | 0.50 | NY Cash |

Data Sources

Dual Feed Architecture

┌────────────────────────────────────────────────────────────┐
│                     DATA SOURCE OPTIONS                     │
│                                                             │
│  ┌─────────────────────┐    ┌─────────────────────────┐   │
│  │      MT5 FEED        │    │      BYBIT FEED         │   │
│  │                      │    │                         │   │
│  │  Source: MT5 terminal│    │  Source: Bybit WebSocket│   │
│  │  Requires: Account   │    │  Requires: Nothing      │   │
│  │  Ticks: 100ms polling│    │  Ticks: Real-time stream│   │
│  │  Orderbook: DOM data │    │  Orderbook: 50 levels   │   │
│  │  History: Up to 3 days│   │  History: None          │   │
│  │  Aggressor: Buy/Sell │    │  Aggressor: Trade side  │   │
│  │  flag from MT5       │    │  from Bybit API         │   │
│  └──────────┬───────────┘    └───────────┬─────────────┘   │
│             │                             │                  │
│             │  DATA_SOURCE = "MT5"        │  "BYBIT"         │
│             │  DATA_SOURCE = "BOTH" ──────┘                  │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────────────────────┐                    │
│  │  Symbol Auto-Discovery (MT5)        │                    │
│  │  200+ broker-specific name variants │                    │
│  │  e.g. USTEC, USTECm, NAS100, US100 │                    │
│  └─────────────────────────────────────┘                    │
└────────────────────────────────────────────────────────────┘

MT5 Symbol Mapping

The system auto-discovers instruments across 200+ broker-specific naming variants:

| Internal | MT5 Symbol | Alternatives | |----------|-----------|-------------| | NAS100 | USTECm | USTEC, NAS100, US100, NQ100, NAS100USD... | | XAUUSDT | XAUUSDm | XAUUSD, GOLD... | | EURUSD | EURUSDm | EURUSD, EUR/USD... | | BTCUSDT | BTCUSDm | BTCUSD, BTC/USD... |

Dashboard

Frontend Components (8 custom JS modules)

┌──────────────────────────────────────────────────────────────────────┐
│                     ORDERFLOW DASHBOARD                              │
│                                                                      │
│  ┌───────────────────────────────────┐  ┌────────────────────────┐  │
│  │        PRICE CHART (app.js)       │  │   VOLUME PROFILE       │  │
│  │   TradingView lightweight-charts  │  │   Horizontal bars      │  │
│  │   Signal markers overlay:         │  │   POC, VAH, VAL marks  │  │
│  │   ▲ Absorption (teal)            │  │   Shape classification  │  │
│  │   ▲ Initiative (green)           │  │   LVN markers          │  │
│  │   ▲ Sweep (purple)               │  └────────────────────────┘  │
│  │   ● Exhaustion (yellow)                                        │
│  │   ● Divergence (orange)          ┌────────────────────────┐    │
│  │   ● Entry/Exit markers           │   FOOTPRINT CHART      │    │
│  └───────────────────────────────────┘│   Bid/Ask per level   │    │
│                                       │   Imbalance highlights │    │
│  ┌───────────────────────────────────┐└────────────────────────┘  │
│  │        SIGNAL CARDS (signals.js)  │                             │
│  │   Real-time trade recommendations │  ┌────────────────────────┐│
│  │   Entry/SL/TP/RR display          │  │  ORDERBOOK DEPTH       ││
│  │   Pattern breakdown               │  │  Bid/Ask ladder        ││
│  │   Grade (A+/A/B/C)                │  │  Thin level markers    ││
│  └───────────────────────────────────┘  │  Spread indicator      ││
│                                         └────────────────────────┘│
│  ┌───────────────────────────────────┐  ┌────────────────────────┐│
│  │  PERFORMANCE (performance.js)     │  │  TIME & SALES (tape.js)││
│  │  Win rate, PnL, RR distribution   │  │  Tick-by-tick feed     ││
│  │  Trade history                    │  │  Big trade highlights  ││
│  └───────────────────────────────────┘  └────────────────────────┘│
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │              MICROSTRUCTURE (microstructure.js)               │  │
│  │  Market state · Session · Absorption · Delta · Exhaustion     │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

WebSocket Channels (9)

| Channel | Data | Throttle | Priority | |---------|------|----------|----------| | tick | Price, size, side | 200ms | High | | candle | OHLCV + delta | None (immediate) | Critical | | signal | AggregatedSignal | None (immediate) | Critical | | trade_state | TradePhase transitions | None (immediate) | Critical | | volume_profile | POC/VAH/VAL/shape | None | Normal | | bias | DailyBias updates | None | Normal | | orderbook | L2 depth + imbalance | 500ms | Normal | | delta | Cumulative delta history | 200ms | Normal | | stats | System-wide per-instrument | 5000ms | Low |

Telegram Alerts

Automated notifications for every trade lifecycle event:

| Alert Type | Trigger | Content | |-----------|---------|---------| | ENTRY SIGNAL | Absorption at qualified level, composite ≥40 | Direction, score, pattern, delta, volume, bias, entry/SL/TP/RR | | BREAK EVEN | First initiative auction after entry | SL moved to entry price — risk-free trade | | TRAIL UPDATE | Subsequent initiative prints | New SL level, trail progress | | EXIT SIGNAL | Trade closed (SL hit or auto-close) | PnL ticks, RR achieved, trade summary | | EXIT WARNING | Exhaustion or divergence detected | Pattern details, strength, direction warning | | DAILY BIAS | New VP shape computed | Shape, direction, confidence, POC/VAH/VAL, qualified levels |

Database

SQLite Schema (5 Tables)

┌─────────────────────────────────────────────────────────────────┐
│                    orderflow_data.db (WAL mode)                  │
│                                                                  │
│  ┌──────────┐ ┌──────────┐ ┌────────────────┐ ┌──────────┐    │
│  │  ticks    │ │ candles  │ │ volume_profiles│ │ signals  │    │
│  ├──────────┤ ├──────────┤ ├────────────────┤ ├──────────┤    │
│  │ id (PK)  │ │ id (PK)  │ │ id (PK)        │ │ id (PK)  │    │
│  │instrument│ │instrument│ │ instrument     │ │instrument│    │
│  │timestamp │ │timestamp │ │ session_date   │ │timestamp │    │
│  │ price    │ │timeframe │ │ poc, vah, val  │ │sig_type  │    │
│  │ size     │ │ OHLCV    │ │ total_volume   │ │direction │    │
│  │ side     │ │ buy/sell │ │ shape          │ │price_lvl │    │
│  │ tradeid │ │ delta    │ │ pocpos_pct    │ │ strength │    │
│  └──────────┘ │footprint │ │ lvn (JSON)     │ │details   │    │
│               └──────────┘ │ volatprice   │ │  (JSON)  │    │
│                             └────────────────┘ └──────────┘    │
│                                                                  │
│  ┌──────────────┐                                               │
│  │ trade_journal│                                               │
│  ├──────────────┤                                               │
│  │ id (PK)      │                                               │
│  │ instrument   │                                               │
│  │ direction    │                                               │
│  │ entry/exit   │                                               │
│  │  time (ms)   │                                               │
│  │ entry/exit   │                                               │
│  │  price       │                                               │
│  │ SL, TP       │                                               │
│  │ pnl_ticks    │                                               │
│  │ rr_ratio     │                                               │
│  │ signals(JSON)│                                               │
│  │ notes        │                                               │
│  └──────────────┘                                               │
│                                                                  │
│  Indexes: (instrument, timestamp), (instrument, session_date)   │
│  PRAGMA: journal_mode=WAL, synchronous=NORMAL                   │
└─────────────────────────────────────────────────────────────────┘

Installation

Prerequisites

• Python 3.10+
• MetaTrader 5 terminal (for MT5 feed) OR Bybit (free, no account needed)

Setup

# Clone the repository
git clone https://github.com/mahmoud20138/OrderFlow-Analysis-Pro.git
cd OrderFlow-Analysis-Pro
Install dependencies
pip install -e .
Or install manually
pip install websockets aiohttp pandas numpy scipy \
    python-telegram-bot plotly kaleido aiosqlite pytz pyyaml

Quick Start (Bybit — No Account Needed)

# 1. Set data source to BYBIT in config
2. Run the system
python -m orderflow_system.main
3. Open dashboard
http://localhost:8080

Quick Start (MT5)

# 1. Open MetaTrader 5 terminal
2. Configure credentials in config/settings.py
3. Run the system
python -m orderflow_system.main

Dashboard Only (Demo Mode)

# Run dashboard with deterministic demo data
python -m orderflow_system.dashboard

Configuration

All configuration is in orderflow_system/config/settings.py:

# Data source: "MT5", "BYBIT", or "BOTH"
DATA_SOURCE = DataSource.BYBIT
MT5 credentials (only if using MT5 feed)
MT5 = MT5Config(
    login=12345678,
    password="your_password",
    server="YourBroker-Server",
    pollintervalms=100,       # Tick polling frequency
    enable_book=True,           # Enable market book (DOM)
    downloadhistorydays=3,    # Download M1 history for warmup
)
Telegram alerts
TELEGRAM = TelegramConfig(
    bottoken="yourbot_token",
    chatid="yourchat_id",
    sendchartsnapshots=True,
)
Dashboard
DASHBOARD = DashboardConfig(
    enabled=True,
    host="0.0.0.0",
    port=8080,
    log_level="warning",
)
Database
DBPATH = "orderflowdata.db"
LOG_LEVEL = "INFO"

Per-Instrument Threshold Tuning

Each instrument has its own config with tuned thresholds. Example for NAS100:

AbsorptionConfig(
    minaggressivevolume=50,      # Min volume to qualify as absorption
    maxpricedisplacement_ticks=2, # Max ticks price can move
    rollingwindowseconds=30,      # Lookback window
    min_attempts=2,                 # Min repeated attempts at level
    bigtradefilter=10,            # Volume threshold for "big" trade
)
InitiativeConfig(     mindeltathreshold=30,          # Min delta to qualify     volumeaccelerationmin=1.5,     # Must be 1.5x average volume     minpricedisplacement_ticks=3,  # Min body size     deltapricealignment=True,      # Delta must align with candle direction )

Usage

Start the System

python -m orderflow_system.main

The system will:

• Connect to configured data source(s)
• Download historical bars (MT5) or connect to live feed (Bybit)
• Build initial volume profiles from historical data
• Start 5 pattern detectors for all 29 instruments
• Compute daily bias and qualified levels
• Auto-watch strong levels (strength ≥ 50)
• Begin state machine monitoring
• Send Telegram alerts on signals
• Serve dashboard at http://localhost:8080

Dashboard Endpoints

# View all instruments
curl http://localhost:8080/api/instruments
Get scanner ranking (all pairs by trade proximity)
curl http://localhost:8080/api/scanner
Get strategy status for NAS100
curl http://localhost:8080/api/strategy-status/NAS100USDT
Get volume profile
curl http://localhost:8080/api/volume-profile/NAS100USDT?days=5
Get daily bias
curl http://localhost:8080/api/bias/NAS100USDT
Get signal history
curl http://localhost:8080/api/signals/NAS100USDT?limit=50
Get active trade state
curl http://localhost:8080/api/trade/NAS100USDT

Project Structure

orderflow_system/
├── main.py                          # System orchestrator (666L)
├── init.py                      # Package init
├── test_integration.py              # Integration tests (314L)
│
├── config/
│   └── settings.py                  # 29 instrument configs, 10 config dataclasses (946L)
│
├── data/
│   ├── models.py                    # 7 dataclasses: Tick, Candle, Signal, TradeState... (290L)
│   ├── candle_builder.py            # Tick → 1m candle aggregation (133L)
│   ├── bybit_feed.py                # Bybit WebSocket feed (209L)
│   ├── mt5_feed.py                  # MT5 terminal feed with auto-discovery (495L)
│   └── database.py                  # SQLite persistence, 5 tables (278L)
│
├── analytics/
│   ├── volume_profile.py            # POC, VAH, VAL, LVN, shape classification (258L)
│   ├── delta.py                     # Vertical, horizontal, cumulative delta (197L)
│   ├── footprint.py                 # Bid/ask per level, imbalance detection (181L)
│   └── orderbook.py                 # L2 depth, thin levels, consumption tracking (208L)
│
├── patterns/
│   ├── absorption.py                # Effort >> result detection (257L)
│   ├── initiative.py                # Effort = result (momentum) (133L)
│   ├── sweep.py                     # Thin book displacement (142L)
│   ├── exhaustion.py                # Declining volume at extremes (228L)
│   └── divergence.py                # Price vs delta disagreement (159L)
│
├── signals/
│   ├── profile_framing.py           # Daily bias + qualified levels (343L)
│   └── aggregator.py                # State machine + composite scoring (516L)
│
├── alerts/
│   └── telegram_bot.py              # Telegram notifications (202L)
│
└── dashboard/
    ├── app.py                       # FastAPI REST + WebSocket (1015L)
    ├── websocket_manager.py         # 9-channel broadcast manager (186L)
    ├── demo_data.py                 # Deterministic demo data generator (782L)
    ├── main.py                  # Standalone launcher (35L)
    └── static/
        ├── index.html               # Main HTML shell (121L)
        ├── app.js                   # TradingView charts + WebSocket (939L)
        ├── style.css                # Dashboard styling (566L)
        ├── footprint.js             # Canvas footprint chart (700L)
        ├── signals.js               # Signal recommendation cards (479L)
        ├── performance.js           # Performance analytics (599L)
        ├── orderbook.js             # Orderbook depth ladder (318L)
        ├── microstructure.js        # Microstructure indicators (417L)
        └── tape.js                  # Time & sales (281L)

File Inventory

| Category | Files | Python Lines | JS/CSS/HTML Lines | Total Lines | |----------|-------|-------------|-------------------|-------------| | Config | 1 | 946 | — | 946 | | Data | 5 | 1,405 | — | 1,405 | | Analytics | 4 | 844 | — | 844 | | Patterns | 5 | 919 | — | 919 | | Signals | 2 | 859 | — | 859 | | Alerts | 1 | 202 | — | 202 | | Dashboard | 4 + 8 static | 1,818 | 4,420 | 6,238 | | Main + Tests | 2 | 980 | — | 980 | | Total | ~32 | ~7,973 | ~4,420 | ~12,393 |

API Reference

REST Endpoints (16)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | / | Dashboard UI | | GET | /api/instruments | Active instruments with stats + trade phase | | GET | /api/scanner | All pairs ranked by trade proximity (priority 0-118) | | GET | /api/markers/{symbol} | TradingView chart markers for signal events | | GET | /api/candles/{symbol} | OHLCV candle history (params: count, tf, range) | | GET | /api/volume-profile/{symbol} | Volume profile with POC/VAH/VAL (params: days, range) | | GET | /api/bias/{symbol} | Daily bias + qualified levels | | GET | /api/signals/{symbol} | Signal history (params: limit) | | GET | /api/trade/{symbol} | Active trade state | | GET | /api/strategy-status/{symbol} | 6-step Fabio methodology checklist | | GET | /api/orderbook/{symbol} | Current L2 orderbook (params: levels) | | GET | /api/delta/{symbol} | Cumulative delta history (params: count, tf, range) | | GET | /api/footprint/{symbol} | Footprint chart data (params: tf, range) | | GET | /api/tape/{symbol} | Time & sales (params: count) | | GET | /api/microstructure/{symbol} | Microstructure snapshot | | GET | /api/stats | System-wide stats |

Strategy Status Labels

| Status | Meaning | |--------|---------| | NO_DATA | No data received yet | | NO_LEVELS | No qualified levels identified | | WAITINGFORPRICE | Levels exist, price not nearby | | ATLEVELSCANNING | Price near a qualified level | | WATCHING | Aggregator actively watching a level | | ENTRY_READY | Absorption detected, composite score ≥ threshold | | IN_TRADE | Position open | | BREAK_EVEN | SL moved to entry | | TRAILING | SL trailing on initiative | | IDLE | No active monitoring |

Scanner Priority Scoring

| State | Base Score | Bonus | |-------|-----------|-------| | IN_TRADE | 100 | +3 per completed step | | TRAILING | 95 | +3 per completed step | | BREAK_EVEN | 90 | +3 per completed step | | ENTRY_READY | 85 | +3 per completed step | | ATLEVELSCANNING | 70 | +3 per completed step | | WATCHING | 60 | +3 per completed step | | WAITINGFORPRICE | 40 | — | | NO_LEVELS | 20 | — | | NO_DATA | 10 | — | | OFFLINE | 5 | — | | IDLE | 0 | — |

Demo Mode

The system includes a deterministic demo data generator that produces realistic data for all 29 instruments — no data feed required. Runs via:

python -m orderflow_system.dashboard

Generates:

• OHLCV candles via random walk (seeded per symbol/timeframe)
• Volume profiles with Gaussian distributions
• Cumulative delta with bar-level noise
• Orderbooks with ~15% thin levels
• 6 institutional-grade signal templates with narrative, thesis, edge, invalidation, HTF context, session, regime, MTF confluence, blockers, and grade

Signal Quality Grading

| Grade | Score | Meaning | |-------|-------|---------| | A+ | ≥85 | Exceptional — multiple confirmations, high confluence | | A | ≥70 | Strong — solid pattern + level + bias alignment | | B | ≥55 | Good — pattern detected, partial confluence | | C | <55 | Weak — pattern only, consider skipping |

Signal Output Examples

Entry Signal

ENTRY SIGNAL: NAS100 LONG
  Composite Score: 72/100
  Pattern: ABSORPTION at VAL (17,845.50)
  Delta: +1,250 (buyers absorbing sells)
  Volume: 3.2x average
  Bias: P-shape (LONG), confidence 85%
  Entry: 17,846.00 | SL: 17,830.00 | TP: 17,878.00
  R:R: 1:2.0
  Grade: A

Daily Bias Update

DAILY BIAS: NAS100
  Shape: P-shape (buyers in control)
  Direction: LONG | Confidence: 85%
  POC: 17,852.00 | VAH: 17,890.00 | VAL: 17,820.00
  LVN: [17,835.00, 17,868.00]
  Qualified Levels: VAL (buy, str=50), MERGED_VAL (buy, str=70)

Strategy Status

STRATEGY STATUS: NAS100
  Step 1: Profile Framing    ✓ P-shape, LONG, 85%
  Step 2: Qualified Levels   ✓ VAL=17820, MERGED_VAL=17815
  Step 3: Price at Level     ✓ Price 17825 near VAL
  Step 4: Absorption Scan    ✓ Detected, strength 72
  Step 5: Entry Decision     ✓ Composite 72 ≥ 40
  Step 6: Trade Management   ⏳ Waiting for initiative
  Overall: ENTRY_READY

How Pattern Detection Works

Absorption Detection (2 Methods)

Method 1: Delta/Close Mismatch
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Delta: +500 (buying)     Delta: -400 (selling)
  Candle: RED (closed ↓)   Candle: GREEN (closed ↑)
  → SELLERS absorbing      → BUYERS absorbing
  → Signal: SELL            → Signal: BUY
Strength = (|delta| / minaggressivevolume) * 40
Method 2: Level Absorption ━━━━━━━━━━━━━━━━━━━━━━━━━━   Track aggressive volume at each price level over rolling window.   If volume >= minaggressive AND attempts >= minattempts:     → ABSORPTION signal     Strength = (vol / min_aggressive)  30 + attempts  15

Initiative Detection (5 Criteria)

┌──────────────────────────────────────────────────────────┐
│  INITIATIVE = Aggressive Conviction                      │
│                                                          │
│  All 5 must be met:                                      │
│  ┌─────────────────────────────────────────────┐        │
│  │ 1. |delta| >= mindeltathreshold (30)       │  ✓/✗  │
│  │ 2. volume / avg >= volume_accel (1.5x)       │  ✓/✗  │
│  │ 3. bodysize >= mindisplacement (3 ticks)   │  ✓/✗  │
│  │ 4. delta direction == candle direction       │  ✓/✗  │
│  │ 5. Bonus: one-sided imbalance prints (>3.0)  │  +10  │
│  └─────────────────────────────────────────────┘        │
│                                                          │
│  Strength = delta20 + accel15 + body5 + imbalance10 │
└──────────────────────────────────────────────────────────┘

Composite Scoring System

The SignalAggregator computes a composite score (0-100) that determines whether a signal becomes a trade:

┌──────────────────────────────────────────────────────────┐
│              COMPOSITE SCORE CALCULATION                  │
│                                                          │
│  Signal Weight (varies by pattern):                      │
│  ┌────────────────┬────────┐                             │
│  │ Absorption     │  ×0.30 │  ← Highest weight          │
│  │ Divergence     │  ×0.25 │                             │
│  │ Initiative     │  ×0.20 │                             │
│  │ Sweep          │  ×0.20 │                             │
│  │ Other          │  ×0.15 │                             │
│  └────────────────┴────────┘                             │
│                                                          │
│  Level Strength:     ×0.25                               │
│  Bias Alignment:     ×0.20 (if direction matches)        │
│  Bias WARNING:       -10   (penalty if VA rejected)      │
│                                                          │
│  Final: clamped to [0, 100]                              │
│  Minimum to enter:   40 (configurable)                   │
└──────────────────────────────────────────────────────────┘

SL/TP Calculation

| Scenario | SL (LONG) | TP (LONG) | SL (SHORT) | TP (SHORT) | |----------|-----------|-----------|------------|------------| | With bias | val - (vah-val)×0.1 | vah | vah + (vah-val)×0.1 | val | | No bias | price × 0.997 (-0.3%) | price × 1.006 (+0.6%) | price × 1.003 (+0.3%) | price × 0.994 (-0.6%) |

Contributing

See CONTRIBUTING.md for guidelines. PRs welcome — bug fixes, new pattern detectors, additional instruments, dashboard improvements.

License

MIT — use freely in personal and commercial projects.

Disclaimer

This software is for educational and research purposes only. It is not financial advice. Trading involves substantial risk of loss. Past performance is not indicative of future results. Use at your own risk.