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 · volume_profiles · signals · trade_journal     │     │
│  └────────────────────────────────────────────────────────────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

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 / min_aggressive) * 40 or (vol / min_aggressive) * 30 + attempts * 15	0-75
Initiative	(delta/threshold)*20 + vol_accel*15 + body_ticks*5 + imbalance_count*10	0-50+
Sweep	levels*15 + efficiency*20 + displacement*1000 + thin_confirm*15	30-100
Exhaustion	`40 +	vol_trend
Divergence	30 + (1 - ratio)*40 + price_new_extreme*10	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 │    │
│  │ trade_id │ │ delta    │ │ poc_pos_pct    │ │ strength │    │
│  └──────────┘ │footprint │ │ lvn (JSON)     │ │details   │    │
│               └──────────┘ │ vol_at_price   │ │  (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",
    poll_interval_ms=100,       # Tick polling frequency
    enable_book=True,           # Enable market book (DOM)
    download_history_days=3,    # Download M1 history for warmup
)

# Telegram alerts
TELEGRAM = TelegramConfig(
    bot_token="your_bot_token",
    chat_id="your_chat_id",
    send_chart_snapshots=True,
)

# Dashboard
DASHBOARD = DashboardConfig(
    enabled=True,
    host="0.0.0.0",
    port=8080,
    log_level="warning",
)

# Database
DB_PATH = "orderflow_data.db"
LOG_LEVEL = "INFO"

Per-Instrument Threshold Tuning

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

AbsorptionConfig(
    min_aggressive_volume=50,      # Min volume to qualify as absorption
    max_price_displacement_ticks=2, # Max ticks price can move
    rolling_window_seconds=30,      # Lookback window
    min_attempts=2,                 # Min repeated attempts at level
    big_trade_filter=10,            # Volume threshold for "big" trade
)

InitiativeConfig(
    min_delta_threshold=30,          # Min delta to qualify
    volume_acceleration_min=1.5,     # Must be 1.5x average volume
    min_price_displacement_ticks=3,  # Min body size
    delta_price_alignment=True,      # Delta must align with candle direction
)

---

Usage

Start the System

python -m orderflow_system.main

The system will:

1. Connect to configured data source(s)
2. Download historical bars (MT5) or connect to live feed (Bybit)
3. Build initial volume profiles from historical data
4. Start 5 pattern detectors for all 29 instruments
5. Compute daily bias and qualified levels
6. Auto-watch strong levels (strength ≥ 50)
7. Begin state machine monitoring
8. Send Telegram alerts on signals
9. 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
WAITING_FOR_PRICE	Levels exist, price not nearby
AT_LEVEL_SCANNING	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
AT_LEVEL_SCANNING	70	+3 per completed step
WATCHING	60	+3 per completed step
WAITING_FOR_PRICE	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| / min_aggressive_volume) * 40

Method 2: Level Absorption
━━━━━━━━━━━━━━━━━━━━━━━━━━
  Track aggressive volume at each price level over rolling window.
  If volume >= min_aggressive AND attempts >= min_attempts:
    → ABSORPTION signal
    Strength = (vol / min_aggressive) * 30 + attempts * 15

Initiative Detection (5 Criteria)

┌──────────────────────────────────────────────────────────┐
│  INITIATIVE = Aggressive Conviction                      │
│                                                          │
│  All 5 must be met:                                      │
│  ┌─────────────────────────────────────────────┐        │
│  │ 1. |delta| >= min_delta_threshold (30)       │  ✓/✗  │
│  │ 2. volume / avg >= volume_accel (1.5x)       │  ✓/✗  │
│  │ 3. body_size >= min_displacement (3 ticks)   │  ✓/✗  │
│  │ 4. delta direction == candle direction       │  ✓/✗  │
│  │ 5. Bonus: one-sided imbalance prints (>3.0)  │  +10  │
│  └─────────────────────────────────────────────┘        │
│                                                          │
│  Strength = delta*20 + accel*15 + body*5 + imbalance*10 │
└──────────────────────────────────────────────────────────┘

---

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.