System Wiki

System Architecture & Flow

Welcome to the NiftyBot v5.0 System Wiki. This document explains the core architecture, data flow, key workflows, and directory structure of the trading terminal.

1. End-to-End System Flow

The system operates autonomously using a confluence-based scoring strategy on Nifty 50 options. Here is how data moves from the market to the Web UI:

Step 1: Real-Time Market Data (Upstox âž” Backend)

  • UpstoxFeeder establishes a secure WebSocket connection to the Upstox Market Data Feed v3.
  • It receives real-time tick data (pb.FeedResponse), extracts the Last Traded Price (LTP) for subscribed instruments (Nifty 50 Spot + Options), and caches it in TradingController.cached_ltps.
  • The Feeder also broadcasts these ticks locally via FastAPI WebSockets to the Web UI for live price flashing.

Step 2: Signal Generation & Evaluation (Backend âž” Trading Strategy)

  • In app/main.py, a background trading_loop() runs every 30 seconds.
  • The loop calls TradingController.evaluate_and_trade(), which gathers the current market context (OHLC, Renko Bricks, Option Chain, PCR, VIX).
  • The SignalEngine (app/strategy/signal_engine.py) takes this context and calculates a confluence score (out of 9) based on: PCR, OI Breakouts, VIX, Anchor Day, Last Swing, Renko Patterns, EMA Structure, Donchian Channels, and RSI.
  • If the score meets the minimum threshold (and RSI/MACD blocks don't trigger), the engine selects the appropriate ITM/ATM strike.
  • The system then checks the Premium Renko Confirmation on the 1-minute option chart to ensure option prices are trending favorably.

Step 3: Execution & Risk Management (Agent âž” Broker & DB)

  • RiskManager calculates position sizing dynamically using the Adaptive Risk Fraction (which learns from recent win/loss streaks to increase or decrease lot sizes automatically).
  • The TradingController triggers execute_pending_trade().
  • The order is sent via UpstoxClient to the broker (if in LIVE mode) or tracked internally (if in PAPER mode).
  • The trade details are committed to the PostgreSQL database via SQLAlchemy (app/models/trade.py).

Step 4: Web UI Updates (Backend âž” Frontend)

  • The Web UI relies on HTMX to poll for state changes (like PnL, Dashboard Stats, and Bot Modes) via endpoints in app/api/routes.py.
  • At the same time, the local WebSocket (/ws) continuously pushes price updates directly to the browser DOM, using Glassmorphism UI effects (green/red glow) to indicate price movements without full page reloads.

2. Directory & File Map

Use this map to quickly locate the logic you need to modify.

Directory / File Description
app/main.py The FastAPI entry point. Starts background loops (trading, Telegram, feedback), configures middleware (Auth), and initializes the database.
app/api/routes.py All HTTP endpoints. Handles Web UI routing (/, /login, /wiki), HTMX partials (/api/dashboard), bot controls (/bot/start), and Upstox OAuth callbacks.
app/services/trading_controller.py The "Brain". Manages state, triggers the SignalEngine, calculates adaptive risk, evaluates market context, places orders, and monitors open positions for SL/T1 hits.
app/services/upstox_feeder.py WebSocket client connecting to Upstox. Parses Protobuf streams to extract real-time LTPs and broadcasts them.
app/services/upstox_client.py HTTP REST client for Upstox API. Used for fetching Option Chains, historical OHLC data, placing orders, and account funds.
app/services/market_data.py Utility to format OHLC candles and calculate Put-Call Ratios (PCR) from Option Chains.
app/strategy/signal_engine.py Core Trading Strategy. Evaluates technical indicators and generates SignalResult structures, maintaining the strict 9-point confluence scorecard.
app/strategy/indicators.py Math for EMA, RSI, MACD, Donchian Channels, and Bollinger Bands.
app/strategy/patterns.py Detects specific Renko brick patterns (One-Back, Two-Back, Multi-Brick Breakout, EMA Pullbacks).
app/strategy/renko.py Logic to convert standard OHLC candles into Renko brick formations.
app/strategy/risk.py Determines optimal SL, T1, and T2 target levels based on ATR or fixed point parameters. Handles dynamic position sizing.
app/models/trade.py SQLAlchemy database schemas for Trade, BotState, and AdaptiveRiskState.
app/templates/ Jinja2 HTML templates. base.html defines the sidebar/layout. Uses Glassmorphism CSS and HTMX.
memory/system_flow_wiki.md This file.
scripts/ Utility scripts like run_backtest.py and validate_memory_sync.py.

3. Key Workflows

Authentication Workflow

  1. User clicks Login on the Web UI.
  2. routes.py (/login) redirects the user to the Upstox OAuth portal.
  3. Upon success, Upstox redirects to /api/auth/callback.
  4. The backend verifies the user's UCC ID (hard-locked to a specific account for security).
  5. The Access Token is stored in memory via UpstoxClient, granting access to the broker and the Web UI dashboard.

Trade Monitoring Workflow (v3.3)

  1. When a trade is open, TradingController creates an ActiveTradeMonitor object.
  2. Every 30 seconds, monitor_open_positions() runs to check the current option premium against the SL (Layer 2) and the Spot price against the Spot SL (Layer 1).
  3. If the Spot price breaches the t1_spot_level, 50% of the position is booked, and a trailing EMA40 rule is activated to ride the trend.
  4. Hard exits are enforced automatically at 3:00 PM (15:00) via check_time_stops().

Adaptive Risk Management

  1. The _compute_adaptive_risk_fraction() method reviews the last N trades.
  2. If the win rate drops, the system classifies it as a "loss cluster" or "slippage" issue, reducing the risk fraction (smaller lot size).
  3. If the win rate recovers above 65%, the system slowly scales the risk fraction back up to the base rate.
  4. This ensures capital preservation during choppy markets and aggressive sizing during trending markets.