🏗️ Nifty Trader — System Architecture

Automated intraday Nifty options trading system with Greek-aware risk management, tiered firefighting adjustments, and real-time web dashboard. v7 scoring architecture.

System Overview

Directory Structure

nifty_trader/
├── agents/              # Market analysis agents
│   ├── global_macro.py     # 31 global instruments, FII/DII, GIFT Nifty
│   ├── technical_analysis.py # RSI, MACD, BB, VWAP, SuperTrend, OI chain
│   ├── news_sentiment.py   # RSS feeds, headline sentiment scoring
│   ├── market_intelligence.py # Participant OI analysis
│   ├── risk_manager.py     # Portfolio-level risk assessment
│   ├── ai_advisor.py       # Claude AI advisory (optional)
│   └── strategy_engine.py  # Strategy proposal generation
├── core/                # Core trading logic
│   ├── orchestrator.py     # Main workflow conductor
│   ├── strategy_scorer.py  # v7 FMS + VIX multiplier scoring
│   ├── firefighter.py      # 3-tier adjustment decision engine
│   ├── position_manager.py # Live position monitoring & exits
│   ├── risk_engine.py      # Dynamic SL/trailing/rupee floors
│   ├── greeks.py           # Black-Scholes delta calculator
│   ├── models.py           # Data models (Position, Leg, OptionsChain)
│   ├── trend_analyzer.py   # Multi-timeframe trend analysis
│   ├── expiry_selector.py  # Weekly/monthly expiry logic
│   ├── margin_calculator.py # Per-strategy margin estimation
│   ├── learning_engine.py  # Post-trade pattern learning
│   └── parameter_tuner.py  # Dynamic parameter optimization
├── execution/           # Order execution layer
│   ├── trading_engine.py   # Unified paper/live engine (WebSocket, monitoring)
│   ├── broker.py           # Zerodha Kite API wrapper
│   ├── order_manager.py    # Order placement & tracking
│   ├── kite_auth.py        # Authentication (auto + manual)
│   └── paper_trader.py     # Paper trading simulation
├── strategies/          # Strategy implementations
│   ├── base.py             # Base class (strike selection, payoff calc)
│   ├── short_straddle.py   # ATM CE+PE sell
│   ├── short_strangle.py   # OTM CE+PE sell
│   ├── iron_condor.py      # Credit spread both sides + wings
│   ├── bull_call_spread.py # Debit CE spread (bullish)
│   └── bear_put_spread.py  # Debit PE spread (bearish)
├── dashboard/           # Web UI
│   ├── api_server.py       # FastAPI backend (~4800 lines)
│   └── index.html          # Single-page dashboard (~3300 lines)
├── data/                # Persistence
│   ├── trade_store.py      # SQLite trade history + AI logs
│   ├── journal.py          # Trade journaling
│   └── market_feeds.py     # Data feed helpers
├── config/settings.py   # All configuration
└── tests/               # Comprehensive test suite

5 Strategies

Strategy Scoring — v7 Architecture

Four-stage pipeline. No single indicator dominates — all signals are fused into a single score.

Stage 1: Compute FMS (Final Market Sentiment)

FMS ranges from -10 (extreme bearish) to +10 (extreme bullish). Purely directional — no VIX influence.

Stage 2: FMS → Base Score Lookup

Each strategy has a score curve mapping FMS to a base score (0-100):

Stage 3: VIX Multiplier

VIX level × VIX direction creates a multiplier that scales base scores:

Sellers: VIX falling = boost (theta friendly). VIX rising + high = penalize (vol expansion risk).

Buyers: VIX rising = boost (movement helps). VIX falling = penalize (IV crush).

Stage 4: Hostility × IV Rank

Hostility = composite of VIX level + trend strength + regime volatility. High hostility penalizes unlimited-risk sellers more than defined-risk strategies. IV Rank >60 boosts sellers (rich premiums), <30 boosts buyers.

Final Score

Score = FMS_Base × VIX_Mult × Hostility_Mult × IV_Rank_Mod

Threshold: 55%. Strategies scoring below are not recommended. Highest scorer gets SELECTED.

Trading Engine

execution/trading_engine.py — Unified engine for both paper and live trading.

Lifecycle

Key Features

Risk Management

Dynamic Exit Levels (risk_engine.py)

SL tightens (never widens) based on: VIX rising, high VIX regime, short DTE, strong trend, low entry confidence, late session.

Firefighter — 3-Tier Adjustment Engine (firefighter.py)

Called by Position Manager when loss severity reaches tier thresholds. Analyzes market context (bias, OI, macro, delta drift) and recommends the optimal adjustment.

Special triggers:

Delta Tier: Independent of SL tiers. Fires when position delta drifts ≥0.25 from entry. Unlimited rolls. Restores delta neutrality by rolling profitable side.

VIX Wing Buy: VIX spikes ≥1.5% from entry → buy both CE+PE wings immediately (straddle/strangle only). Converts to defined risk. Highest priority override.

Range Breach: After wings bought, if spot breaches wing strike → guaranteed loser, exit immediately.

Max rolls: 1 at T1, 2 at T2, 3 at T3. When exhausted → tighten SL for controlled exit.

Urgency Modifier

Each adjustment's threshold is adjusted by a [-5, +5] urgency modifier based on: intraday bias confirming tested side (+3), OI sentiment (+2), OI momentum (+2), macro direction (+2), regime (trending +2, rangebound -2), trend duration, delta drift, VIX spike.

Analysis Agents

Dashboard

Single-page web app served by FastAPI. Real-time data via polling (30s scores, 5s positions). No external dependencies — all charting via Chart.js.

Tabs

Data Flow — Entry to Exit

1. SCORING (every 30s during market hours)
   Agents collect: macro score, technicals, OI, news sentiment
   → compute_fms() → FMS score (-10 to +10)
   → FMS lookup → base score per strategy
   → VIX multiplier → hostility → IV rank → final score
   → Highest scorer above 55% threshold → SELECTED

2. ENTRY
   Selected strategy proposes strikes (ATM/OTM based on strategy)
   → Verify liquidity (LTP available for all legs)
   → Calculate risk_engine exit levels (dynamic SL, trail, rupee floor)
   → Place MARKET orders (paper: LTP fill, live: Kite MARKET)
   → Initialize position tracking (net premium, Greeks, base delta)

3. MONITORING (every tick, ~1-5s)
   Update leg LTPs from WebSocket → compute unrealized P&L
   → Check priority order:
     a. TIME EXIT (3:00 PM) → close all
     b. RANGE BREACH (post-wings) → close all
     c. HARD SL (rupee floor or % SL) → close all
     d. TRAILING STOP (70/80% of peak) → close all
     e. ADJUSTMENT ZONE (30-100% of SL severity):
        → Build FirefighterContext (bias, OI, macro, delta, surge)
        → Firefighter.analyze() → recommendation
        → Execute: roll untested / buy wings / add lots / tighten SL
     f. NORMAL → continue monitoring

4. EXIT
   Close all legs via MARKET orders
   → Compute final P&L (realized + unrealized)
   → Store to SQLite with full market snapshot
   → AI post-trade analysis (optional)
   → Update learning engine patterns

Technology Stack