# anuranpaul/kalshi-mispricing-arbitrage-engine architecture

> Architecture diagram of the GitHub repository anuranpaul/kalshi-mispricing-arbitrage-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anuranpaul/kalshi-mispricing-arbitrage-engine
- Repository: https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine

## Overview

KalshiEngine is a paper-only Kalshi market observer: its principal workflow ingests demo WebSocket snapshots and deltas, reconstructs fresh YES/NO books, detects and deduplicates estimated complementary mispricing, then publishes observed events for persistence and live display. Separate read-only REST commands support smoke checks; the product does not execute orders. The README documents the major flow and capabilities, while sampled excerpts confirm key book, WebSocket, deduplication, storage, gateway, and UI behavior; some subsystem wiring is therefore based on that documentation.

Main entry points: [`cmd/kalshiengine/main.go`](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/cmd/kalshiengine/main.go) (CLI Orchestrator), [`internal/kalshi/ws/client.go`](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/ws/client.go) (WebSocket Client), [`internal/gateway/server.go`](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/gateway/server.go) (SSE / REST Gateway), [`internal/kalshi/rest/client.go`](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/rest/client.go) (Read-only REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Market Ingestion"]
  node_auth["RSA-PSS Signer<br/>[auth.go]"]
  node_rest["Read-only REST<br/>[client.go]"]
  node_ws["WebSocket Client<br/>[client.go]"]
  node_registry["Book Registry<br/>[registry.go]"]
  node_market["Market State<br/>[market.go]"]
  node_ladder["YES/NO Ladders<br/>[ladder.go]"]
  node_redis[("Redis Cache<br/>[redis.go]")]
end

subgraph group_detect["Detection Engine"]
  node_detector["Mispricing Detector<br/>[detect.go]"]
  node_depth["Depth Walk<br/>[depth.go]"]
  node_fees["Fee Model<br/>[fee.go]"]
  node_dedup["Opportunity Dedup<br/>[dedup.go]"]
  node_publisher["Event Publisher<br/>[publisher.go]"]
end

subgraph group_persist["Event Persistence"]
  node_nats["NATS JetStream"]
  node_consumer["Pull Consumer<br/>[consumer.go]"]
  node_store[("TimescaleDB Store<br/>[store.go]")]
end

subgraph group_observe["Monitoring UI"]
  node_gateway["SSE / REST Gateway<br/>[server.go]"]
  node_health["Health / Metrics<br/>[health.go]"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
end

subgraph group_runtime["Runtime Support"]
  node_engine["CLI Orchestrator<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_money["Exact Decimal<br/>[amount.go]"]
  node_guard["Order Safety Guard<br/>[guard.go]"]
end

node_operator(("Operator"))
node_kalshi(("Kalshi Demo"))

node_operator -->|"runs command"| node_engine
node_engine -->|"loads settings"| node_config
node_engine -->|"loads signer"| node_auth
node_engine -->|"runs smoke checks"| node_rest
node_rest -->|"signs requests"| node_auth
node_rest -->|"checks paths"| node_guard
node_rest -->|"GET requests"| node_kalshi
node_engine -->|"starts ingestion"| node_ws
node_ws -->|"signs connection"| node_auth
node_ws -->|"connects / subscribes"| node_kalshi
node_kalshi -->|"sends book frames"| node_ws
node_ws -->|"updates books"| node_registry
node_registry -->|"ensures markets"| node_market
node_market -->|"updates levels"| node_ladder
node_market -.->|"caches snapshots"| node_redis
node_engine -->|"uses exact amounts"| node_money
node_ws -->|"evaluates live books"| node_detector
node_detector -->|"walks liquidity"| node_depth
node_detector -->|"estimates fees"| node_fees
node_ws -->|"evaluates results"| node_dedup
node_ws -->|"publishes decisions"| node_publisher
node_publisher -->|"sends events"| node_nats
node_engine -->|"starts consumer"| node_consumer
node_nats -->|"delivers events"| node_consumer
node_consumer -->|"persists records"| node_store
node_ws -->|"broadcasts events"| node_gateway
node_gateway -->|"reads book views"| node_registry
node_gateway -->|"queries records"| node_store
node_engine -->|"starts server"| node_gateway
node_engine -->|"starts endpoints"| node_health
node_dashboard -->|"fetches / streams"| node_gateway

click node_engine "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/cmd/kalshiengine/main.go"
click node_config "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/config/config.go"
click node_auth "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/auth/auth.go"
click node_rest "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/rest/client.go"
click node_ws "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/ws/client.go"
click node_registry "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/registry.go"
click node_market "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/market.go"
click node_ladder "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/ladder.go"
click node_redis "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/redis.go"
click node_money "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/money/amount.go"
click node_detector "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/detect.go"
click node_depth "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/depth.go"
click node_fees "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/fee.go"
click node_dedup "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/dedup.go"
click node_publisher "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/publisher.go"
click node_consumer "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/consume/consumer.go"
click node_store "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/store/store.go"
click node_gateway "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/gateway/server.go"
click node_health "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/health/health.go"
click node_dashboard "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/web/src/App.tsx"
click node_guard "https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/guard/guard.go"

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_auth,node_rest,node_ws,node_registry,node_market,node_ladder,node_redis toneBlue
class node_detector,node_depth,node_fees,node_dedup,node_publisher toneAmber
class node_nats,node_consumer,node_store toneMint
class node_gateway,node_health,node_dashboard toneRose
class node_engine,node_config,node_money,node_guard,node_operator,node_kalshi toneIndigo
```

## Components

### Market Ingestion

- [RSA-PSS Signer](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/auth/auth.go): `internal/kalshi/auth/auth.go`
- [Read-only REST](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/rest/client.go): `internal/kalshi/rest/client.go`
- [WebSocket Client](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/kalshi/ws/client.go): `internal/kalshi/ws/client.go`
- [Book Registry](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/registry.go): `internal/book/registry.go`
- [Market State](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/market.go): `internal/book/market.go`
- [YES/NO Ladders](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/ladder.go): `internal/book/ladder.go`
- [Redis Cache](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/book/redis.go): `internal/book/redis.go`

### Detection Engine

- [Mispricing Detector](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/detect.go): `internal/detect/detect.go`
- [Depth Walk](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/depth.go): `internal/detect/depth.go`
- [Fee Model](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/fee.go): `internal/detect/fee.go`
- [Opportunity Dedup](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/dedup.go): `internal/detect/dedup.go`
- [Event Publisher](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/detect/publisher.go): `internal/detect/publisher.go`

### Event Persistence

- **NATS JetStream**
- [Pull Consumer](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/consume/consumer.go): `internal/consume/consumer.go`
- [TimescaleDB Store](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/store/store.go): `internal/store/store.go`

### Monitoring UI

- [SSE / REST Gateway](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/gateway/server.go): `internal/gateway/server.go`
- [Health / Metrics](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/health/health.go): `internal/health/health.go`
- [Dashboard](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/web/src/App.tsx): `web/src/App.tsx`

### Runtime Support

- [CLI Orchestrator](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/cmd/kalshiengine/main.go): `cmd/kalshiengine/main.go`
- [Configuration](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/config/config.go): `internal/config/config.go`
- [Exact Decimal](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/money/amount.go): `internal/money/amount.go`
- [Order Safety Guard](https://github.com/anuranpaul/kalshi-mispricing-arbitrage-engine/blob/main/internal/guard/guard.go): `internal/guard/guard.go`

### Other components

- **Operator**
- **Kalshi Demo**

## Connections

- Operator → CLI Orchestrator: runs command
- CLI Orchestrator → Configuration: loads settings
- CLI Orchestrator → RSA-PSS Signer: loads signer
- CLI Orchestrator → Read-only REST: runs smoke checks
- Read-only REST → RSA-PSS Signer: signs requests
- Read-only REST → Order Safety Guard: checks paths
- Read-only REST → Kalshi Demo: GET requests
- CLI Orchestrator → WebSocket Client: starts ingestion
- WebSocket Client → RSA-PSS Signer: signs connection
- WebSocket Client → Kalshi Demo: connects / subscribes
- Kalshi Demo → WebSocket Client: sends book frames
- WebSocket Client → Book Registry: updates books
- Book Registry → Market State: ensures markets
- Market State → YES/NO Ladders: updates levels
- Market State → Redis Cache: caches snapshots
- CLI Orchestrator → Exact Decimal: uses exact amounts
- WebSocket Client → Mispricing Detector: evaluates live books
- Mispricing Detector → Depth Walk: walks liquidity
- Mispricing Detector → Fee Model: estimates fees
- WebSocket Client → Opportunity Dedup: evaluates results
- WebSocket Client → Event Publisher: publishes decisions
- Event Publisher → NATS JetStream: sends events
- CLI Orchestrator → Pull Consumer: starts consumer
- NATS JetStream → Pull Consumer: delivers events
- Pull Consumer → TimescaleDB Store: persists records
- WebSocket Client → SSE / REST Gateway: broadcasts events
- SSE / REST Gateway → Book Registry: reads book views
- SSE / REST Gateway → TimescaleDB Store: queries records
- CLI Orchestrator → SSE / REST Gateway: starts server
- CLI Orchestrator → Health / Metrics: starts endpoints
- Dashboard → SSE / REST Gateway: fetches / streams