Range Analysis — Overview
Range Analysis measures the high–low range of a repeating time window and shows how price moved inside it. The window can be a slice of each trading day, an expiry cycle, or a calendar span.
- What the page must do: see Requirements (V1).
- This page: how it is built.
| Page | /range-analysis (Developer sidebar, DEVELOPER rank) |
| Frontend | frontend/src/pages/RangeAnalysis/ |
| Backend | backend/app/api/range_analysis.py, prefix /api/range-analysis, same DEVELOPER access check as the other data routes |
| Rules | NeoWave wave-chart rules: Wave Chart Construction (NeoWave), mirrored in backend/CLAUDE.md section 4 |
Architecture
Tab 1 (User Input) rangeEngine.js (pure JS) backend /api/range-analysis
───────────────── ──────────────────────── ───────────────────────────
exchange / symbol ───────────────────────────────────────────────────────▶ /symbols (dropdown)
expiry basis ───────────────────────────────────────────────────────▶ /expiries (expiry calendar)
(always) ───────────────────────────────────────────────────────▶ /calendar (holidays, sessions)
time frame rules ─▶ validateConfig / resolveWindows ─▶ right panel: rule, next windows, all windows
[Run] ─▶ planRun → windows + {from, to, step}
│ NSE / MCX ──────────────────────▶ /prices (base bars)
│ BSE → generateBars (mock)
buildResult ◀───────┘
Tabs 2 and 3 ◀─ { cfg, windows[ {label, start, end, candle, bars, base, …} ], prices }
The window logic runs in the browser. rangeEngine.js holds all of it: validation, window
resolution, NeoWave order, and aggregation. The backend only supplies data. V2 may move
planRun / buildResult server-side for very large 1-minute ranges.
Frontend files
| File | Role |
|---|---|
RangeAnalysis.jsx | Page shell and tabs. Loads symbols, expiries and the calendar (React Query, 30 min cache), and runs the analysis (fetches /prices or uses mock data for BSE). |
rangeEngine.js | Constants, validation, resolveWindows (raw windows → no-overlap → session cut), expiry and trading calendars, planRun, buildResult, NeoWave orderOf, wavePoints, countMonowaves, childBars, mock bar generator. |
InputTab.jsx | Tab 1 form and right panel: rule, next windows, all windows, named errors. |
CandleTab.jsx / WaveTab.jsx | Tabs 2 and 3 (two-column layout). |
ExcelChart.jsx / SidePanes.jsx | Excel-style child chart and the right-hand child and details panes. |
The AmiBroker-style canvas chart itself (candle / bar / wave / line, selector,
B/E range markers, zoom and pan) is no longer page-specific — it moved to the
shared frontend/src/components/TEChart.jsx so other pages (e.g. Corporate
Actions) can reuse it. See Frontend Guide "Reusable Components"
for its full props reference.
Time convention
Every timestamp is exchange wall-clock time stored as if it were UTC, in seconds: 09:15 IST
is stored as 09:15Z. The charts can then show exchange time without any timezone conversion.
The backend returns /prices timestamps in the same convention.
Window boundaries: windows are half-open on the bar start time, so a bar belongs to a
window when start <= t < end.
API reference
All endpoints are GET requests.
/symbols?exchange=NSE|MCX
Symbols for the dropdown.
- NSE: index underlyings (
scr_mastertyp 2) that have index futures. - MCX: active symbols only — a
typ = 20row with a contract that has not expired (edate >= CURRENT_DATE) and rows inscr_mcxsp_eod. That's 28 of the 151 rows on the VPS; the spot condition drops MCXBULLDEX / MCXMETLDEX. The spot condition is skipped if the spot table doesn't exist.
/expiries?exchange=&symbol=&basis=FUT|OPT
Returns {monthly, weekly, weeklyFirst, weeklyLast, dataFrom, dataTo}.
- NSE: monthly expiries = index futures expiries. Weekly expiries = option expiries that are not monthly, fall on or before the last futures expiry, are more than 3 days from any monthly expiry, and are within 14 days of another weekly candidate.
- MCX: futures or options expiries, depending on
basis. There are no weekly expiries.
/calendar?exchange=NSE|BSE|MCX
Returns {holidays, specialSessions, holidaysTo, latestEod}.
holidays: full closures. For MCX, only rows that are closed in both sessions.specialSessions: days with their own hours:kind: "special"—specialdaysrows (weekend sessions, Muhurat);kind: "partial"— MCX evening-only days (17:00 to close): explicit session-flag rows, plus NSE weekday holidays that are not MCX full holidays. Dates afterholidaysToare markedassumed.
holidaysTo: how far the calendar is known. For MCX this is the later of the newest holiday row and the latest MCX EOD date, because MCX holidays are derived from traded dates. After the 2026-09-26 rebuild, the newest row is 2026-04-03 but the calendar is known to 2026-09-23.- BSE uses the NSE rows.
/prices?exchange=NSE|MCX&symbol=&from=&to=&step=1|75
Returns base bars as columns: {source, resolution, count, bars: {t, o, h, l, c}}.
- NSE: spot from the IEOD Parquet store via
Con_Price_Getter(nseieodrule 2).- GDFL stamps each bar's end time (
09:15:59), so times are floored to the bar start. - With
step=75, bars are grouped from 09:15. - A symbol with no spot data returns 404 (for example FINNIFTY today). There is no fallback to futures, because NeoWave requires spot.
- GDFL stamps each bar's end time (
- MCX: spot daily bars from
scr_mcxsp_eod, withtset to the day at 09:00. If the reference database has no such table, it is read from the local database. - BSE: not served; the page uses mock prices.
Configuration
# backend/.env (local development only)
RANGE_ANALYSIS_DB=VPS # read this router's data from the VPS DB; LOCAL = this machine
VPS_DB_REMOTE_HOST=103.178.166.188 # VPS_DB_HOST is "localhost" from the VPS's own point of view
- Read-only: the VPS connection is opened with
default_transaction_read_only=on, so the database refuses any write. - On the VPS itself (
APP_ENV=VPS) the setting is ignored, because the app's own database already is the VPS one. - NSE prices always come from the IEOD store of the machine running the backend. A local store is only as current as its last pack.
Operations and troubleshooting
| Symptom | Cause / fix |
|---|---|
Every /api/range-analysis/... call returns 404 | The backend was started before the router existed or changed. Restart it; run uvicorn with --reload in development. .env changes always need a manual restart. |
| "Holiday calendar not loaded: trading days are Mon to Fri" | /calendar failed (often the 404 above). |
| Right panel says "Expiries: Mock calendar" for NSE/MCX | /expiries failed. The note next to it shows the error. |
| Run says "No NSE spot data for X" | That index has no spot series in the IEOD store. |
| NSE windows after a date are all skipped | The IEOD store ends there. Pack or sync newer data. |
| MCX prices stop at a date | scr_mcxsp_eod is behind. See mcx_spot_downloader.py. |
| MCX evening-only days marked "assumed" | They fall after holidaysTo. Rebuild the MCX calendar: python -m mcxeod.mcx_history. |
Testing without the UI
- Backend:
fastapi.testclient.TestClient(app)inside onewithblock. The pooled async connections don't survive the separate event loops that one-off calls create. - Engine:
rangeEngine.jshas no imports, so it runs directly in Node. Copy it to a.mjsfile and callvalidateConfig,planRun,buildResultand so on with saved API responses.