deepkoluguri
/
institutional-trader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
institutional-trader/FEATURE_DOCUMENTATION.md

17 KiB
Raw Blame History

Institutional Flow Trading Platform - Complete Feature Documentation

Application Overview

A professional-grade institutional trading platform that combines real-time options flow analysis, multi-timeframe price context, alert stream correlation, institutional footprint detection, and automated scoring & badge system.

Feature Sequence (User Journey Flow)

1. DATA INGESTION & STREAMING

Sequence Step 1: Real-time Data Collection

  • CheddarFlow WebSocket Integration: Streams live options flow data
  • BlackBox API Sync: Imports historical and real-time options flow data
  • Yahoo Finance Integration: Fetches real-time stock prices, intraday data, VWAP calculations
  • Bookmap WebSocket Service: Provides order flow and price data
  • Alert Stream Processing: Correlates trading alerts with options flow
  • Database Storage: Stores all data in PostgreSQL (Supabase)

2. DATA PROCESSING & ENRICHMENT

Sequence Step 2: Options Flow Processing

  • Options Flow Processor: Normalizes and aggregates raw flow data
    • Processes Symbol, Type (CALL/PUT), Strike, Expiration, Premium, Volume
    • Calculates net premium (bullish vs bearish)
    • Determines moneyness (ITM/OTM/ATM)
    • Aggregates by symbol and time windows
    • Session bucketing (PRE/RTH/POST/OFF hours)

Sequence Step 3: Badge Calculation

  • Badge System: Visual indicators for trade characteristics
    • 🟢/🔴 (Round Badge): Bullish/Bearish direction based on ITM premium
    • 💎 (Diamond): ITM dominance indicator
    • ⭐ (Star): OTM flow indicator (>$10K premium)
    • 💰 (Money): High Open Interest (>$100K)
    • ✔ (Check): New positioning (Volume > Open Interest)
    • ⚡ (Flash): Aggressive side sweep with high premium
    • 🚀 (Rocket): Compound rocket score indicator

Sequence Step 4: Scoring & Ranking

  • Rocket Score Calculation (0-100 scale):
    • Premium tier scoring (0-3 points)
    • Net premium imbalance (-1.5 to +1.5 points)
    • Volume > OI bonus (1.2 points)
    • Session weight (RTH: 1.0, POST: 0.5, PRE: 0.3)
    • Catalyst flag (1 point)
    • OTM bias (0.8 points)
    • Tape alignment (0.5 points)
  • Momentum Score: Price momentum calculation
  • Signal Tier Classification: TIER_1, TIER_2, or IGNORE classification

3. PRICE CONTEXT ENRICHMENT

Sequence Step 5: Price Context Service

  • Multi-timeframe Price Data:
    • Prior day close price
    • RTH (Regular Trading Hours) open price (9:30 AM ET)
    • Current spot price
    • 5-minute, 15-minute, 30-minute price movements
  • VWAP Calculation: Volume-Weighted Average Price from RTH open
  • Price Reaction Tracking:
    • 5-minute reaction after signal
    • 15-minute reaction after signal
    • 30-minute reaction after signal
  • VWAP Distance: Percentage distance from current price to VWAP
  • Price vs Prior Close: Percentage change from previous close
  • Price vs RTH Open: Percentage change from market open

4. INSTITUTIONAL DETECTION

Sequence Step 6: Institutional Footprint Detection

  • Tape Alignment: Detects if price moves align with flow direction
  • Cluster Detection: Identifies institutional block trades
  • Aggressor Detection: Identifies buyer/seller initiated trades (AA/BB)
  • Large Premium Detection: Flags trades with premium > threshold
  • Flow Trend Analysis: Tracks flow momentum over time windows

5. ALERT CORRELATION

Sequence Step 7: Alert Stream Matching

  • Alert Service: Matches alerts from AlertStream to options flow
  • Alert Type Detection: News, earnings, FDA, analyst actions, etc.
  • Near Alert Flagging: Flags flow near alert events
  • Catalyst Correlation: Links options activity to market events

6. TRADE SIGNAL GENERATION

Sequence Step 8: Automated Trade Signals

  • Trade Signal Generator: Converts badge patterns to actionable signals
    • Institutional FOMO (BUY): 🟢 + 💎 + ⭐ + 💰 + ⚡
    • Institutional Distribution (SHORT): 🔴 + 💎 + ⭐ + 💰
    • Trap Warning (WAIT): 🟢 but no tape alignment
    • Slow Accumulation (BUY): 🟢 + 💎 but no ⚡
  • Entry Strategy Generation: Primary and aggressive entry strategies
  • Stop Loss Calculation: Tight and wide stop levels
  • Profit Targets: T1, T2, T3 targets with scaling percentages
  • Confidence Scoring: 0-100% confidence based on badge strength
  • Trade Horizon Classification: SCALP, INTRADAY, or SWING

