# vigsank/kite-paper-node architecture

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

- Interactive diagram: https://gitdiagram.com/vigsank/kite-paper-node
- Repository: https://github.com/vigsank/kite-paper-node

## Overview

kite-paper-node is a drop-in Zerodha Kite Connect paper-trading mock. A strategy initiates requests through the in-process SDK, REST, or MCP surface; those interfaces reach the mock engine, which coordinates simulated orders and portfolio state alongside generated or replayed market data. The README also documents persistent state and WebSocket ticker modes. Some subsystem links rely on the SOURCE INDEX or README because the relevant wiring was not excerpted; uncertain links are omitted.

Main entry points: [`src/mock-engine.ts`](https://github.com/vigsank/kite-paper-node/blob/main/src/mock-engine.ts) (Mock engine), [`src/services`](https://github.com/vigsank/kite-paper-node/tree/main/src/services) (Broker services), [`src/market/generator-pool.ts`](https://github.com/vigsank/kite-paper-node/blob/main/src/market/generator-pool.ts) (Generator pool), [`src/market/tick-event-bus.ts`](https://github.com/vigsank/kite-paper-node/blob/main/src/market/tick-event-bus.ts) (Tick event bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_sdk["Kite SDK mock"]
  node_ticker["Kite ticker mock"]
  node_rest["REST API<br/>[rest-server.ts]"]
  node_ws["WebSocket server<br/>[ws-server.ts]"]
  node_packer["Binary packet packing<br/>[binary-packer.ts]"]
  node_mcp["MCP tools and server<br/>[tools.ts]"]
end

subgraph group_orchestration["Mock orchestration"]
  node_engine["Mock engine<br/>[mock-engine.ts]"]
  node_services["Broker services"]
end

subgraph group_trading["Trading and portfolio"]
  node_gtt["GTT triggers<br/>[gtt-engine.ts]"]
  node_orders["Order lifecycle<br/>[order-engine.ts]"]
  node_matching["Order matching<br/>[matching-engine.ts]"]
  node_ledger["Ledger and fills<br/>[ledger-engine.ts]"]
  node_positions["Positions<br/>[position-engine.ts]"]
  node_margins["Margin calculations<br/>[margin-engine.ts]"]
end

subgraph group_market["Market data"]
  node_pool["Generator pool<br/>[generator-pool.ts]"]
  node_walk["Random-walk generator"]
  node_csv["CSV market data"]
  node_replay["Historical replay"]
  node_history["Tick history"]
  node_bus["Tick event bus<br/>[tick-event-bus.ts]"]
end

subgraph group_state["State and persistence"]
  node_store[("Broker state store<br/>[state-store.ts]")]
  node_persistence[("State persistence")]
end

node_strategy(("Strategy client"))
node_externaldata["CSV data files"]

node_strategy -->|"calls"| node_sdk
node_strategy -->|"requests"| node_rest
node_strategy -->|"invokes tools"| node_mcp
node_strategy -->|"subscribes"| node_ticker
node_sdk -->|"delegates to"| node_engine
node_rest -->|"routes requests"| node_services
node_rest -->|"uses"| node_engine
node_mcp -->|"calls"| node_engine
node_ticker -.->|"receives ticks"| node_bus
node_ws -.->|"streams ticks"| node_bus
node_ws -.->|"packs packets"| node_packer
node_engine -->|"coordinates state"| node_store
node_engine -->|"constructs"| node_gtt
node_engine -->|"wires services"| node_services
node_engine -->|"configures market data"| node_pool
node_pool -->|"creates generators"| node_walk
node_pool -->|"uses data provider"| node_csv
node_csv -->|"loads"| node_externaldata
node_pool -.->|"emits ticks"| node_bus
node_replay -->|"emits replay ticks"| node_bus
node_bus -->|"dispatches ticks"| node_matching
node_matching -->|"updates fills"| node_orders
node_matching -->|"executes fills"| node_ledger
node_ledger -->|"applies fills"| node_positions
node_ledger -->|"calculates margin"| node_margins
node_orders -->|"checks affordability"| node_margins
node_orders -->|"stores orders"| node_store
node_positions -->|"updates positions"| node_store
node_margins -->|"reads and updates"| node_store
node_store -.->|"persists snapshot"| node_persistence
node_services -->|"serves quote data"| node_pool
node_services -->|"reads historical data"| node_csv
node_services -->|"reads candles"| node_history

click node_sdk "https://github.com/vigsank/kite-paper-node/blob/main/src/mock-kite-connect.ts"
click node_ticker "https://github.com/vigsank/kite-paper-node/blob/main/src/mock-kite-ticker.ts"
click node_rest "https://github.com/vigsank/kite-paper-node/blob/main/src/server/rest-server.ts"
click node_ws "https://github.com/vigsank/kite-paper-node/blob/main/src/server/ws-server.ts"
click node_packer "https://github.com/vigsank/kite-paper-node/blob/main/src/server/binary-packer.ts"
click node_mcp "https://github.com/vigsank/kite-paper-node/blob/main/src/mcp/tools.ts"
click node_engine "https://github.com/vigsank/kite-paper-node/blob/main/src/mock-engine.ts"
click node_gtt "https://github.com/vigsank/kite-paper-node/blob/main/src/core/gtt-engine.ts"
click node_orders "https://github.com/vigsank/kite-paper-node/blob/main/src/core/order-engine.ts"
click node_matching "https://github.com/vigsank/kite-paper-node/blob/main/src/core/matching-engine.ts"
click node_ledger "https://github.com/vigsank/kite-paper-node/blob/main/src/core/ledger-engine.ts"
click node_positions "https://github.com/vigsank/kite-paper-node/blob/main/src/core/position-engine.ts"
click node_margins "https://github.com/vigsank/kite-paper-node/blob/main/src/core/margin-engine.ts"
click node_services "https://github.com/vigsank/kite-paper-node/tree/main/src/services"
click node_pool "https://github.com/vigsank/kite-paper-node/blob/main/src/market/generator-pool.ts"
click node_walk "https://github.com/vigsank/kite-paper-node/blob/main/src/market/random-walk-generator.ts"
click node_csv "https://github.com/vigsank/kite-paper-node/blob/main/src/market/csv-data-provider.ts"
click node_replay "https://github.com/vigsank/kite-paper-node/blob/main/src/market/historical-replay.ts"
click node_history "https://github.com/vigsank/kite-paper-node/blob/main/src/market/tick-history-buffer.ts"
click node_bus "https://github.com/vigsank/kite-paper-node/blob/main/src/market/tick-event-bus.ts"
click node_store "https://github.com/vigsank/kite-paper-node/blob/main/src/state/state-store.ts"
click node_persistence "https://github.com/vigsank/kite-paper-node/blob/main/src/state/state-persistence.ts"

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_sdk,node_ticker,node_rest,node_ws,node_packer,node_mcp,node_strategy toneBlue
class node_engine,node_services toneAmber
class node_gtt,node_orders,node_matching,node_ledger,node_positions,node_margins toneMint
class node_pool,node_walk,node_csv,node_replay,node_history,node_bus toneRose
class node_store,node_persistence,node_externaldata toneIndigo
```

## Components

### User interfaces

- [Kite SDK mock](https://github.com/vigsank/kite-paper-node/blob/main/src/mock-kite-connect.ts): `src/mock-kite-connect.ts`
- [Kite ticker mock](https://github.com/vigsank/kite-paper-node/blob/main/src/mock-kite-ticker.ts): `src/mock-kite-ticker.ts`
- [REST API](https://github.com/vigsank/kite-paper-node/blob/main/src/server/rest-server.ts): `src/server/rest-server.ts`
- [WebSocket server](https://github.com/vigsank/kite-paper-node/blob/main/src/server/ws-server.ts): `src/server/ws-server.ts`
- [Binary packet packing](https://github.com/vigsank/kite-paper-node/blob/main/src/server/binary-packer.ts): `src/server/binary-packer.ts`
- [MCP tools and server](https://github.com/vigsank/kite-paper-node/blob/main/src/mcp/tools.ts): `src/mcp/tools.ts`

### Mock orchestration

- [Mock engine](https://github.com/vigsank/kite-paper-node/blob/main/src/mock-engine.ts): `src/mock-engine.ts`
- [Broker services](https://github.com/vigsank/kite-paper-node/tree/main/src/services): `src/services`

### Trading and portfolio

- [GTT triggers](https://github.com/vigsank/kite-paper-node/blob/main/src/core/gtt-engine.ts): `src/core/gtt-engine.ts`
- [Order lifecycle](https://github.com/vigsank/kite-paper-node/blob/main/src/core/order-engine.ts): `src/core/order-engine.ts`
- [Order matching](https://github.com/vigsank/kite-paper-node/blob/main/src/core/matching-engine.ts): `src/core/matching-engine.ts`
- [Ledger and fills](https://github.com/vigsank/kite-paper-node/blob/main/src/core/ledger-engine.ts): `src/core/ledger-engine.ts`
- [Positions](https://github.com/vigsank/kite-paper-node/blob/main/src/core/position-engine.ts): `src/core/position-engine.ts`
- [Margin calculations](https://github.com/vigsank/kite-paper-node/blob/main/src/core/margin-engine.ts): `src/core/margin-engine.ts`

### Market data

- [Generator pool](https://github.com/vigsank/kite-paper-node/blob/main/src/market/generator-pool.ts): `src/market/generator-pool.ts`
- [Random-walk generator](https://github.com/vigsank/kite-paper-node/blob/main/src/market/random-walk-generator.ts): `src/market/random-walk-generator.ts`
- [CSV market data](https://github.com/vigsank/kite-paper-node/blob/main/src/market/csv-data-provider.ts): `src/market/csv-data-provider.ts`
- [Historical replay](https://github.com/vigsank/kite-paper-node/blob/main/src/market/historical-replay.ts): `src/market/historical-replay.ts`
- [Tick history](https://github.com/vigsank/kite-paper-node/blob/main/src/market/tick-history-buffer.ts): `src/market/tick-history-buffer.ts`
- [Tick event bus](https://github.com/vigsank/kite-paper-node/blob/main/src/market/tick-event-bus.ts): `src/market/tick-event-bus.ts`

### State and persistence

- [Broker state store](https://github.com/vigsank/kite-paper-node/blob/main/src/state/state-store.ts): `src/state/state-store.ts`
- [State persistence](https://github.com/vigsank/kite-paper-node/blob/main/src/state/state-persistence.ts): `src/state/state-persistence.ts`

### Other components

- **Strategy client**
- **CSV data files**

## Connections

- Strategy client → Kite SDK mock: calls (evidence: `README.md`)
- Strategy client → REST API: requests (evidence: `README.md`)
- Strategy client → MCP tools and server: invokes tools (evidence: `README.md`)
- Strategy client → Kite ticker mock: subscribes (evidence: `README.md`)
- Kite SDK mock → Mock engine: delegates to (evidence: `src/mock-kite-connect.ts`)
- REST API → Broker services: routes requests (evidence: `src/server/rest-server.ts`)
- REST API → Mock engine: uses (evidence: `src/server/rest-server.ts`)
- MCP tools and server → Mock engine: calls (evidence: `src/mcp/tools.ts`)
- Kite ticker mock → Tick event bus: receives ticks
- WebSocket server → Tick event bus: streams ticks
- WebSocket server → Binary packet packing: packs packets
- Mock engine → Broker state store: coordinates state (evidence: `src/mock-engine.ts`)
- Mock engine → GTT triggers: constructs (evidence: `src/mock-engine.ts`)
- Mock engine → Broker services: wires services (evidence: `src/mock-engine.ts`)
- Mock engine → Generator pool: configures market data (evidence: `src/mock-engine.ts`)
- Generator pool → Random-walk generator: creates generators (evidence: `src/market/generator-pool.ts`)
- Generator pool → CSV market data: uses data provider (evidence: `src/market/generator-pool.ts`)
- CSV market data → CSV data files: loads (evidence: `src/market/csv-data-provider.ts`)
- Generator pool → Tick event bus: emits ticks (evidence: `src/market/generator-pool.ts`)
- Historical replay → Tick event bus: emits replay ticks (evidence: `src/market/historical-replay.ts`)
- Tick event bus → Order matching: dispatches ticks (evidence: `src/core/matching-engine.ts`)
- Order matching → Order lifecycle: updates fills (evidence: `src/core/matching-engine.ts`)
- Order matching → Ledger and fills: executes fills (evidence: `src/core/matching-engine.ts`)
- Ledger and fills → Positions: applies fills (evidence: `src/core/ledger-engine.ts`)
- Ledger and fills → Margin calculations: calculates margin (evidence: `src/core/ledger-engine.ts`)
- Order lifecycle → Margin calculations: checks affordability (evidence: `src/core/order-engine.ts`)
- Order lifecycle → Broker state store: stores orders (evidence: `src/core/order-engine.ts`)
- Positions → Broker state store: updates positions (evidence: `src/core/position-engine.ts`)
- Margin calculations → Broker state store: reads and updates (evidence: `src/core/margin-engine.ts`)
- Broker state store → State persistence: persists snapshot
- Broker services → Generator pool: serves quote data (evidence: `src/services/quote-service.ts`)
- Broker services → CSV market data: reads historical data (evidence: `src/services/historical-service.ts`)
- Broker services → Tick history: reads candles (evidence: `src/services/historical-service.ts`)
