Functional Workflows & Diagrams
Functional Reference
How Intellect FinLab works end-to-end — every major workflow, decision flow, and system behaviour with flow diagrams. From market open to trade close to session wealth accounting.
Full Trade LifecycleSignal Pipeline
Risk Gates (8 checks)LP Shield Flows
Wealth CompoundingAlert Routing
Backtest PipelineAI Discovery
⚡
Core Principle
Every decision in the system is deterministic, auditable, and recoverable. No signal is acted on without passing all risk gates. No trade closes without updating the lifecycle DB. No session ends without reconciling the wealth model against the plan.
End-to-End System Flow — Market Open to Wealth Updated
Market DataIBKR bars
→
80+ Scannerstechnical signals
→
Signal Poolthread-safe store
→
Strategy Enginepattern + Veera Rules
→
Risk Gates8 checks
→
Executionstrike pick · submit
→
LP Shieldmonitor · protect
→
Close & Wealthaudit · compound
01
📡
Market Data Ingestion
IBKR price feeds stream real-time bar data across all 6 instruments. FreshnessMonitor flags stale feeds before they influence decisions.
02
🔍
Signal Scanning — 80+ Scanners
Each scanner evaluates technical conditions on its timeframe. 4-layer defence stack: config gate → market hours → cooldown → bar identity. Signal published to pool on pass.
03
🧠
Strategy Evaluation — Hunter Loop
Hunter Loop wakes instantly when pool.publish() fires. Evaluates all enabled strategies in priority order. Pattern match + Veera Rules + context/trigger confirmation.
04
⛩️
Risk Preflight — 8 Gates
Market gate · existing position · daily loss limit · max positions · gamma exposure · staleness guard · capital sufficiency · option viability. ALL must pass.
05
📐
Options Selection Pipeline
Delta-target strike selection via GreekCache + LiquidityFilter. DeltaStrikePicker finds closest delta match. ExpiryUtils resolves 0DTE contract.
06
⚡
Order Submission
Market BUY via ib_async. OrderStatusCache provides O(1) confirmation. Fill event dispatched by V2FillDispatcher to lifecycle bridge → DB write.
07
🛡️
Loss Protection Daemon
LP thread arms immediately on fill. Grace period → fast poll (5s/10min) → normal poll (30s). Rules 1–6 active. Limit sell T1 placed and monitored.
08
💰
Close & Wealth Accounting
On SELL_FILLED: lifecycle DB → CLOSED → WealthManager updates capital → milestone check → TradeDiary → ws/wealth WebSocket → Telegram + email alerts.
1
Build Container
build_container() instantiates all 40+ services and wires dependencies via DI. Container stored on FastAPI app state.
2
DB Path Authority
DBPathAuthority validates all 3 DB paths exist and are accessible. Detects stale duplicates or mismatched environment paths.
3
Startup Invariant Check
StartupInvariantChecker validates config integrity, environment consistency, and required table presence.
4
Apply Config
RuntimeControlService loads all config domains from config DB into live services. Establishes initial state.
5
Runtime Sync
RuntimeSyncWorker starts IBKR state sync loop. Heartbeat established — notify_tick() begins firing on bar events.
6
Delta Ladder Pre-Activation
DeltaLadderWorker pre-activates ES, SPX, NQ symbols so greek data is available before first scanner fires.
7
Lifecycle Reload
TradeLifecycleService reloads all active (non-closed) trades from lifecycle DB into RuntimeStore. In-progress positions resume monitoring.
8
Promotion Sync
PromotionSyncWorker imports any un-promoted legacy diary entries into the modern lifecycle DB.
9
Broker Reconcile
BrokerTradeReconciler (delayed 8s to let IBKR settle) reconciles TWS fills with lifecycle DB. Catches any fills that landed during restart.
10
Trade Story Service Init
TradeStoryService initialises timeline service. System is now fully trade-ready. [STARTUP COMPLETE] logged.
⏱️
Micro-Timing Breakdown
Scanner fire T+0ms → Preflight complete T+3ms → SafeLock acquired T+5ms → Strike picked T+8ms → Order submitted T+12ms → Fill confirmed T+35ms → LP armed T+36ms → Telegram alert T+~800ms (async, non-blocking)
Trade Stage Progression — Full Lifecycle
SCANNER SIGNAL
→
STRATEGY PASS
→
HUNTER OK
→
OPTION SELECTED
→
WEALTH SIZED
→
BUY SUBMITTED
→
BUY FILLED
→
SELL SUBMITTED
→
SELL FILLED
→
CLOSED
→
WEALTH UPDATED
| Category | Representative Scanners | Logic Type |
|---|---|---|
| Fibonacci | SPX_FIB_1HR_CALL/PUT · ES_FIB_CALL_1HR | State-based — fires while price is in fib zone |
| EMA Cross | SPX_V3_CALL/PUT · ES_CALL_V3 · NQ_CALL_V3 | Cross-based — fires on the actual cross bar |
| MACD | SPX_10MIN_MACD_UP/DOWN · SPX_1HR_MACD_UP | Cross-based — MACD signal line cross |
| Momentum / SMI | SPX_10MIN_MOMENTUM_UP/DOWN · SPX_4HR_STOCHASTIC | State-based — SMI Ergodic level threshold |
| ADX / Trend | SPX_ADX_5M · ES_ADX_5M | Threshold — ADX > 20 strength gate |
| RSI | SPX_15M_RSI_OVERSOLD | Threshold — RSI level reversal |
| Zone Breakout | SPX_ZONE_BREAKOUT_CALL/PUT · ES_ZONE_BREAKOUT | State — price outside consolidation box |
| Trifecta | SPX_EMA21_TRIFECTA_CALL/PUT | Multi-condition AND — EMA21 + MACD + momentum |
| Correlated | SPY_21_200_CALL/PUT · VIX_21_200_CALL/PUT | Cross-based on correlated instrument |
Strategy Evaluation Cycle
Signal Poolsnapshot()
→
Strategy Listpriority order
→
Pattern Matchcall/put in pool?
→
Veera Rulesmarket regime pre-filter
→
Hunter Gatecontext + trigger
→
Risk Preflightall 8 checks
🕐
Multi-Scanner Confirmation Window
If a strategy requires 2+ scanner patterns (e.g. SPX_FIB_1HR_CALL AND SPX_ADX_5M), both must appear in the Signal Pool within scanner_confirmation_window_minutes (default 5 min) of each other. This prevents stale signals from creating false entries.
| # | Gate | Check | Fail Action |
|---|---|---|---|
| 1 | Market Gate | Is the trading gate OPEN? | Block — log MARKET_GATE_CLOSED, alert if configured |
| 2 | Existing Position | No open position in same instrument + direction | Block — DUPLICATE_POSITION logged |
| 3 | Daily Loss Limit | Today's PnL > configured daily loss ceiling | Block — auto-close market gate, CRITICAL alert |
| 4 | Max Open Positions | Open count < configured max | Block — wait for existing position to close |
| 5 | Gamma Exposure | Net gamma within configured upper/lower bounds | Block — GAMMA_OVEREXPOSED |
| 6 | Staleness Guard | Price feed freshness within threshold | Block — STALE_PRICE_FEED |
| 7 | Capital Sufficiency | WealthManager has capital for ≥ 1 contract | Block — INSUFFICIENT_CAPITAL |
| 8 | Option Viability | Greeks loaded, IV not extreme, bid price available | Block — retry after greek freshness |
🔀 Risk Gate Decision Tree — Sequential Evaluation
Strategy PASS
Gate OPEN?
YES ✓
NO → BLOCK
No Dup Position?
YES ✓
NO → BLOCK
Loss Limit OK?
YES ✓
NO → CLOSE GATE
Max Positions?
OK ✓
FULL → WAIT
Gamma OK?
OK ✓
OVER → BLOCK
Capital OK?
OK ✓
LOW → BLOCK
✓ EXECUTE
LP Daemon Lifecycle
BUY FILLEDLP.start()
→
Grace Periodprotect sell 15 min
→
Fast Pollevery 5s · first 10min
→
Normal Pollevery 30s · after 10min
→
3:30PM GateEOD handling
→
EOD Forcemarket sell 15:55
3:30PM Handling Modes
| Mode | Action | Use When |
|---|---|---|
modify_to_entry | Atomic cancel-replace: moves limit sell to entry + breakeven % (default +1%). Ensures exit at breakeven or better. | Default — protects against late-day reversal |
alert_only | Sends Telegram + email alert only. Sell order unchanged. Operator decides action. | Manual oversight preference |
force_close | Market sell at exactly 3:30PM ET. No price protection. | Risk-limited environments only |
| Exit Pathway | Trigger | Order Type |
|---|---|---|
| Target Hit (T1/T2/T3) | Limit sell placed at entry fills at target price | Limit sell — placed at entry, monitored by LP |
| Trail Stop | V2PositionWatchdog detects reversal below trail threshold | Atomic cancel-replace to stop price |
| EOD Force Close | Rule 5 — 15:55 ET non-negotiable | Market sell — no exceptions |
| Manual Close | Operator presses Close button in dashboard Positions page | Limit sell at mid-price |
Post-Close Actions — Automatic Chain
SELL_FILLED
→
CLOSEDlifecycle DB
→
WEALTH_UPDATEDcapital + ladder
→
TradeDiarylog with greeks
→
Alert DispatchTelegram + email
→
ws/wealth firesdashboard updates
Config Change Propagation
Operator UIConfig Console
→
FastAPI RoutePUT /config/:domain
→
ConfigServicewrite to config.db
→
TTL Expires5s max lag
→
Services Re-readchange is live
| Parameter | Purpose | Recommended |
|---|---|---|
delta_call | Target delta for call strike selection. Higher = more ITM. | 0.30 |
delta_put | Target delta for put strike selection. | 0.25 |
trade_preference | Primary instrument for contract sizing | ES |
contract_months | 0 = 0DTE · 1 = weekly · 2 = monthly | 0 (0DTE) |
entry_start_time | Earliest allowed entry time (ET) | 09:45 |
entry_end_time | Latest allowed entry (LP handles anything after) | 15:00 |
gamma_upper_bound | Max net gamma — long gamma limit | 0.15 |
gamma_lower_bound | Min net gamma — negative exposure tolerance | −0.10 |
call_side_enabled | Allow call entries without affecting puts | true |
put_side_enabled | Allow put entries without affecting calls | true |
🔑
Key Strategy Config Fields
scanner_patterns_call/put — which scanners trigger entry · target_profit_pct — exit target (23%) · shield — rapid_shield or day_shield · wealth_model — capital plan override · veera_rules_enabled + individual rule toggles · hunterloop.mode — standard or context_plus_trigger · priority — evaluation order (1 = highest)
| Parameter | Level | Purpose |
|---|---|---|
enabled | Per-scanner | Enable/disable — disabled scanner emits no signals and no alerts |
cooldown | Per-scanner | Min seconds between fires — overrides timeframe default |
email | Per-scanner | Email alert on fire (subject to global email_all toggle) |
telegram | Per-scanner | Telegram alert on fire (subject to global telegram_all toggle) |
email_all | Global | Master email switch — OFF disables all scanner emails regardless |
telegram_all | Global | Master Telegram switch — OFF disables all scanner Telegrams |
es_only_mode | Global | Restrict to ES / rapid / test scanners only — useful for off-hours |
Wealth Accounting Cycle — Triggered on Every Trade Close
Trade CLOSEDPnL confirmed
→
WealthManagerupdate current_capital
→
Milestone CheckT1 / T2 / T3 reached?
→
Week Advance?target hit → next week
→
TradeDiarylog with greeks
→
ws/wealth firesdashboard updates
WM235K — Weekly Progression Example
📈 WM235K — Compounding Curve · Plan vs Actual (52 weeks)
Plan
Actual
Projected
Start: $35,000
Week 17 (now): $41,280
Plan at W17: $39,800
+$1,480 ahead of plan ↗
Year target: $500K+
W1$35,000 → $35,800Trade start · base size✓ Complete
W2$35,800 → $36,900T1 milestone hit · size up✓ Complete
W3$36,900 → $38,100T2 milestone hit · size up✓ Complete
W4$38,100 → $39,800Active · T3 pending↗ In Progress
W5$39,800 → $41,600Projected— Upcoming
W52→ $500,000+Annual target🏆 Goal
IN-APPBUY FILLED: SPX 5940C @ 4.20 × 2 — immediately visible in dashboard Live Feed
WEBSOCKETws/orders fires BUY_FILLED event → React dashboard updates live positions
TELEGRAM📲 BOUGHT SPX 5940C @ 4.20 · delta 0.30 · T1: 5.17 (+23%) · Trade #47
EMAILHTML email dispatched: order_buy template with full greek table · commission · slippage
TELEGRAM📲 SOLD SPX 5940C @ 5.18 · +$196 · +23.3% · Hold 21m 47s · T1 target hit
EMAILHTML email: order_sell template with PnL breakdown · hold time · close reason · wealth ladder level
SCANNER BOT📡 SPX_FIB_1HR_CALL fired · score 87 · SPX @ 5938 · separate Telegram channel
💡
Dual-Bot Architecture
The Scanner Bot sends scanner fire events to a separate Telegram channel — keeping your main alert channel clean with only trade-critical events (fills, closes, LP triggers). Each bot has its own token and chat ID, independently configurable.
Backtest Execution Flow
Select Scannersor rule builder
→
Historical Data2Y · 1-min bars
→
Signal Replayscanner logic on history
→
TQS Scoringwin rate · PnL · drawdown
→
Equity Curvetrade-by-trade chart
→
8 Gate Checkall green → onboard
AI Discovery Pipeline
Backtest ResultsTQS scores
→
Ollama LLMpattern analysis
→
AI Candidatesranked combinations
→
Load → Testone-click backtest
→
8 Gate Checkvalidate gates
→
Onboard Paperwrite to config DB
🏆
Scanner Leaderboard
Every scanner ranked by win rate, total PnL, avg hold time, and trade count. Identifies top performers and underperformers for config tuning.
🕐
Hour-of-Day Heatmap
Win rate and PnL by hour of day across all sessions. Reveals time-of-day edges — identify best entry windows and periods to avoid.
📈
Equity Curve Review
Session-by-session equity progression with drawdown overlays. Compare plan vs actual compounding curve against your wealth model milestones.
🔗
Streak Analysis
Win/loss streak detection. Identifies regime shifts — when consecutive losses appear, triggers strategy review and potential scanner re-calibration.
| Dimension | Paper | Live |
|---|---|---|
| IBKR Port | 7497 — TWS paper account | 7496 — TWS live account (real money) |
| Wealth DB | runtime/paper/intellect.db | runtime/live/intellect.db |
| Capital | Virtual — no real risk | Real money — full risk |
| Config DB | Shared — backend/data/config.db | |
| Lifecycle DB | Shared — backend/runtime/intellect_finlab_next.db | |
| Switch via | Config Console → Environment Settings (requires restart) | |
🔥 Crash during BUY order submission
▾On restart: StartupReconciliation queries TWS for open orders. If BUY was submitted but not confirmed, reconciler checks fill status. If filled, creates BUY_FILLED event and resumes from there. If not filled, marks trade FAILED and cancels.
📈 Crash while position is open (holding)
▾Lifecycle DB has SELL_SUBMITTED state. On restart: trade reloaded into RuntimeStore, LP daemon restarts, V2PositionWatchdog resumes monitoring. All rules re-arm from current position state.
💰 Crash during wealth update
▾If trade is CLOSED in lifecycle DB but wealth not yet updated: on startup, PromotionSyncWorker detects unpromoted closed trades and applies wealth updates from the trade diary. Idempotent — safe to run multiple times.
🔌 IBKR TWS disconnection mid-session
▾ib_async fires a disconnect event. RuntimeSyncWorker suspends tick processing. LP daemon continues running but in alert-only mode. On reconnect, RuntimeSyncWorker syncs position and order state. Engine resumes automatically.