7. FLOW ANALYSIS FEATURES

Sequence Step 9: Flow Decay & Reversal Detection

  • Flow Decay Detector: Tracks when institutional flow stops
    • 30+ minutes = CAUTION
    • 60+ minutes = STRONG_DECAY
    • Flow stopped + Price rising = FADE (retail chasing)
    • Flow stopped + Price dropping = AVOID
  • Flow Reversal Detection: Detects net premium direction flips
  • Flow Trend Analysis: Monitors flow momentum over time windows
  • Last Flow Timestamp: Tracks recency of flow activity

8. TRADE PLAN GENERATION

Sequence Step 10: Comprehensive Trade Plans

  • Trade Plan Generator: Auto-generates complete trade plans
    • Entry strategies (primary + aggressive)
    • Stop loss levels (tight + wide)
    • Profit targets (T1, T2, T3 with scaling)
    • Time horizon (expected + max hold)
    • Risk/Reward calculations
    • Reasoning (why this setup works)
    • Invalidation conditions
  • Trade Checklist: Automated checklist for trade validation
  • Historical Win Rate: Similar setups performance tracking

9. MULTI-SIGNAL SCANNER

Sequence Step 11: Multi-Signal Scanning

  • Signal Convergence Detection: Flags when 3+ signals fire within 10 minutes
    • Dark pool clusters
    • Options flow + block prints
    • 52-week highs
    • Volume spikes
    • ORB (Opening Range Breakouts)
    • Shock tape events
  • Stealth vs Aggressive Classification:
    • SCALP: ORB + Shock Tape + high rVol (minutes to hours)
    • INTRADAY: Options + Prints + RTH session (2-4 hours)
    • SWING: Stealth Dark + low rVol (1-5 days)
  • False Signal Filtering:
    • Dumb money trap detection (OTM lotto tickets)
    • Spoofed liquidity detection
    • End-of-day noise detection (MOC rebalancing)
  • Signal Scoring: Multi-factor scoring system

10. PHASE CLASSIFIER

Sequence Step 12: Market Phase Classification

  • Phase Classification Panel: Classifies market phases
  • Pattern Detection: Identifies repeatable market patterns
  • Phase-based Strategy Recommendations

11. DAILY ANALYSIS & POST-MORTEM

Sequence Step 13: Daily Performance Analysis

  • Daily Analysis Panel: Post-market analysis
  • Performance Tracking: Tracks signal performance
  • Playbook Generator: Auto-detects repeatable patterns from historical data
    • FDA Approval Squeeze pattern
    • Earnings Beat Fade pattern
    • Options Flow Pre-Positioning pattern
  • Pattern Win Rate Calculation: Historical win rates for patterns
  • Backtesting: Strategy backtesting capabilities

12. PERFORMANCE TRACKING

Sequence Step 14: Performance Monitoring

  • Performance Tracking Panel: Today's signals performance
  • Win Rate Tracking: Tracks actual vs predicted outcomes
  • Signal Outcome Analysis: WIN/LOSS tracking
  • Expectancy Calculation: Risk-adjusted returns
  • Historical Performance: Backtested strategy performance

13. REAL-TIME DISPLAY

Sequence Step 15: Frontend Display & Interaction

  • Options Flow Panel: Main table with all flow data
  • Top Trades Summary: Top 5 trades ranked by "best trade potential"
  • Trade Analysis Modal: Detailed trade analysis view
  • Flow Info Panel: Real-time flow statistics
  • Watchlist: User-managed symbol watchlist
  • Alerts Feed: Real-time alerts stream
  • Interactive Charts: Price charts with flow overlay
  • WebSocket Updates: Real-time data streaming
  • Filtering & Sorting: Advanced filtering capabilities
  • Column Visibility: Customizable column display

14. STRATEGY BACKTESTING

Sequence Step 16: Strategy Validation

  • Strategy Backtester: Validates signals with historical data
  • Pattern Matching: Finds historical matches for patterns
  • Win Rate Calculation: Historical win rates
  • Expectancy Analysis: Risk:Reward ratios
  • Best/Worst Setup Identification: Optimal conditions analysis

Complete Feature List (Alphabetical/Grouped)

