# maheshumale/workspace1 architecture

> Architecture diagram of the GitHub repository maheshumale/workspace1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maheshumale/workspace1
- Repository: https://github.com/maheshumale/workspace1

## Overview

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: [`python-engine/main.py`](https://github.com/maheshumale/workspace1/blob/main/python-engine/main.py) (FastAPI app), [`src/app/page.tsx`](https://github.com/maheshumale/workspace1/blob/main/src/app/page.tsx) (Terminal UI), [`src/app/api/candles/route.ts`](https://github.com/maheshumale/workspace1/blob/main/src/app/api/candles/route.ts) (API proxy), [`src/hooks/use-market-data.ts`](https://github.com/maheshumale/workspace1/blob/main/src/hooks/use-market-data.ts) (Data hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js terminal"]
  node_browser_terminal["Terminal UI<br/>Next.js app<br/>[page.tsx]"]
  node_terminal_components["Terminal widgets<br/>React components<br/>[option-chart.tsx]"]
  node_client_state["Trading state<br/>Zustand store<br/>[trading-store.ts]"]
  node_data_hooks["Data hooks<br/>React hooks<br/>[use-market-data.ts]"]
  node_data_provider["Data provider<br/>BFF client<br/>[data-provider.ts]"]
  node_proxy_routes["API proxy<br/>Next route handlers<br/>[route.ts]"]
  node_sevenstrike_page["7-strike page<br/>Next.js route<br/>[page.tsx]"]
  node_health_config["Config & health<br/>API routes<br/>[route.ts]"]
end

subgraph group_engine["Python engine"]
  node_engine_api["FastAPI app<br/>Python service<br/>[main.py]"]
  node_engine_core["Market engine<br/>Orchestrator<br/>[market_engine.py]"]
  node_upstox_wrapper["Upstox adapter<br/>SDK wrapper<br/>[upstox_api.py]"]
  node_engine_routes["Engine routes<br/>Route modules<br/>[candles.py]"]
  node_sevenstrike_pipeline["7-strike analysis<br/>Signal pipeline<br/>[seven_strike.py]"]
end

subgraph group_aux["Aux services"]
  node_ws_relay["WS relay<br/>Bun service<br/>[index.ts]"]
  node_mini_trader["Mini trading engine<br/>Bun service<br/>[index.ts]"]
end

subgraph group_infra["Runtime & deploy"]
  node_caddy_gateway["Caddy gateway<br/>Reverse proxy"]
  node_runtime_scripts["Startup scripts<br/>Shell/PowerShell<br/>[start.sh]"]
end

subgraph group_storage["Persistence"]
  node_duckdb_store[("DuckDB history<br/>Historical store<br/>[trading.duckdb]")]
  node_sqlite_store[("SQLite config<br/>App persistence<br/>[custom.db]")]
end

subgraph group_docs["Reference material"]
  node_websocket_example["WS example<br/>Example app<br/>[frontend.tsx]"]
end

node_browser_terminal -->|"renders"| node_terminal_components
node_terminal_components -->|"uses"| node_data_hooks
node_data_hooks -->|"reads/writes"| node_client_state
node_data_hooks -->|"fetches via"| node_data_provider
node_data_provider -->|"calls"| node_proxy_routes
node_proxy_routes -->|"proxies to"| node_engine_api
node_browser_terminal -->|"navigates to"| node_sevenstrike_page
node_sevenstrike_page -->|"uses"| node_proxy_routes
node_proxy_routes -->|"includes"| node_health_config
node_engine_api -->|"orchestrates"| node_engine_core
node_engine_core -->|"queries"| node_upstox_wrapper
node_engine_api -->|"mounts"| node_engine_routes
node_engine_routes -->|"includes"| node_sevenstrike_pipeline
node_engine_routes -->|"persists/reads"| node_duckdb_store
node_sevenstrike_pipeline -->|"stores history"| node_duckdb_store
node_health_config -->|"configures"| node_upstox_wrapper
node_health_config -.->|"may persist"| node_sqlite_store
node_runtime_scripts -->|"starts"| node_browser_terminal
node_runtime_scripts -->|"starts"| node_engine_api
node_caddy_gateway -->|"proxies"| node_browser_terminal
node_caddy_gateway -->|"proxies"| node_engine_api
node_mini_trader -.->|"pairs with"| node_ws_relay
node_websocket_example -.->|"demonstrates"| node_ws_relay

click node_browser_terminal "https://github.com/maheshumale/workspace1/blob/main/src/app/page.tsx"
click node_terminal_components "https://github.com/maheshumale/workspace1/blob/main/src/components/terminal/option-chart.tsx"
click node_client_state "https://github.com/maheshumale/workspace1/blob/main/src/store/trading-store.ts"
click node_data_hooks "https://github.com/maheshumale/workspace1/blob/main/src/hooks/use-market-data.ts"
click node_data_provider "https://github.com/maheshumale/workspace1/blob/main/src/lib/data-provider.ts"
click node_proxy_routes "https://github.com/maheshumale/workspace1/blob/main/src/app/api/candles/route.ts"
click node_sevenstrike_page "https://github.com/maheshumale/workspace1/blob/main/src/app/7strike/page.tsx"
click node_health_config "https://github.com/maheshumale/workspace1/blob/main/src/app/api/config/upstox/route.ts"
click node_engine_api "https://github.com/maheshumale/workspace1/blob/main/python-engine/main.py"
click node_engine_core "https://github.com/maheshumale/workspace1/blob/main/python-engine/market_engine.py"
click node_upstox_wrapper "https://github.com/maheshumale/workspace1/blob/main/python-engine/upstox_api.py"
click node_engine_routes "https://github.com/maheshumale/workspace1/blob/main/python-engine/routes/candles.py"
click node_sevenstrike_pipeline "https://github.com/maheshumale/workspace1/blob/main/python-engine/routes/seven_strike.py"
click node_duckdb_store "https://github.com/maheshumale/workspace1/blob/main/python-engine/python-engine/data/trading.duckdb"
click node_sqlite_store "https://github.com/maheshumale/workspace1/blob/main/db/custom.db"
click node_caddy_gateway "https://github.com/maheshumale/workspace1/tree/main/Caddyfile"
click node_runtime_scripts "https://github.com/maheshumale/workspace1/blob/main/start.sh"
click node_ws_relay "https://github.com/maheshumale/workspace1/blob/main/mini-services/ws-relay/index.ts"
click node_mini_trader "https://github.com/maheshumale/workspace1/blob/main/mini-services/trading-engine/index.ts"
click node_websocket_example "https://github.com/maheshumale/workspace1/blob/main/examples/websocket/frontend.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_terminal,node_terminal_components,node_client_state,node_data_hooks,node_data_provider,node_proxy_routes,node_sevenstrike_page,node_health_config toneBlue
class node_engine_api,node_engine_core,node_upstox_wrapper,node_engine_routes,node_sevenstrike_pipeline toneAmber
class node_ws_relay,node_mini_trader toneMint
class node_caddy_gateway,node_runtime_scripts toneRose
class node_duckdb_store,node_sqlite_store toneIndigo
class node_websocket_example toneTeal
```

## Components

### Next.js terminal

Browser UI, API proxy routes, and client state.

- [Terminal UI](https://github.com/maheshumale/workspace1/blob/main/src/app/page.tsx): Next.js app · Trading workspace with charts, order entry, search, and 7-strike views. · `src/app/page.tsx`
- [Terminal widgets](https://github.com/maheshumale/workspace1/blob/main/src/components/terminal/option-chart.tsx): React components · Spot/option charts, mini chain, PCR, order panel, search, and config dialog. · `src/components/terminal/option-chart.tsx`
- [Trading state](https://github.com/maheshumale/workspace1/blob/main/src/store/trading-store.ts): Zustand store · Shared instrument selection and UI state across the terminal. · `src/store/trading-store.ts`
- [Data hooks](https://github.com/maheshumale/workspace1/blob/main/src/hooks/use-market-data.ts): React hooks · Market-data and trading-engine hooks that feed terminal components. · `src/hooks/use-market-data.ts`
- [Data provider](https://github.com/maheshumale/workspace1/blob/main/src/lib/data-provider.ts): BFF client · Frontend abstraction for fetching through the Next.js API layer. · `src/lib/data-provider.ts`
- [API proxy](https://github.com/maheshumale/workspace1/blob/main/src/app/api/candles/route.ts): Next route handlers · 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](https://github.com/maheshumale/workspace1/blob/main/src/app/7strike/page.tsx): Next.js route · Dedicated page for signal matrix, historical signals, and suggested trades. · `src/app/7strike/page.tsx`
- [Config & health](https://github.com/maheshumale/workspace1/blob/main/src/app/api/config/upstox/route.ts): API routes · Upstox token update and engine health endpoints. · `src/app/api/config/upstox/route.ts`

### Python engine

FastAPI market engine and Upstox integration.

- [FastAPI app](https://github.com/maheshumale/workspace1/blob/main/python-engine/main.py): Python service · Main market engine HTTP surface on port 3035. · `python-engine/main.py`
- [Market engine](https://github.com/maheshumale/workspace1/blob/main/python-engine/market_engine.py): Orchestrator · Coordinates domain logic, calculations, and output shaping. · `python-engine/market_engine.py`
- [Upstox adapter](https://github.com/maheshumale/workspace1/blob/main/python-engine/upstox_api.py): SDK wrapper · Official Upstox SDK integration with caching and async execution. · `python-engine/upstox_api.py`
- [Engine routes](https://github.com/maheshumale/workspace1/blob/main/python-engine/routes/candles.py): Route modules · Candle, options, instruments, PCR, replay, and 7-strike endpoints. · `python-engine/routes/candles.py`
- [7-strike analysis](https://github.com/maheshumale/workspace1/blob/main/python-engine/routes/seven_strike.py): Signal pipeline · 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](https://github.com/maheshumale/workspace1/blob/main/mini-services/ws-relay/index.ts): Bun service · Auxiliary websocket relay service. · `mini-services/ws-relay/index.ts`
- [Mini trading engine](https://github.com/maheshumale/workspace1/blob/main/mini-services/trading-engine/index.ts): Bun service · 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](https://github.com/maheshumale/workspace1/tree/main/Caddyfile): Reverse proxy · Deployed entrypoint in front of the app stack. · `Caddyfile`
- [Startup scripts](https://github.com/maheshumale/workspace1/blob/main/start.sh): Shell/PowerShell · 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](https://github.com/maheshumale/workspace1/blob/main/python-engine/python-engine/data/trading.duckdb): Historical store · Local market, signal, and replay data store. · `python-engine/python-engine/data/trading.duckdb`
- [SQLite config](https://github.com/maheshumale/workspace1/blob/main/db/custom.db): App persistence · Root-level Prisma-backed local database. · `db/custom.db`

### Reference material

Architecture notes and examples that explain the system.

- [WS example](https://github.com/maheshumale/workspace1/blob/main/examples/websocket/frontend.tsx): Example app · Reference websocket frontend and server sandbox. · `examples/websocket/frontend.tsx`

## Connections

- 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.