# 🚀 Institutional Flow Trading Platform

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.

Features

• Real-time Options Flow Analysis - Live streaming of options trades with institutional detection
• Multi-Signal Scanner - Automated scanning for high-probability trading opportunities
• Daily Post-Mortem Analysis - Performance tracking and analysis
• Institutional Footprint Detection - Tape alignment and cluster detection
• Automated Scoring System - Rocket Score (🚀) calculation for opportunity ranking
• Badge System - Visual indicators for trade characteristics (🟢🔴💎⭐💰⚡🚀)
• Live WebSocket Updates - Real-time data streaming
• Interactive Charts - TradingView-style price charts using Lightweight Charts

Tech Stack

Backend

• Node.js + Express.js - RESTful API server
• PostgreSQL (via Supabase) - Database
• WebSocket - Real-time data streaming
• Express-WS - WebSocket support for Express

Frontend

• React.js - UI framework
• Vite - Build tool and dev server
• TailwindCSS - Utility-first CSS framework
• Zustand - State management
• React Query - Data fetching and caching
• Lightweight Charts - TradingView-style charts
• shadcn/ui - UI component library (styled components)

Project Structure

/institutional_trader
├── /backend
│   ├── /src
│   │   ├── /routes          # API route handlers
│   │   ├── /queries         # Database query modules
│   │   ├── /services        # Business logic (badges, scoring, alignment)
│   │   ├── db.js            # Supabase connection
│   │   └── server.js        # Express server
│   ├── package.json
│   └── .env.example
├── /frontend
│   ├── /src
│   │   ├── /components      # React components
│   │   │   ├── /dashboard   # Main dashboard panels
│   │   │   ├── /charts      # Chart components
│   │   │   ├── /tables      # Table components
│   │   │   └── /ui          # UI components
│   │   ├── /hooks           # Custom React hooks
│   │   ├── /store           # Zustand store
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   ├── vite.config.js
│   └── tailwind.config.js
└── README.md

Setup Instructions

Prerequisites

• Node.js 18+ and npm
• Supabase account and project
• Git

1. Clone the Repository

git clone <repository-url>
cd institutional_trader

2. Backend Setup

cd backend
npm install

Create a .env file in the backend directory:

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key
SUPABASE_SERVICE_KEY=your_supabase_service_key

# Server Configuration
PORT=3001
NODE_ENV=development

# CORS Configuration
CORS_ORIGIN=http://localhost:5173

3. Database Setup (Supabase)

You'll need to create the following tables in your Supabase database:

options_flow table

CREATE TABLE options_flow (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  symbol VARCHAR(10) NOT NULL,
  type VARCHAR(4) NOT NULL, -- 'CALL' or 'PUT'
  strike DECIMAL(10, 2) NOT NULL,
  expiration TIMESTAMP WITH TIME ZONE,
  total_premium DECIMAL(15, 2),
  volume INTEGER,
  sentiment DECIMAL(3, 2), -- 0.00 to 1.00
  volume_ratio DECIMAL(10, 2),
  execution_time INTEGER, -- seconds
  rocket_score INTEGER, -- 0-100
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_options_flow_symbol ON options_flow(symbol);
CREATE INDEX idx_options_flow_created_at ON options_flow(created_at DESC);
CREATE INDEX idx_options_flow_type ON options_flow(type);

daily_analysis table

CREATE TABLE daily_analysis (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  symbol VARCHAR(10) NOT NULL,
  analysis_date DATE NOT NULL,
  final_score INTEGER, -- 0-100
  price_change_percent DECIMAL(5, 2),
  flow_count INTEGER,
  total_premium DECIMAL(15, 2),
  call_put_ratio DECIMAL(5, 2),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  UNIQUE(symbol, analysis_date)
);

CREATE INDEX idx_daily_analysis_date ON daily_analysis(analysis_date DESC);
CREATE INDEX idx_daily_analysis_symbol ON daily_analysis(symbol);

4. Frontend Setup

cd frontend
npm install

5. Start Development Servers

Terminal 1 - Backend

cd backend
npm run dev

The backend will start on http://localhost:3001

Terminal 2 - Frontend

cd frontend
npm run dev

The frontend will start on http://localhost:5173

API Endpoints

Options Flow

• GET /api/options-flow - Get recent options flow data
• GET /api/options-flow/stats/:symbol - Get flow statistics for a symbol
• GET /api/options-flow/:id - Get specific flow entry
• POST /api/options-flow/search - Search flows by criteria

Daily Analysis

• GET /api/daily-analysis - Get recent daily analyses
• GET /api/daily-analysis/:date - Get analysis for specific date
• GET /api/daily-analysis/:date/top - Get top performers for date
• GET /api/daily-analysis/symbol/:symbol - Get symbol performance over time

Scanner

• POST /api/scanner/multi-signal - Multi-signal scan
• POST /api/scanner/clusters - Institutional cluster detection
• POST /api/scanner/alert-correlation - Alert correlation analysis
• GET /api/scanner/opportunities - Quick top opportunities scan

WebSocket

• ws://localhost:3001/ws - Real-time data streaming

Badge System

The platform uses emoji badges to quickly identify trade characteristics:

• 🟢 Bullish Flow - Call options with bullish sentiment
• 🔴 Bearish Flow - Put options with bearish sentiment
• 💎 Premium Trade - High premium trades (>$100k)
• ⭐ Unusual Activity - Volume > 10x average
• 💰 High Volume - Volume > 1000 contracts
• ⚡ Fast Execution - Execution time < 5 seconds
• 🚀 High Momentum - Momentum score > 80

Rocket Score

The Rocket Score (0-100) combines multiple signals:

• Badge Score (0-25 points) - Based on badge count
• Tape Alignment (0-30 points) - Price action alignment with flow
• Premium Score (0-20 points) - Trade size significance
• Volume Score (0-15 points) - Unusual volume detection
• Sentiment Score (0-10 points) - Directional conviction

Score Tiers:

• 90-100: 🚀🚀🚀 ELITE
• 75-89: 🚀🚀 HIGH
• 60-74: 🚀 MEDIUM
• 40-59: ⚡ LOW
• 0-39: MINIMAL

Development

Backend Scripts

• npm run dev - Start development server with auto-reload
• npm start - Start production server

Frontend Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build

Environment Variables

Backend (.env)

• SUPABASE_URL - Your Supabase project URL
• SUPABASE_KEY - Supabase anon key
• SUPABASE_SERVICE_KEY - Supabase service role key (for admin operations)
• PORT - Server port (default: 3001)
• NODE_ENV - Environment (development/production)
• CORS_ORIGIN - Allowed CORS origin

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License

Support

For issues and questions, please open an issue on GitHub.

---

Built with ❤️ for institutional traders