DATA SOURCES & INTEGRATIONS

  1. BlackBox API Integration: Historical options flow data sync
  2. Bookmap WebSocket Service: Order flow and price data
  3. CheddarFlow WebSocket Service: Real-time options flow streaming
  4. Yahoo Finance Service: Stock price data, intraday bars, VWAP calculations
  5. Alert Stream Integration: Alert correlation with flow
  6. PostgreSQL Database: Central data storage (Supabase)

DATA PROCESSING

  1. Options Flow Processor: Normalizes and aggregates raw flow data
  2. Data Normalization: Symbol, type, strike, expiration standardization
  3. Premium Aggregation: Bullish vs bearish premium calculation
  4. Session Bucketing: PRE/RTH/POST/OFF hours classification
  5. Moneyness Calculation: ITM/OTM/ATM determination

SCORING & BADGES

  1. Badge System: Visual indicators (🟢🔴💎⭐💰✔⚡🚀)
  2. Rocket Score: 0-100 scoring algorithm
  3. Momentum Score: Price momentum calculation
  4. Signal Tier Classification: TIER_1, TIER_2, IGNORE
  5. Best Trade Score: Composite ranking score
  6. Confidence Scoring: 0-100% confidence ratings

PRICE ANALYSIS

  1. Price Context Service: Multi-timeframe price enrichment
  2. VWAP Calculation: Volume-weighted average price
  3. Price Reaction Tracking: 5m/15m/30m reaction analysis
  4. Prior Close Tracking: Previous day close comparison
  5. RTH Open Tracking: Regular trading hours open price
  6. Spot Price Tracking: Current market price
  7. Price vs VWAP Distance: Percentage distance calculation
  8. Support/Resistance Calculation: Key level identification

INSTITUTIONAL DETECTION

  1. Tape Alignment Detection: Price-flow direction alignment
  2. Cluster Detection: Institutional block trade identification
  3. Aggressor Detection: Buyer/seller initiated trade detection
  4. Large Premium Detection: High-value trade flagging
  5. Flow Trend Analysis: Momentum tracking over time
  6. Institutional Footprint Detection: Large player activity identification

ALERT SYSTEM

  1. Alert Stream Processing: Real-time alert ingestion
  2. Alert Matching Service: Correlates alerts with flow
  3. Alert Type Detection: News, earnings, FDA, analyst actions
  4. Near Alert Flagging: Proximity-based alert correlation
  5. Catalyst Correlation: Event-flow linking

TRADE SIGNALS

  1. Trade Signal Generator: Badge-to-signal conversion
  2. Institutional FOMO Signal: BUY signal pattern
  3. Institutional Distribution Signal: SHORT signal pattern
  4. Trap Warning Signal: WAIT signal pattern
  5. Slow Accumulation Signal: Swing trade pattern
  6. Entry Strategy Generation: Primary and aggressive entries
  7. Stop Loss Calculation: Tight and wide stops
  8. Profit Target Generation: T1, T2, T3 targets
  9. Trade Horizon Classification: SCALP/INTRADAY/SWING

FLOW ANALYSIS

  1. Flow Decay Detection: Tracks when flow stops
  2. Flow Reversal Detection: Direction flip identification
  3. Flow Trend Tracking: Momentum over time windows
  4. Last Flow Timestamp: Recency tracking
  5. Flow Metadata: Summary statistics

TRADE PLANNING

  1. Trade Plan Generator: Comprehensive trade plan creation
  2. Trade Checklist: Automated validation checklist
  3. Risk/Reward Calculation: Automated R:R ratios
  4. Entry Strategy Suggestions: Primary and aggressive
  5. Exit Strategy Suggestions: Multiple target levels
  6. Time Horizon Recommendations: Expected hold duration

SCANNING

  1. Multi-Signal Scanner: Multi-factor signal detection
  2. Signal Convergence Detection: Multiple signal alignment
  3. Stealth vs Aggressive Classification: Trade style identification
  4. False Signal Filtering: Noise reduction
  5. Dumb Money Trap Detection: Retail noise filtering
  6. Spoofed Liquidity Detection: Fake flow identification
  7. End-of-Day Noise Detection: MOC filtering
  8. Scanner Enhancement Service: Advanced scanning logic

MARKET ANALYSIS

  1. Phase Classifier: Market phase identification
  2. Pattern Detection: Repeatable pattern identification
  3. Daily Analysis Panel: Post-market analysis
  4. Performance Tracking Panel: Signal outcome tracking
  5. Playbook Generator: Pattern extraction from history
  6. FDA Approval Squeeze Pattern: Specific pattern detection
  7. Earnings Beat Fade Pattern: Specific pattern detection
  8. Options Flow Pre-Positioning Pattern: Specific pattern detection

