How maheshumale/workspace1 works
1. Overall shape
This repo is a two-tier trading terminal: a Next.js frontend on port 3000 and a Python FastAPI market engine on port 3035. The critical boundary is that the browser and TypeScript app do not talk to Upstox directly; all broker and market-data access is funneled through the Python service.
2. User-facing terminal
The main UI lives under src/app and src/components/terminal. It renders the trading workspace, including spot/option charts, mini option chain, PCR view, quick order panel, instrument search, and the 7-strike signal page. The UI is built with React, Tailwind, shadcn/ui primitives, lightweight-charts, and Zustand state.
3. Next.js API proxy layer
src/app/api/* contains the frontend’s backend-for-frontend endpoints. These routes mostly proxy requests to the Python engine for candles, instruments, option chain, PCR, replay, config, health, and 7-strike signal data. This keeps the browser-side code simple and creates a stable internal API surface for the terminal components.
4. Data-fetching and state flow in the frontend
The main data flow is: UI components → React hooks → src/lib/data-provider.ts / proxy routes → Python engine. Hooks like use-market-data.ts and use-trading-engine.ts feed the terminal, while src/store/trading-store.ts centralizes UI and instrument selection state across charts and panels.
5. Python market engine
The Python app in python-engine/ is the core domain service. main.py exposes FastAPI routes, market_engine.py orchestrates the logic, and upstox_api.py wraps the official Upstox SDK with caching and async execution. This layer is responsible for live market data retrieval, calculations, and domain-specific outputs such as the 7-strike signal matrix.
6. 7-strike analysis pipeline
The 7-strike subsystem computes COI PCR over an ATM ±3 strike window and derives LONG/SHORT/NEUTRAL signals plus confidence and trade suggestions. The Python routes under python-engine/routes/ and mirrored Next proxy routes under src/app/api/7strike/* expose the matrix, current signals, historical signals, and suggested trades.
7. Market data endpoints
The engine’s main data services are candles, options, instruments, pcr, and replay. These endpoints provide the terminal with live candles, option-chain snapshots, expiry/search data, PCR values, and historical replay sessions. The frontend charts and tables are built directly from these data shapes.
8. Persistence boundaries
There are two distinct storage concerns. The Python engine uses DuckDB (python-engine/python-engine/data/trading.duckdb) for historical market/signal data and replay. Separately, the root project includes Prisma + SQLite (prisma/schema.prisma, db/custom.db) for app-side configuration or local persistence. These stores serve different purposes and are not the same data layer.
9. Configuration and session control
Upstox connection state is managed through config endpoints, especially the token update/connect/disconnect flow. The UI includes a configuration dialog for updating the access token at runtime, and the Python health endpoint reports whether the engine is connected. This is important because the token expires frequently and directly affects system mode.
10. Deployment and runtime topology
The repo supports local startup with platform-specific scripts and a production gateway via Caddy. The documented topology is Browser → Next.js → Python Engine → Upstox API, with Caddy acting as a reverse proxy in front of the app in deployed setups. Ports are fixed and important for the diagram: 3000 for Next.js, 3035 for Python, and 81 for Caddy.
11. Auxiliary mini-services
mini-services/ contains smaller Bun-based services, including a ws-relay and a trimmed trading-engine implementation. These appear to be supporting or experimental runtime variants rather than the main path. If diagramming the repo, treat them as auxiliary services around the core Next.js/Python architecture, not the primary production flow.
12. Example and reference material
The examples/websocket area and the various agent-ctx / ARCHITECTURE.md files are documentation and sandbox material that help explain or test the system’s boundaries. They do not drive the main terminal flow, but they reinforce that websocket-style realtime delivery is an architectural concern in the broader project.
Main entry points: main.py FastAPI app · page.tsx Terminal UI · route.ts API proxy · use-market-data.ts Data hooks
Components 20
Next.js terminal
Browser UI, API proxy routes, and client state.
- Terminal UI · Trading workspace with charts, order entry, search, and 7-strike views.
src/app/page.tsx - Terminal widgets · Spot/option charts, mini chain, PCR, order panel, search, and config dialog.
src/components/terminal/option-chart.tsx - Trading state · Shared instrument selection and UI state across the terminal.
src/store/trading-store.ts - Data hooks · Market-data and trading-engine hooks that feed terminal components.
src/hooks/use-market-data.ts - Data provider · Frontend abstraction for fetching through the Next.js API layer.
src/lib/data-provider.ts - API proxy · Backend-for-frontend routes for candles, instruments, option chain, PCR, replay, config, health, and 7-strike.
src/app/api/candles/route.ts - 7-strike page · Dedicated page for signal matrix, historical signals, and suggested trades.
src/app/7strike/page.tsx - Config & health · Upstox token update and engine health endpoints.
src/app/api/config/upstox/route.ts
Python engine
FastAPI market engine and Upstox integration.
- FastAPI app · Main market engine HTTP surface on port 3035.
python-engine/main.py - Market engine · Coordinates domain logic, calculations, and output shaping.
python-engine/market_engine.py - Upstox adapter · Official Upstox SDK integration with caching and async execution.
python-engine/upstox_api.py - Engine routes · Candle, options, instruments, PCR, replay, and 7-strike endpoints.
python-engine/routes/candles.py - 7-strike analysis · Computes COI PCR in the ATM ±3 strike window and derives LONG/SHORT/NEUTRAL signals.
python-engine/routes/seven_strike.py
Aux services
Supporting Bun services and websocket experiments.
- WS relay · Auxiliary websocket relay service.
mini-services/ws-relay/index.ts - Mini trading engine · Trimmed experimental trading-engine variant with its own routes and simulator.
mini-services/trading-engine/index.ts
Runtime & deploy
Process scripts and reverse proxy.
- Caddy gateway · Deployed entrypoint in front of the app stack.
Caddyfile - Startup scripts · Local launch and build scripts for Next.js and engine processes.
start.sh
Persistence
Separate local stores for engine history and app state.
- DuckDB history · Local market, signal, and replay data store.
python-engine/python-engine/data/trading.duckdb - SQLite config · Root-level Prisma-backed local database.
db/custom.db
Reference material
Architecture notes and examples that explain the system.
- WS example · Reference websocket frontend and server sandbox.
examples/websocket/frontend.tsx
Connections 23
- Terminal UI → Terminal widgets: renders · The page composes the terminal workspace from specialized widgets.
- Terminal widgets → Data hooks: uses · Widgets subscribe to market data and trading state through hooks.
- Data hooks → Trading state: reads/writes · Hooks coordinate selections and UI state through the store.
- Data hooks → Data provider: fetches via · Hooks rely on the shared data-provider abstraction.
- Data provider → API proxy: calls · Frontend requests go through Next.js API endpoints.
- API proxy → FastAPI app: proxies to · Browser-side requests are funneled into the Python engine.
- Terminal UI → 7-strike page: navigates to · Separate 7-strike terminal page.
- 7-strike page → API proxy: uses · 7-strike UI consumes the proxied matrix and signal endpoints.
- API proxy → Config & health: includes · Config and health are exposed through the same BFF surface.
- FastAPI app → Market engine: orchestrates · FastAPI delegates domain work to the engine core.
- Market engine → Upstox adapter: queries · Core logic pulls live market data through the Upstox adapter.
- FastAPI app → Engine routes: mounts · Route modules expose the market-data and replay API surface.
- Engine routes → 7-strike analysis: includes · 7-strike routes are backed by the signal pipeline.
- Engine routes → DuckDB history: persists/reads · Historical and replay endpoints use DuckDB.
- 7-strike analysis → DuckDB history: stores history · Signal history and replay data are kept in DuckDB.
- Config & health → Upstox adapter: configures · Runtime token updates affect the broker connection.
- Config & health → SQLite config: may persist · App-side configuration uses the separate SQLite/Prisma store.
- Startup scripts → Terminal UI: starts · Scripts launch the Next.js frontend.
- Startup scripts → FastAPI app: starts · Scripts launch the Python engine.
- Caddy gateway → Terminal UI: proxies · Deployed traffic is routed through Caddy to the app stack.
- Caddy gateway → FastAPI app: proxies · Caddy can forward engine requests in deployed setups.
- Mini trading engine → WS relay: pairs with · Auxiliary runtimes support websocket-style delivery and simulation.
- WS example → WS relay: demonstrates · Reference material for websocket architecture and behavior.