# Quick Integration Guide
## Add Momentum Score & Moneyness Context (15 minutes)

---

## Step 1: Add to Options Flow Route

**File:** `backend/src/routes/optionsFlow.js`

Add these imports at the top:
```javascript
import { calculateFlowMomentum, getMomentumLabel } from '../services/momentumScore.js';
import { getMoneynessContext, isGammaSqueezeSetup, getMoneynessLabel } from '../utils/moneynessHelper.js';
```

Then, in the `dataWithFlowInfo` mapping (around line 218), add:

```javascript
const dataWithFlowInfo = sorted.map(row => {
  const symbol = row.Symbol || row.symbol_norm;
  const decay = flowDecay[symbol];
  const reversal = flowReversals[symbol];
  const trend = flowTrends[symbol];
  
  // ADD: Moneyness context
  const moneyness = getMoneynessContext(row);
  const isGamma = isGammaSqueezeSetup(row);
  
  // ADD: Momentum score
  const momentumScore = calculateFlowMomentum(row, trend);
  const momentumLabel = getMomentumLabel(momentumScore);
  
  const rowWithFlowInfo = {
    ...row,
    flowDecayRaw: decay,
    flowReversalRaw: reversal,
    flowTrendRaw: trend,
    // NEW: Add these fields
    moneynessContext: moneyness,
    moneynessLabel: getMoneynessLabel(moneyness),
    isGammaSqueezeSetup: isGamma,
    momentumScore: momentumScore,
    momentumLabel: momentumLabel.label,
    momentumColor: momentumLabel.color,
    momentumIcon: momentumLabel.icon
  };
  
  // Regenerate trade signal with flow trend data
  const tradeSignal = generateTradeSignal(rowWithFlowInfo);
  rowWithFlowInfo.tradeSignal = tradeSignal;
  rowWithFlowInfo.tradeSignalDisplay = formatTradeSignal(tradeSignal);
  
  return {
    ...rowWithFlowInfo,
    flowDecay: decay ? formatFlowDecay(decay) : null,
    flowReversal: reversal && reversal.hasReversal ? formatFlowReversal(reversal) : null,
    flowTrend: trend ? formatFlowTrend(trend) : null
  };
});
```

---

## Step 2: Update Trade Signal Generator to Use Moneyness

**File:** `backend/src/services/tradeSignalGenerator.js`

Add import at top:
```javascript
import { getMoneynessContext, isGammaSqueezeSetup } from '../utils/moneynessHelper.js';
```

Then update Pattern 1 (around line 27) to check for gamma squeeze:

```javascript
// Pattern 1: 🟢 + 💎 + ⭐ + 💰 + ⚡ = BUY SIGNAL
if (round === '🟢' && hasDiamond && hasStar && hasMoney && hasFlash) {
  // CHECK: Is this a gamma squeeze setup?
  const moneyness = getMoneynessContext(row);
  const isGamma = isGammaSqueezeSetup(row);
  
  if (isGamma || (moneyness.category === 'DEEP_OTM' && row.cp_norm === 'CALL')) {
    return {
      signal: 'BUY',
      type: 'GAMMA_SQUEEZE_SETUP', // NEW TYPE
      confidence: Math.min(calculateConfidence(row, 'BUY') + 10, 95), // Boost confidence
      entry: generateEntryStrategy(row, 'BUY'),
      stop: generateStopLoss(row, 'BUY'),
      target: generateTarget(row, 'BUY'),
      reasoning: `Gamma squeeze setup: Deep OTM calls (${moneyness.distancePct}% OTM) + full institutional flow`,
      timeHorizon: 'INTRADAY',
      invalidation: generateInvalidation(row, 'BUY')
    };
  }
  
  // Regular institutional FOMO
  return {
    signal: 'BUY',
    type: 'INSTITUTIONAL_FOMO',
    confidence: calculateConfidence(row, 'BUY'),
    // ... rest stays the same
  };
}
```

---

## Step 3: Add Momentum Column to Frontend

**File:** `frontend/src/components/dashboard/OptionsFlowPanel.jsx`

