TRADESTACK / DEVELOPER DOCUMENTATION

Understand the system.
Build with evidence.

Source-grounded engineering documentation for the Python market engine and Node.js Upstox gateway. Distinguish the implemented paper workflow from research experiments and future plans.

PYTHON 3.12NODE.JS 22+REDISMONGODBPARQUETPAPER-ONLY
01 / SYSTEM OVERVIEW

Two services.
A traceable paper workflow.

The trading engine ingests live market data and generates rule-based decisions. The gateway authenticates configured Upstox accounts and provides controls, history, and analytics. Redis coordinates ephemeral state and commands; MongoDB stores historical account records; Parquet files hold recorded market events.

01Upstox market feedMarket ticks, instrument context and available depth
02Python analysis and risk engineCandle construction, setups, filters, scoring, positions
03Paper execution and journalSimulated orders, lifecycle events, signal/trade records
04Node dashboard and researchAuthenticated controls, MongoDB history, replay tools
02 / CODE ORGANIZATION

Where the work happens.

Python · algo-execution-service

app/main.py FastAPI control API and Redis command publication; app/services/trading_manager.py per-user session orchestration; app/analyzer/ indicators, strategy context, market structure and filters; app/services/risk_engine.py Redis-backed capital protection; app/services/trade_lifecycle_manager.py active trade state; app/services/market_data_recorder.py and Parquet modules for capture; scripts/run_session_backtest.py for historical replay.

Node · upstox_api_integration

routes/router.js authenticated HTTP routes; security/session.js session and account ownership checks; controllers/trading/trading-with-python-backend.js controls and gateway-to-engine requests; controllers/trading/paper-history.js session/trade/signal/analytics queries; public/trading-dashboard.html documented six-module workspace.

Infrastructure

Redis manages temporary coordination and risk keys. MongoDB stores durable trades, signals and supporting research/audit data. Date-partitioned local recordings and session manifests support replay; they are not part of this static website.

03 / DATA CONTRACTS

Events you can trace.

Field names below come from the documented repository models and query projections. These are examples of structure, not a guarantee that every historical record contains every field.

Trade record

trade_id, session_id, user_id, strategy_version, symbol, trade_type, mode, entry, exit, risk_params, pnl, status.

Signal record

signal_id, timestamp, session_id, signal_data, analysis, indicators, status and rejection_reason. Link to trades using the recorded entry signal identifier and compatible ID conversion.

Recorded session

A manifest can carry session_start, effective_config_snapshot, option_chain_snapshot, decision and session_stop. Recorder metadata indicates completeness and dropped events. Invalid or incomplete sessions must not be assumed replay-valid.

Example only — synthetic trade shape, no account data
{
  "mode": "PAPER",
  "strategy_version": "strategy-v2026.10.15",
  "status": "CLOSED",
  "entry": {"signal_id": "example-signal"},
  "exit": {"reason": "STOP_LOSS"},
  "pnl": {"net_pnl": null}
}

The null amount is intentional: this page never invents a trade result.

04 / DEVELOPMENT SETUP

Local development boundaries.

These commands are based on each repository's setup guide. You need authorized access to the Python repository, an Upstox developer application, and independently configured MongoDB/Redis services. No secrets or account data are included here.

Python engine · local loopback
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
# Configure local secrets, MongoDB and Redis in .env
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
Node.js gateway · separate checkout
git clone https://github.com/vishaldkale01/upstox_api_integration.git
cd upstox_api_integration
npm ci
cp .env.example .env
# Configure APP_ORIGIN, Redis, MongoDB, OAuth and engine token
npm start
The gateway's ENGINE_API_TOKEN must match the engine, with secrets stored only on the server. Both applications must select the same MongoDB database. Keep service ports private; the Cloudflare Pages marketing website needs neither backend connected.
05 / VERIFY BEFORE CLAIMING

Testing isn't the same
as trading profitability.

Unit tests, integration checks and deterministic replay serve different purposes. Passing code tests does not establish production uptime, real-money execution readiness, or positive strategy expectancy.

Python unit and research checks
python -m pip install -r requirements-dev.txt
python -m pytest tests/ -v
python scripts/run_session_backtest.py --help
python scripts/run_session_backtest.py --list-dates
Node.js gateway and browser smoke checks
npm test
npx playwright install chromium
npm run test:browser
Recorded replay acceptance

Confirm session start and stop events, complete recorder metadata, zero dropped events, available warmup/chain context, time-aligned input events and documented fill/fee assumptions. Replay must not silently treat missing context as validated results.

Reporting acceptance

Distinguish gross from net P&L, classify exit reasons correctly, show brokerage estimates, disclose sample and session completeness, and explain any mismatch between paper and replay execution.

06 / PRIVACY & SAFETY

Make the separation explicit.

Marketing website

Static Cloudflare Pages content only. It has no broker login, no MongoDB/Redis credentials, no trading API integration, and no public signup or live orders.

Gateway

Requires an authenticated account session, server-held broker credentials, CSRF verification and user ownership checks. Public routes for direct live order placement and modification are disabled in the current gateway.

Engine

Accepts only authenticated gateway requests via a shared server secret. The documented configuration remains paper-only, with optional AI validation disabled by default.

07 / SOURCE & SCOPE

What these docs verify.

Reviewed source files and README/setup guides from the connected Python engine and Node gateway as of 19 November 2026. The gateway repository is public; the Python engine remains private. This documentation intentionally abstracts private implementation details while describing the module boundaries visible in code.

Current exceptions: live broker execution is not exposed through the public gateway, research replay has known parity/fidelity limitations, and an optional AI validator is not enabled by default. Public documentation is not an independent security audit or runtime certification.