institutional-trader/FEATURE_DOCUMENTATION.md

# 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
7. **Options Flow Processor**: Normalizes and aggregates raw flow data
8. **Data Normalization**: Symbol, type, strike, expiration standardization
9. **Premium Aggregation**: Bullish vs bearish premium calculation
10. **Session Bucketing**: PRE/RTH/POST/OFF hours classification
11. **Moneyness Calculation**: ITM/OTM/ATM determination

### SCORING & BADGES
12. **Badge System**: Visual indicators (🟢🔴💎⭐💰✔⚡🚀)
13. **Rocket Score**: 0-100 scoring algorithm
14. **Momentum Score**: Price momentum calculation
15. **Signal Tier Classification**: TIER_1, TIER_2, IGNORE
16. **Best Trade Score**: Composite ranking score
17. **Confidence Scoring**: 0-100% confidence ratings

### PRICE ANALYSIS
18. **Price Context Service**: Multi-timeframe price enrichment
19. **VWAP Calculation**: Volume-weighted average price
20. **Price Reaction Tracking**: 5m/15m/30m reaction analysis
21. **Prior Close Tracking**: Previous day close comparison
22. **RTH Open Tracking**: Regular trading hours open price
23. **Spot Price Tracking**: Current market price
24. **Price vs VWAP Distance**: Percentage distance calculation
25. **Support/Resistance Calculation**: Key level identification

### INSTITUTIONAL DETECTION
26. **Tape Alignment Detection**: Price-flow direction alignment
27. **Cluster Detection**: Institutional block trade identification
28. **Aggressor Detection**: Buyer/seller initiated trade detection
29. **Large Premium Detection**: High-value trade flagging
30. **Flow Trend Analysis**: Momentum tracking over time
31. **Institutional Footprint Detection**: Large player activity identification

### ALERT SYSTEM
32. **Alert Stream Processing**: Real-time alert ingestion
33. **Alert Matching Service**: Correlates alerts with flow
34. **Alert Type Detection**: News, earnings, FDA, analyst actions
35. **Near Alert Flagging**: Proximity-based alert correlation
36. **Catalyst Correlation**: Event-flow linking

### TRADE SIGNALS
37. **Trade Signal Generator**: Badge-to-signal conversion
38. **Institutional FOMO Signal**: BUY signal pattern
39. **Institutional Distribution Signal**: SHORT signal pattern
40. **Trap Warning Signal**: WAIT signal pattern
41. **Slow Accumulation Signal**: Swing trade pattern
42. **Entry Strategy Generation**: Primary and aggressive entries
43. **Stop Loss Calculation**: Tight and wide stops
44. **Profit Target Generation**: T1, T2, T3 targets
45. **Trade Horizon Classification**: SCALP/INTRADAY/SWING

### FLOW ANALYSIS
46. **Flow Decay Detection**: Tracks when flow stops
47. **Flow Reversal Detection**: Direction flip identification
48. **Flow Trend Tracking**: Momentum over time windows
49. **Last Flow Timestamp**: Recency tracking
50. **Flow Metadata**: Summary statistics

### TRADE PLANNING
51. **Trade Plan Generator**: Comprehensive trade plan creation
52. **Trade Checklist**: Automated validation checklist
53. **Risk/Reward Calculation**: Automated R:R ratios
54. **Entry Strategy Suggestions**: Primary and aggressive
55. **Exit Strategy Suggestions**: Multiple target levels
56. **Time Horizon Recommendations**: Expected hold duration

### SCANNING
57. **Multi-Signal Scanner**: Multi-factor signal detection
58. **Signal Convergence Detection**: Multiple signal alignment
59. **Stealth vs Aggressive Classification**: Trade style identification
60. **False Signal Filtering**: Noise reduction
61. **Dumb Money Trap Detection**: Retail noise filtering
62. **Spoofed Liquidity Detection**: Fake flow identification
63. **End-of-Day Noise Detection**: MOC filtering
64. **Scanner Enhancement Service**: Advanced scanning logic

### MARKET ANALYSIS
65. **Phase Classifier**: Market phase identification
66. **Pattern Detection**: Repeatable pattern identification
67. **Daily Analysis Panel**: Post-market analysis
68. **Performance Tracking Panel**: Signal outcome tracking
69. **Playbook Generator**: Pattern extraction from history
70. **FDA Approval Squeeze Pattern**: Specific pattern detection
71. **Earnings Beat Fade Pattern**: Specific pattern detection
72. **Options Flow Pre-Positioning Pattern**: Specific pattern detection

### BACKTESTING & VALIDATION
73. **Strategy Backtester**: Historical validation
74. **Pattern Matching**: Historical pattern finding
75. **Win Rate Calculation**: Success rate analysis
76. **Expectancy Analysis**: Risk-adjusted returns
77. **Best Setup Identification**: Optimal conditions
78. **Worst Setup Identification**: Suboptimal conditions
79. **Historical Win Rate Tracking**: Similar setups performance

### USER INTERFACE
80. **Options Flow Panel**: Main data table
81. **Top Trades Summary**: Top 5 ranked trades
82. **Trade Analysis Modal**: Detailed trade view
83. **Flow Info Panel**: Real-time statistics
84. **Watchlist**: Symbol tracking
85. **Alerts Feed**: Real-time alerts display
86. **Price Charts**: Interactive price visualization
87. **Flow Heatmap**: Visual flow representation
88. **Filtering System**: Advanced filtering
89. **Sorting System**: Multi-column sorting
90. **Column Visibility Toggle**: Customizable columns
91. **Row Expansion**: Detailed inline view
92. **Symbol Tooltips**: Quick info on hover
93. **Score Breakdown Tooltips**: Score component details

### REAL-TIME FEATURES
94. **WebSocket Streaming**: Real-time data updates
95. **Live Updates**: Auto-refresh capabilities
96. **Real-time Flow Streaming**: Live options flow
97. **Real-time Price Updates**: Live price streaming
98. **Real-time Alert Streaming**: Live alert feed

### DATA MANAGEMENT
99. **CSV Import**: Historical data import
100. **Data Validation**: Data quality checks
101. **Time Format Fixing**: Time normalization
102. **Database Indexing**: Performance optimization
103. **Query Optimization**: Fast data retrieval

### TECHNICAL INFRASTRUCTURE
104. **Hybrid Architecture**: Node.js + Python services
105. **FastAPI Service**: Python data processing service
106. **Express.js API**: Node.js REST API
107. **PostgreSQL Database**: Central data store
108. **React Frontend**: Modern UI framework
109. **WebSocket Support**: Real-time communication
110. **Health Monitoring**: Service health checks
111. **Automatic Fallback**: SQL fallback when Python unavailable
112. **Error Handling**: Comprehensive error management
113. **Logging System**: Detailed logging
114. **Performance Monitoring**: Response time tracking

### ADVANCED FEATURES
115. **AI Analysis Integration**: AI-powered insights
116. **Symbol Normalization**: Symbol format standardization
117. **Timezone Handling**: Multi-timezone support (ET/CT)
118. **Rate Limiting**: API rate limit management
119. **Caching**: Data caching for performance
120. **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*