# vishaalchandrasekar0203/theory-trade architecture

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

- Interactive diagram: https://gitdiagram.com/vishaalchandrasekar0203/theory-trade
- Repository: https://github.com/vishaalchandrasekar0203/theory-trade

## Overview

Theory Trade is a local operations console for a deterministic high-frequency limit-order execution simulator. The principal workflow is to configure a tagged order and queue/market parameters, optionally calibrate those parameters from public Coinbase L1 data, then start and control a seeded discrete-event episode. The console presents queue position, fills, inventory, event tape, and a deterministic action recommendation with an equation-based explanation. Live calibration is optional and freezes at Start; the market feed does not drive the matching engine. Evidence for unsampled UI and live details is limited to README statements and SOURCE INDEX references.

Main entry points: [`hooks/use-simulation.ts`](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/hooks/use-simulation.ts) (Simulation controller), [`components/console.tsx`](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/console.tsx) (Console shell), [`lib/sim/policy.ts`](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/policy.ts) (Action policy), [`lib/sim/engine.ts`](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/engine.ts) (Discrete-event engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operations console"]
  node_page["App entry<br/>[page.tsx]"]
  node_console_shell["Console shell<br/>[console.tsx]"]
  node_controls["Parameter controls<br/>[controls-panel.tsx]"]
  node_controller["Simulation controller<br/>[use-simulation.ts]"]
end

subgraph group_sim["Execution model"]
  node_policy["Action policy<br/>[policy.ts]"]
  node_formulas["Closed-form model<br/>[formulas.ts]"]
  node_engine["Discrete-event engine<br/>[engine.ts]"]
  node_rng["Seeded randomness<br/>[rng.ts]"]
  node_sim_types["Simulation state<br/>[types.ts]"]
  node_explain["Recommendation explanation<br/>[explain.ts]"]
end

subgraph group_live["Live calibration"]
  node_market_endpoint["Market stream endpoint<br/>[route.ts]"]
  node_live_hub["Feed hub<br/>[hub.ts]"]
  node_live_estimate["Window estimator<br/>[estimate.ts]"]
  node_live_ewma["EWMA smoothing<br/>[ewma.ts]"]
  node_live_map["Estimate mapping<br/>[map.ts]"]
end

subgraph group_presentation["Episode views"]
  node_book_view["Queue and inventory<br/>[book-panel.tsx]"]
  node_directive_view["Directive and equations"]
  node_event_view["Event tape<br/>[event-tape.tsx]"]
  node_metrics_view["Episode metrics<br/>[metrics-bar.tsx]"]
  node_status_view["Status and controls<br/>[status-strip.tsx]"]
  node_model_card["Model card<br/>[model-card.tsx]"]
end

node_operator(("Operator"))
node_coinbase["Coinbase Exchange"]

node_operator -->|"sets parameters"| node_controls
node_page -->|"renders"| node_console_shell
node_console_shell -->|"renders"| node_controls
node_console_shell -->|"uses state"| node_controller
node_controls -->|"updates parameters"| node_controller
node_controller -->|"runs episodes"| node_engine
node_controller -->|"requests recommendation"| node_policy
node_policy -->|"checks legal actions"| node_engine
node_policy -->|"scores actions"| node_formulas
node_engine -->|"samples clocks"| node_rng
node_engine -->|"reads and updates state"| node_sim_types
node_policy -->|"scores typed state"| node_sim_types
node_explain -->|"uses policy terms"| node_policy
node_controller -->|"builds explanation"| node_explain
node_console_shell -->|"renders"| node_book_view
node_console_shell -->|"renders"| node_directive_view
node_console_shell -->|"renders"| node_event_view
node_console_shell -->|"renders"| node_metrics_view
node_console_shell -->|"renders"| node_status_view
node_book_view -->|"reads episode state"| node_controller
node_directive_view -->|"shows recommendation"| node_controller
node_directive_view -->|"renders model card"| node_model_card
node_event_view -->|"reads event tape"| node_controller
node_operator -->|"enables feed"| node_market_endpoint
node_controller -->|"opens event stream"| node_market_endpoint
node_market_endpoint -->|"requests market data"| node_live_hub
node_live_hub -->|"subscribes to L1"| node_coinbase
node_live_hub -->|"estimates window"| node_live_estimate
node_live_hub -->|"smooths estimates"| node_live_ewma
node_controller -->|"maps live estimates"| node_live_map
node_live_map -->|"creates parameter patch"| node_sim_types
node_controller -.->|"freezes estimates at start"| node_engine

click node_page "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/app/page.tsx"
click node_console_shell "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/console.tsx"
click node_controls "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/controls-panel.tsx"
click node_controller "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/hooks/use-simulation.ts"
click node_policy "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/policy.ts"
click node_formulas "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/formulas.ts"
click node_engine "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/engine.ts"
click node_rng "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/rng.ts"
click node_sim_types "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/types.ts"
click node_explain "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/explain.ts"
click node_market_endpoint "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/app/api/market/route.ts"
click node_live_hub "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/hub.ts"
click node_live_estimate "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/estimate.ts"
click node_live_ewma "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/ewma.ts"
click node_live_map "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/map.ts"
click node_book_view "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/book-panel.tsx"
click node_directive_view "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/directive-panel.tsx"
click node_event_view "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/event-tape.tsx"
click node_metrics_view "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/metrics-bar.tsx"
click node_status_view "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/status-strip.tsx"
click node_model_card "https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/model-card.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_page,node_console_shell,node_controls,node_controller toneBlue
class node_policy,node_formulas,node_engine,node_rng,node_sim_types,node_explain toneAmber
class node_market_endpoint,node_live_hub,node_live_estimate,node_live_ewma,node_live_map toneMint
class node_book_view,node_directive_view,node_event_view,node_metrics_view,node_status_view,node_model_card toneRose
class node_operator,node_coinbase toneIndigo
```

## Components

### Operations console

- [App entry](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/app/page.tsx): `app/page.tsx`
- [Console shell](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/console.tsx): `components/console.tsx`
- [Parameter controls](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/controls-panel.tsx): `components/controls-panel.tsx`
- [Simulation controller](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/hooks/use-simulation.ts): `hooks/use-simulation.ts`

### Execution model

- [Action policy](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/policy.ts): `lib/sim/policy.ts`
- [Closed-form model](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/formulas.ts): `lib/sim/formulas.ts`
- [Discrete-event engine](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/engine.ts): `lib/sim/engine.ts`
- [Seeded randomness](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/rng.ts): `lib/sim/rng.ts`
- [Simulation state](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/types.ts): `lib/sim/types.ts`
- [Recommendation explanation](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/sim/explain.ts): `lib/sim/explain.ts`

### Live calibration

- [Market stream endpoint](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/app/api/market/route.ts): `app/api/market/route.ts`
- [Feed hub](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/hub.ts): `lib/live/hub.ts`
- [Window estimator](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/estimate.ts): `lib/live/estimate.ts`
- [EWMA smoothing](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/ewma.ts): `lib/live/ewma.ts`
- [Estimate mapping](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/lib/live/map.ts): `lib/live/map.ts`

### Episode views

- [Queue and inventory](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/book-panel.tsx): `components/book-panel.tsx`
- [Directive and equations](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/directive-panel.tsx): `components/directive-panel.tsx`
- [Event tape](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/event-tape.tsx): `components/event-tape.tsx`
- [Episode metrics](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/metrics-bar.tsx): `components/metrics-bar.tsx`
- [Status and controls](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/status-strip.tsx): `components/status-strip.tsx`
- [Model card](https://github.com/vishaalchandrasekar0203/theory-trade/blob/main/components/model-card.tsx): `components/model-card.tsx`

### Other components

- **Operator**
- **Coinbase Exchange**

## Connections

- Operator → Parameter controls: sets parameters (evidence: `components/controls-panel.tsx`)
- App entry → Console shell: renders (evidence: `app/page.tsx`)
- Console shell → Parameter controls: renders (evidence: `components/console.tsx`)
- Console shell → Simulation controller: uses state (evidence: `components/console.tsx`)
- Parameter controls → Simulation controller: updates parameters (evidence: `components/controls-panel.tsx`)
- Simulation controller → Discrete-event engine: runs episodes (evidence: `hooks/use-simulation.ts`)
- Simulation controller → Action policy: requests recommendation (evidence: `hooks/use-simulation.ts`)
- Action policy → Discrete-event engine: checks legal actions (evidence: `lib/sim/policy.ts`)
- Action policy → Closed-form model: scores actions (evidence: `lib/sim/policy.ts`)
- Discrete-event engine → Seeded randomness: samples clocks (evidence: `lib/sim/engine.ts`)
- Discrete-event engine → Simulation state: reads and updates state (evidence: `lib/sim/engine.ts`)
- Action policy → Simulation state: scores typed state (evidence: `lib/sim/policy.ts`)
- Recommendation explanation → Action policy: uses policy terms (evidence: `lib/sim/explain.ts`)
- Simulation controller → Recommendation explanation: builds explanation
- Console shell → Queue and inventory: renders (evidence: `components/console.tsx`)
- Console shell → Directive and equations: renders (evidence: `components/console.tsx`)
- Console shell → Event tape: renders (evidence: `components/console.tsx`)
- Console shell → Episode metrics: renders (evidence: `components/console.tsx`)
- Console shell → Status and controls: renders (evidence: `components/console.tsx`)
- Queue and inventory → Simulation controller: reads episode state (evidence: `components/book-panel.tsx`)
- Directive and equations → Simulation controller: shows recommendation (evidence: `components/directive-panel.tsx`)
- Directive and equations → Model card: renders model card (evidence: `components/directive-panel.tsx`)
- Event tape → Simulation controller: reads event tape (evidence: `components/event-tape.tsx`)
- Operator → Market stream endpoint: enables feed (evidence: `README.md`)
- Simulation controller → Market stream endpoint: opens event stream (evidence: `hooks/use-simulation.ts`)
- Market stream endpoint → Feed hub: requests market data (evidence: `app/api/market/route.ts`)
- Feed hub → Coinbase Exchange: subscribes to L1 (evidence: `README.md`)
- Feed hub → Window estimator: estimates window (evidence: `lib/live/hub.ts`)
- Feed hub → EWMA smoothing: smooths estimates (evidence: `lib/live/hub.ts`)
- Simulation controller → Estimate mapping: maps live estimates
- Estimate mapping → Simulation state: creates parameter patch (evidence: `lib/live/map.ts`)
- Simulation controller → Discrete-event engine: freezes estimates at start (evidence: `README.md`)