BACKTESTING & VALIDATION

  1. Strategy Backtester: Historical validation
  2. Pattern Matching: Historical pattern finding
  3. Win Rate Calculation: Success rate analysis
  4. Expectancy Analysis: Risk-adjusted returns
  5. Best Setup Identification: Optimal conditions
  6. Worst Setup Identification: Suboptimal conditions
  7. Historical Win Rate Tracking: Similar setups performance

USER INTERFACE

  1. Options Flow Panel: Main data table
  2. Top Trades Summary: Top 5 ranked trades
  3. Trade Analysis Modal: Detailed trade view
  4. Flow Info Panel: Real-time statistics
  5. Watchlist: Symbol tracking
  6. Alerts Feed: Real-time alerts display
  7. Price Charts: Interactive price visualization
  8. Flow Heatmap: Visual flow representation
  9. Filtering System: Advanced filtering
  10. Sorting System: Multi-column sorting
  11. Column Visibility Toggle: Customizable columns
  12. Row Expansion: Detailed inline view
  13. Symbol Tooltips: Quick info on hover
  14. Score Breakdown Tooltips: Score component details

REAL-TIME FEATURES

  1. WebSocket Streaming: Real-time data updates
  2. Live Updates: Auto-refresh capabilities
  3. Real-time Flow Streaming: Live options flow
  4. Real-time Price Updates: Live price streaming
  5. Real-time Alert Streaming: Live alert feed

DATA MANAGEMENT

  1. CSV Import: Historical data import
  2. Data Validation: Data quality checks
  3. Time Format Fixing: Time normalization
  4. Database Indexing: Performance optimization
  5. Query Optimization: Fast data retrieval

TECHNICAL INFRASTRUCTURE

  1. Hybrid Architecture: Node.js + Python services
  2. FastAPI Service: Python data processing service
  3. Express.js API: Node.js REST API
  4. PostgreSQL Database: Central data store
  5. React Frontend: Modern UI framework
  6. WebSocket Support: Real-time communication
  7. Health Monitoring: Service health checks
  8. Automatic Fallback: SQL fallback when Python unavailable
  9. Error Handling: Comprehensive error management
  10. Logging System: Detailed logging
  11. Performance Monitoring: Response time tracking

ADVANCED FEATURES

  1. AI Analysis Integration: AI-powered insights
  2. Symbol Normalization: Symbol format standardization
  3. Timezone Handling: Multi-timezone support (ET/CT)
  4. Rate Limiting: API rate limit management
  5. Caching: Data caching for performance
  6. Batch Processing: Efficient bulk operations

Feature Count Summary

Total Features: 120+

By Category:

  • Data Sources & Integrations: 6 features
  • Data Processing: 5 features
  • Scoring & Badges: 6 features
  • Price Analysis: 8 features
  • Institutional Detection: 6 features
  • Alert System: 5 features
  • Trade Signals: 9 features
  • Flow Analysis: 5 features
  • Trade Planning: 6 features
  • Scanning: 8 features
  • Market Analysis: 8 features
  • Backtesting & Validation: 7 features
  • User Interface: 14 features
  • Real-time Features: 5 features
  • Data Management: 5 features
  • Technical Infrastructure: 11 features
  • Advanced Features: 6 features

Key User Workflows

Workflow 1: Real-time Trading

  1. Stream real-time options flow
  2. See badges and rocket scores auto-calculate
  3. View top trades in summary cards
  4. Click trade for detailed analysis
  5. Review trade plan with entry/stop/targets
  6. Execute trade based on signal

Workflow 2: Multi-Signal Scanning

  1. Run multi-signal scanner
  2. View convergence events
  3. Filter by trade horizon (SCALP/INTRADAY/SWING)
  4. Check false signal warnings
  5. Review scanner results
  6. Add promising symbols to watchlist

Workflow 3: Daily Analysis

  1. Review daily analysis panel
  2. Check performance tracking
  3. View playbook patterns
  4. Analyze win rates
  5. Adjust strategies based on patterns

Workflow 4: Strategy Development

  1. Identify pattern
  2. Backtest pattern
  3. Review win rate and expectancy
  4. Generate trade plan template
  5. Monitor performance
  6. Refine strategy

Technology Stack

Frontend

  • React.js
  • Vite
  • Tailwind CSS
  • Lightweight Charts
  • WebSocket Client

Backend

  • Node.js + Express.js
  • Python + FastAPI
  • PostgreSQL (Supabase)
  • WebSocket Server

Data Sources

  • CheddarFlow API
  • BlackBox API
  • Yahoo Finance API
  • Bookmap WebSocket
  • Alert Stream Data

Last Updated: Based on current codebase analysis