Add to `allColumns` array (around line 250):

```javascript
{
  accessorKey: 'Momentum',
  header: 'Momentum',
  group: 'core',
  cell: ({ row }) => {
    const momentum = row.original.momentumScore || 0;
    const label = row.original.momentumLabel || 'MODERATE';
    const color = row.original.momentumColor || 'yellow';
    const icon = row.original.momentumIcon || '🟡';
    
    const colorClasses = {
      green: 'text-green-400 bg-green-500/20',
      yellow: 'text-yellow-400 bg-yellow-500/20',
      orange: 'text-orange-400 bg-orange-500/20',
      red: 'text-red-400 bg-red-500/20'
    };
    
    return (
      <div className="flex items-center gap-2">
        <div className="flex-1 bg-slate-700 rounded-full h-2">
          <div 
            className={`bg-${color}-500 h-2 rounded-full transition-all`}
            style={{ width: `${momentum}%` }}
          />
        </div>
        <div className={`px-2 py-1 rounded text-xs font-medium ${colorClasses[color]}`}>
          <span className="mr-1">{icon}</span>
          {momentum}
        </div>
      </div>
    );
  }
},
```

Add to `DEFAULT_VISIBLE_COLUMNS`:
```javascript
const DEFAULT_VISIBLE_COLUMNS = [
  'Symbol', 'badges', 'Rocket', 'Momentum', 'TradeSignal', 'NetPremium', 
  'FlowTrend', 'Premium', 'CallPut', 'Strike', 'TapeAlign', 'LastFlow', 
  'PctVsRthOpen', 'CreatedTime'
];
```

---

## Step 4: Add Moneyness Badge

Add to columns (optional, but helpful):

```javascript
{
  accessorKey: 'Moneyness',
  header: 'Moneyness',
  group: 'option',
  cell: ({ row }) => {
    const moneyness = row.original.moneynessLabel || 'Unknown';
    const isGamma = row.original.isGammaSqueezeSetup;
    
    return (
      <div className="flex items-center gap-1">
        <Badge variant="outline" className="text-xs">
          {moneyness}
        </Badge>
        {isGamma && (
          <Badge className="bg-purple-500/20 text-purple-400 text-xs border-purple-500/50">
            ⚡ GAMMA
          </Badge>
        )}
      </div>
    );
  }
}
```

---

## Step 5: Add Momentum Filter

Add to quick filters in `OptionsFlowPanel.jsx`:

```javascript
// In the quick filter chips section
{quickFilters.has('HighMomentum') && (
  filtered = filtered.filter(row => (row.momentumScore || 0) >= 70);
)}
```

Add button:
```javascript
<button
  onClick={() => toggleQuickFilter('HighMomentum')}
  className={`px-3 py-1 rounded text-xs ${
    quickFilters.has('HighMomentum')
      ? 'bg-green-500/20 text-green-400 border border-green-500/50'
      : 'bg-slate-800 text-slate-400 border border-slate-700'
  }`}
>
  🔥 High Momentum (70+)
</button>
```

---

## Testing

After making changes:

1. **Restart backend** - `npm run dev` in backend folder
2. **Refresh frontend** - Should see new columns
3. **Check data** - Look for:
   - Momentum scores (0-100) in Momentum column
   - Moneyness labels (ITM/OTM/etc) if you added that column
   - Gamma squeeze signals showing as `GAMMA_SQUEEZE_SETUP` type

---

## Expected Results

- ✅ **Momentum Score** - Single number (0-100) showing flow strength
- ✅ **Gamma Squeeze Detection** - Deep OTM calls with full badges = special signal type
- ✅ **Better Signal Accuracy** - Moneyness context improves signal quality
- ✅ **Easier Filtering** - Filter by momentum to find strongest signals

---

**Time:** ~15 minutes to implement all changes

**Impact:** 
- More accurate signals (gamma squeeze detection)
- Easier to spot opportunities (momentum score)
- Better trade selection (filter by momentum)

Ready to implement? Start with Step 1!