StockTracker — Complete System Guide

An NSE Nifty-100 swing & intraday screener with virtual paper trading, live KITE quotes, and 15 trading strategies running every 5 minutes during market hours.

1. Overview

StockTracker scans the Nifty 100 universe every 5 minutes during market hours (09:00–16:00 IST) against 15 hand-tuned trading strategies spanning bull/bear/sideways regimes, both swing and intraday. Qualifying signals are auto-entered into a virtual ₹80,000 paper portfolio. Live market prices come from Zerodha KITE (when configured) or Yahoo Finance as fallback. No real orders are ever placed.

2. Architecture

Three independent layers communicating via MySQL + Redis:

                              ┌──────────────────────┐
                              │   Frontend (static)  │
                              │  login · dashboard   │
                              │  screener · paper    │
                              │  strategies · zero   │
                              └──────────┬───────────┘
                                         │ /api/*
                                         ▼
        ┌────────────────────────────────────────────────────────────┐
        │                  PHP API  (api/index.php)                  │
        │  ─────────────────────────────────────────────────────────  │
        │  AuthController  · BrokerConfigController                  │
        │  ScreenerController · StrategiesController                 │
        │  PaperTradingController · MarketController                 │
        │  WatchlistController · StockController                     │
        │                                                            │
        │  lib/KiteClient.php  (READ-ONLY, whitelist enforced)       │
        └─────────────┬────────────────────────────┬─────────────────┘
                      │                            │
                      ▼                            ▼
              ┌──────────────┐              ┌─────────────┐
              │    MySQL     │              │    Redis    │
              │              │              │   (cache)   │
              │ ohlcv_daily  │              └─────────────┘
              │ ohlcv_hourly │                     ▲
              │ stocks       │                     │
              │ users        │              ┌──────┴──────┐
              │ user_broker  │              │             │
              │ virtual_*    │       ┌──────┴──────┐ ┌────┴────────┐
              │ strategy_*   │       │   Python    │ │   Python    │
              │ screening_*  │       │  Ingestion  │ │  Strategies │
              │ ingestion_log│       │   Worker    │ │   Engine    │
              └──────────────┘       └──────┬──────┘ └─────┬───────┘
                                            │              │
                                            ▼              │
                                     ┌──────────────┐      │
                                     │   KITE API   │◄─────┘
                                     │              │ (live LTP +
                                     │   Yahoo API  │  historical)
                                     │  (fallback)  │
                                     └──────────────┘

Tech stack

3. Data Flow

Following a single trade from market to paper portfolio:

  ① 10:15 IST    ingest cron fires
                 ┌──────────────────────────────────────┐
                 │ python main.py ingest                │
                 │  → KiteHistoricalClient (preferred)  │
                 │  → YahooFinanceClient   (fallback)   │
                 └──────────────────────────────────────┘
                                  │
                                  ▼  upsert
                 ┌──────────────────────────────────────┐
                 │ ohlcv_daily   (1d candles, 2y back)  │
                 │ ohlcv_hourly  (1h candles, 60d back) │
                 └──────────────────────────────────────┘

  ② Every 5 min  strategies cron fires
     09:00-16:00 ┌──────────────────────────────────────┐
                 │ python main.py strategies            │
                 │  → load OHLCV from MySQL              │
                 │  → compute indicators (pandas)        │
                 │  → run 15 strategy fns concurrently   │
                 │  → produce StrategySignal[]          │
                 │  → persist signals                    │
                 └──────────────────────────────────────┘
                                  │
                                  ▼
                 ┌──────────────────────────────────────┐
                 │ strategy_signals (live table, 24h TTL)│
                 └──────────────────────────────────────┘
                                  │
                                  ▼  _paper_trade(signals)
                 ┌──────────────────────────────────────┐
                 │ PaperTrader.sweep_stale_intradays()  │ ← safety net
                 │ PaperTrader.auto_enter(signals)      │ ← BUY/SELL paper
                 │ PaperTrader.update_unrealized()      │
                 │ PaperTrader.check_swing_exits()      │
                 └──────────────────────────────────────┘
                                  │
                                  ▼
                 ┌──────────────────────────────────────┐
                 │ virtual_trades   (the paper ledger)  │
                 │ virtual_portfolio (cash + tallies)   │
                 └──────────────────────────────────────┘

  ③ 15:25 IST    paper-close cron fires
                 ┌──────────────────────────────────────┐
                 │ python main.py paper-close           │
                 │  → close all intraday positions      │
                 │  → exit price priority:              │
                 │      KITE LTP                        │
                 │       → today's hourly close         │
                 │       → today's daily close          │
                 │       → current_price                │
                 │       → entry_price (last resort)    │
                 └──────────────────────────────────────┘

  ④ User opens   /paper-trading.html
                 ┌──────────────────────────────────────┐
                 │ PaperTradingController (PHP)         │
                 │  → self-heal stuck-open rows         │
                 │  → sweepStaleIntradays()             │
                 │  → return trades + portfolio + perf  │
                 └──────────────────────────────────────┘
                                  │
                                  ▼
                 ┌──────────────────────────────────────┐
                 │ Browser renders:                     │
                 │   Open Positions · Closed Today      │
                 │   Today's Trades · Performance · etc │
                 │ LivePrices.fetch() overlays KITE LTP │
                 └──────────────────────────────────────┘

4. Cron Jobs

4.1 Cron table

4.2 What each job does

5. Strategies (15)

All strategies share a common dataclass output (StrategySignal): direction, entry, SL, T1/T2/T3, risk, R:R, signal_strength (0–100), confidence (HIGH/MEDIUM), and a human-readable reason string. Each function is a pure transform of pre-computed indicators (_ExtIndicators) and produces a signal only when every hard condition passes.

5.1 Bull Swing (6 strategies)

5.2 Bull Intraday (2)

5.3 Bear (4: 2 Intraday + 2 Swing)

5.4 Sideways (3: 2 Intraday + 1 Swing)

6. Trading Rules

Hard rules enforced by PaperTrader.auto_enter():

1. Trade window: No new paper trades outside 09:20–15:25 IST, weekdays only. 5-min buffer at both ends of the 09:15–15:30 NSE session.
2. Open-position block: If a ticker already has an OPEN paper position (any strategy), no new entry for that ticker — even from a different strategy.
3. Cooldown: If (ticker, strategy_key) was traded and closed within the last 5 days, skip — wait for cooldown to expire. Different strategy on the same ticker is OK after cooldown.
4. Confidence: Only HIGH or MEDIUM signals — never LOW.
5. Cash check: Skip if current_balance < live_entry_price.
6. Trigger validation: For LONG, execute only when live ≥ strategy_entry. For SHORT, execute only when live ≤ strategy_entry.
7. Slippage cap: 0.5% for intraday strategies, 0.75% for swing strategies — skip "chasing" entries where live has already moved too far past the trigger.

Strategy vs Actual prices

Each paper trade stores both:

Position sizing & portfolio

• 1 share per signal. No leverage, no portfolio sizing math.
• Cash deducted on entry, refunded + P&L credited on close.
• Portfolio is a single row in virtual_portfolio (id=1) — shared across all users in this build.
• Reset via POST /api/paper/reset with {"confirm":"RESET_CONFIRMED"} body.

7. Pages & UI

All protected pages use a 4-item collapsible sidebar (Dashboard · Screener · Strategies · Paper Trading) plus a Broker settings button. The sidebar collapse-state persists in localStorage['sb_col']. auth.js blocks unauthenticated access via a global /api/auth/check probe.

7.1 login.html — Sign in

• Username + password authentication (bcrypt, 5-attempt lockout for 15 min)
• Data Source selector (Yahoo / Zerodha KITE) baked into the form
• When KITE is selected, expands a collapsible block with API Key / Secret / Access Token inputs
• Animated ticker tape at top, shake-on-error, grid background
• Redirects to / on success

7.2 index.html — Dashboard

• 6 metric cards: Total Signals, Strong, Moderate, Avg Strength, Portfolio Value, Today's P&L
• Top Signals table (2/3 width) — top 10 highest-strength signals from the screener
• Open Positions list (1/3 width) — quick glance at current paper holdings
• Strategy Performance table — per-strategy win-rate, average win/loss, total P&L

7.3 screener.html — Technical Screener

• Full Nifty-100 table with Price · Change% · RSI 14 · Volume× · ATR% · Rules badges · Signal Strength
• Search by ticker / company name; Sector filter; Min Signal Strength slider
• Rule badges (T/M/V/MC/VR/ST) show which technical conditions passed per row
• Click any row → modal with TradingView-style chart (EMA 20/50/200 overlay) via Lightweight Charts

7.4 strategies.html — Strategy Explorer

• Strategy cards grid — one card per strategy with description, edge, hold period, risk level
• Click a card → filter the signals table below to just that strategy's current signals
• Direction badges (LONG / SHORT), Intraday/Swing chips, signal counts per strategy
• Signals table: per-row entry, SL, T1/T2/T3, R:R, confidence, time since signal
• Click signal row → same chart modal as Screener page
• "Screener" link in toolbar to jump to /screener.html

7.5 paper-trading.html — Paper Trading Simulator

5 tabs across the top:

• Top toolbar always shows a "PAPER ONLY · No real orders" green badge — visible reassurance that KITE is read-only.
• Portfolio summary bar: Available · Invested · Realized P&L · Unrealized (live-updated) · Win Rate · Today's P&L. The Unrealized tile flashes amber on every live-price refresh.
• Reset button wipes all trades and restores ₹80,000 cash (confirmation modal).

7.6 settings.html — Trading Parameters

Edit any of the 10 tunable trading parameters from the UI instead of source code. Changes apply on the next strategies-cron run (within 5 min). Grouped into four categories:

• Entry Rules — slippage caps (intraday + swing), minimum confidence (LOW/MEDIUM/HIGH), minimum signal strength
• Trade Window — open and close times (IST), enforced against weekday market hours
• Risk Management — cooldown days for same ticker+strategy, stale-swing expiry days
• Sizing — quantity per signal (shares), default initial balance for Reset

Settings are global (single row per key). Backed by the app_settings table. Python reads via settings_loader.py with hard-coded fallbacks.

7.7 zero.html — KITE Token Exchange

• Configured as the Redirect URL in your Kite Connect app
• Reads ?request_token=XXX&status=success from the URL after Zerodha login
• POSTs to /api/broker/kite-token — backend computes the SHA-256 checksum, exchanges for an access_token, saves it to user_broker_config
• Shows success / error / retry states; auto-redirects to / after 3s on success
• Strips the request_token from the URL bar via history.replaceState() — won't leak via bookmarks

7.8 Broker Settings modal (sidebar → Broker)

• Data Source toggle (Yahoo / KITE) with explanatory text
• Read-only KITE callout: "no real orders are ever placed"
• Pre-filled credential inputs with masked values (ab••••yz) — proves a value is saved without leaking the secret
• Focus → select-all so paste replaces cleanly; blur with empty restores the masked display
• "Test Connection" button — hits /user/profile on KITE, prints "Connected as <your-name>"
• "Login with Zerodha →" button — redirects to kite.zerodha.com/connect/login?api_key=... which bounces back to /zero.html
• Token age display: "Token last updated 3h ago" / "likely expired" if > 24h

8. Broker / Data Source

Two sources, with KITE strongly preferred when configured:

Yahoo Finance (default)

• Free, no credentials needed
• Provides 2-year daily and 60-day hourly OHLCV
• EOD only — no real-time intraday ticks
• Used as the fallback when KITE is unavailable

Zerodha KITE (preferred)

• Requires Kite Connect subscription (₹2,000/mo + GST)
• Real-time intraday quotes via /quote/ltp
• Historical OHLCV via /instruments/historical/<token>/<interval>
• Access token rotates daily (~6 AM IST) — refresh via "Login with Zerodha"

Daily KITE flow

  1. Sidebar → Broker → "Login with Zerodha →"
     │
     ▼
  2. Browser redirects to:
        https://kite.zerodha.com/connect/login?api_key=YOURKEY&v=3
     │
     ▼
  3. User signs in (Zerodha ID + password + TOTP)
     │
     ▼
  4. Zerodha redirects to:
        https://trade.recruval.in/zero.html?request_token=XXX&status=success
     │
     ▼
  5. zero.html JS captures request_token, POSTs to /api/broker/kite-token
     │
     ▼
  6. BrokerConfigController computes SHA256(api_key+request_token+api_secret)
     POSTs to https://api.kite.trade/session/token, gets access_token
     │
     ▼
  7. access_token saved to user_broker_config.kite_access_token
     kite_token_updated_at = NOW()
     │
     ▼
  8. /api/market/quote, /quote/ltp, /instruments/historical
     now all served from KITE for the rest of the day

Where each data source is used

9. Paper Trading Engine

All paper-trade lifecycle methods live in python/paper/trader.py:

Exit reasons (enum)

• TARGET1, TARGET2, TARGET3 — price hit one of the strategy's targets
• STOP_LOSS — price breached the strategy's stop
• INTRADAY_AUTO — closed by the 15:25 cron (or by the stale-intraday sweep)
• MANUAL — user clicked the Close button in the UI
• EXPIRED — swing trade open > 15 days with no target/SL hit; force-closed at latest close

10. Database Schema

Migrations

Run in order on a fresh install:

mysql -u app -p stocktracker < database/schema.sql
mysql -u app -p stocktracker < database/nifty100_stocks.sql
mysql -u app -p stocktracker < database/add_users.sql
mysql -u app -p stocktracker < database/add_direction_column.sql
mysql -u app -p stocktracker < database/add_strategy_signals.sql
mysql -u app -p stocktracker < database/add_paper_trading.sql
mysql -u app -p stocktracker < database/add_broker_config.sql
mysql -u app -p stocktracker < database/add_strategy_prices.sql
mysql -u app -p stocktracker < database/add_app_settings.sql

# Optional / on-demand
mysql -u app -p stocktracker < database/repair_paper_trades.sql

11. API Endpoints

All routes registered in api/index.php. Public routes (/api/auth/*) skip the auth guard; everything else requires $_SESSION['user_id'].

12. Safety Guarantees

No real orders — three independent layers

1. Code structurally cannot place orders. KiteClient only has a get() method — no post(), put(), or delete(). The ALLOWED_PATHS whitelist rejects any path outside read-only market-data endpoints. __call blocks any undefined method invocation with a clear error.
2. Codebase audit. Zero matches for place_order, /orders, place_trade across the entire repo. The only POST to KITE is /session/token (auth, not orders) and is commented as such.
3. UI is honest. The Paper Trading toolbar always shows a green "PAPER ONLY · No real orders" badge. The Broker modal repeats this in a green callout when KITE is selected.

Data self-healing

• Stuck-open rows (status='OPEN' but exit_price set) — auto-promoted to CLOSED on every /api/paper/trades and /api/paper/dashboard call.
• Stale intraday positions (entry_time < today and still OPEN) — Python sweep runs before every auto_enter; PHP sweep runs on every API read. Both update both virtual_trades and virtual_portfolio atomically.
• Belt-and-braces filter — Open Positions SQL requires ALL of status='OPEN' AND exit_time IS NULL AND exit_price IS NULL AND exit_reason IS NULL AND pnl IS NULL so a half-closed row never appears in the open list.
• One-shot SQL repair — database/repair_paper_trades.sql for manual cleanup of historical inconsistency.

Credential handling

• Secrets stored in user_broker_config per-user, never logged.
• Frontend only ever receives MASKED versions (ab••••yz) — full values stay on the server.
• Saved credentials shown as masked placeholder in the modal; the masked string is never sent back as a save value.
• Failed login attempts: 5 strikes → 15-min lockout (per users.locked_until).
• request_token in the URL is stripped via history.replaceState() after capture.

13. Troubleshooting

"Intraday trades from yesterday still showing as OPEN"

Likely the paper-close cron didn't fire (server down, cron mis-scheduled). Self-heal will fix on next page load. To confirm:

tail -50 $LOG/paper.log
crontab -l | grep paper-close
# Should show:  25 15 * * 1-5  $PY $APP paper-close ...

"PAPER trigger skip" appearing in logs

Working as designed. Means a signal fired but the live price had already moved > 0.5% / 0.75% past the trigger — system avoided "chasing" the move. Tune the slippage cap in trader.py (MAX_SLIPPAGE_INTRADAY / MAX_SLIPPAGE_SWING) if too strict.

"KITE token expired or invalid"

KITE access_tokens expire at 06:00 IST daily. Sidebar → Broker → "Login with Zerodha →" to mint a fresh one. The /api/market/quote endpoint silently falls back to Yahoo EOD when this happens — UI shows an amber warning banner.

Wrong times displayed in trade details

MySQL TIMESTAMPs are stored in the server's session timezone (IST). The JS parser treats them as local without appending " UTC". If you see times off by +5:30 hours, server timezone configuration likely changed — check SELECT @@session.time_zone, @@global.time_zone, NOW().

Re-running migrations safely

All migrations are idempotent — they use either CREATE TABLE IF NOT EXISTS or a stored-procedure check against information_schema. Safe to re-run after a code update.

Reset the paper portfolio

curl -X POST http://localhost/api/paper/reset \
  -H "Content-Type: application/json" \
  -b "PHPSESSID=<your-session>" \
  -d '{"confirm":"RESET_CONFIRMED"}'

Or simply click Reset in the Paper Trading toolbar.

14. File Map

stockTracker/
├── api/
│   ├── index.php                              # Router + auth guard
│   ├── config/
│   │   ├── bootstrap.php                      # Session start
│   │   └── database.php                       # PDO + Redis singletons
│   ├── core/
│   │   └── Router.php                         # GET/POST/DELETE + path params
│   ├── lib/
│   │   ├── KiteClient.php                     # READ-ONLY KITE REST client
│   │   └── BrokerConfig.php                   # Per-user broker config helper
│   └── controllers/
│       ├── AuthController.php                 # Login / logout / check
│       ├── ScreenerController.php             # Technical screener data
│       ├── StockController.php                # Universe / chart-data / indicators
│       ├── StrategiesController.php           # 15-strategy metadata + signals
│       ├── PaperTradingController.php         # Paper trade lifecycle
│       ├── BrokerConfigController.php         # KITE creds + token exchange
│       ├── MarketController.php               # Live quote pass-through
│       ├── WatchlistController.php
│       └── DiagController.php
├── python/
│   ├── main.py                                # CLI dispatch (ingest/screen/strategies/paper-close)
│   ├── config.py                              # Dataclass-based settings
│   ├── models/
│   │   ├── database.py                        # get_cursor() context manager
│   │   └── cache.py                           # Redis wrapper
│   ├── ingestion/
│   │   ├── worker.py                          # Async batch ingester (KITE-first)
│   │   ├── yahoo_client.py                    # Yahoo OHLCV (fallback)
│   │   └── kite_historical_client.py          # KITE historical OHLCV
│   ├── screening/
│   │   ├── indicators.py                      # EMA / RSI / BB / ATR / MACD / Supertrend
│   │   ├── strategies.py                      # 15 strategy functions
│   │   └── strategy_engine.py                 # Concurrent runner + _paper_trade
│   └── paper/
│       ├── trader.py                          # auto_enter / exits / sweep / cooldown
│       └── kite_prices.py                     # Sync KITE LTP for paper-close cron
├── database/
│   ├── schema.sql                             # Core tables
│   ├── nifty100_stocks.sql                    # Universe seed
│   ├── add_users.sql                          # Auth table
│   ├── add_direction_column.sql               # LONG/SHORT migration
│   ├── add_strategy_signals.sql               # Live signals table
│   ├── add_paper_trading.sql                  # virtual_portfolio + virtual_trades
│   ├── add_broker_config.sql                  # user_broker_config
│   ├── add_strategy_prices.sql                # strategy_entry/exit_price columns
│   └── repair_paper_trades.sql                # One-shot data cleanup
├── cron/
│   └── stocktracker.cron                      # ingest / screen / strategies / paper-close / watchdog
├── assets/
│   ├── css/app.css                            # Sidebar + nav-link styles
│   └── js/
│       ├── auth.js                            # Session guard + global fetch interceptor
│       ├── sidebar.js                         # Sidebar collapse persistence
│       ├── api.js                             # API fetch wrapper
│       ├── broker.js                          # Broker settings modal
│       ├── livePrices.js                      # /api/market/quote helper + DOM overlay
│       ├── chart.js                           # Lightweight-charts modal
│       ├── home.js                            # Dashboard page
│       ├── dashboard.js                       # Screener page (legacy naming)
│       ├── strategies.js                      # Strategy explorer page
│       └── paper.js                           # Paper trading page (5 tabs)
├── login.html
├── index.html         (Dashboard)
├── screener.html      (Technical Screener)
├── strategies.html    (Strategy Explorer)
├── paper-trading.html (Paper Trading Simulator)
├── zero.html          (KITE token landing)
└── guide.html         (this document)