# synpath-ai/synpath architecture

> Architecture diagram of the GitHub repository synpath-ai/synpath, 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/synpath-ai/synpath
- Repository: https://github.com/synpath-ai/synpath

## Overview

Synpath normalizes prediction-market access across Kalshi, Polymarket, and Polymarket US. A user can read markets through the unified client, submit orders through venue adapters, and consume typed live events; the optional-in-process execution engine adds risk checks, managed order types, routing, and durable order state. The server exposes read and authenticated trading APIs, while hosted history and market matching are additional capabilities. The map follows the README and sampled excerpts; unsampled subsystems are shown only where documented, with uncertain wiring omitted.

Main entry points: [`synpath/engine/engine.py`](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/engine.py) (Engine), [`synpath/client.py`](https://github.com/synpath-ai/synpath/blob/main/synpath/client.py) (Unified Client), [`synpath/ws`](https://github.com/synpath-ai/synpath/tree/main/synpath/ws) (Stream Adapters), [`synpath/server/trading.py`](https://github.com/synpath-ai/synpath/blob/main/synpath/server/trading.py) (Trading API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Unified API"]
  node_client["Unified Client<br/>[client.py]"]
  node_types["Shared Types<br/>[types.py]"]
  node_remote["Remote Client<br/>[remote.py]"]
  node_history["Hosted History<br/>[history.py]"]
  node_hosted_auth["Hosted Auth<br/>[hosted_auth.py]"]
end

subgraph group_venues["Venue Adapters"]
  node_market_adapters["Market Data<br/>[kalshi.py]"]
  node_polymarket_data["Polymarket Data<br/>[polymarket.py]"]
  node_us_data["US Market Data<br/>[polymarket_us.py]"]
  node_trading["Trading Adapters"]
end

subgraph group_streams["Live Streams"]
  node_stream_api["Stream Adapters"]
  node_grpc["gRPC Transport<br/>[grpc.py]"]
  node_stream_queue["Typed Event Stream<br/>[base.py]"]
end

subgraph group_engine["Execution Engine"]
  node_engine["Engine<br/>[engine.py]"]
  node_risk["Risk Rules<br/>[risk.py]"]
  node_managed["Managed Orders<br/>[manager.py]"]
  node_order_types["Advanced Orders"]
  node_router["Bucket Router<br/>[router.py]"]
  node_journal[("Order Journal<br/>[journal.py]")]
  node_ledger["Account Ledger<br/>[ledger.py]"]
end

subgraph group_server["Server APIs"]
  node_server_api["Read API<br/>[api.py]"]
  node_trading_api["Trading API<br/>[trading.py]"]
  node_server_store[("Server Store<br/>[store.py]")]
end

node_user(("Application"))
node_venue_apis(("Exchange APIs"))
node_hosted_service(("Hosted API"))

node_user -->|"calls"| node_client
node_client -->|"routes reads"| node_market_adapters
node_client -->|"routes reads"| node_polymarket_data
node_client -->|"routes reads"| node_us_data
node_market_adapters -->|"reads markets"| node_venue_apis
node_polymarket_data -->|"reads markets"| node_venue_apis
node_us_data -->|"reads markets"| node_venue_apis
node_client -->|"routes orders"| node_trading
node_trading -->|"places orders"| node_venue_apis
node_user -->|"subscribes"| node_stream_api
node_stream_api -->|"opens streams"| node_venue_apis
node_stream_api -.->|"uses transport"| node_grpc
node_stream_api -->|"publishes events"| node_stream_queue
node_user -->|"submits orders"| node_engine
node_engine -->|"checks risk"| node_risk
node_engine -->|"supervises"| node_managed
node_managed -->|"runs order hooks"| node_order_types
node_engine -->|"sends orders"| node_trading
node_engine -->|"persists orders"| node_journal
node_engine -->|"tracks account state"| node_ledger
node_engine -->|"plans bucket legs"| node_router
node_user -->|"requests data"| node_server_api
node_server_api -->|"fetches venue data"| node_market_adapters
node_user -->|"submits requests"| node_trading_api
node_trading_api -->|"authenticates and audits"| node_server_store
node_trading_api -->|"dispatches trading"| node_engine
node_client -->|"uses server mode"| node_remote
node_remote -->|"requests data"| node_server_api
node_remote -->|"sends trading requests"| node_trading_api
node_user -->|"manages credentials"| node_hosted_auth
node_hosted_auth -->|"authenticates"| node_hosted_service
node_history -->|"queries history"| node_hosted_service

click node_client "https://github.com/synpath-ai/synpath/blob/main/synpath/client.py"
click node_types "https://github.com/synpath-ai/synpath/blob/main/synpath/types.py"
click node_market_adapters "https://github.com/synpath-ai/synpath/blob/main/synpath/kalshi.py"
click node_polymarket_data "https://github.com/synpath-ai/synpath/blob/main/synpath/polymarket.py"
click node_us_data "https://github.com/synpath-ai/synpath/blob/main/synpath/polymarket_us.py"
click node_trading "https://github.com/synpath-ai/synpath/tree/main/synpath/trading"
click node_stream_api "https://github.com/synpath-ai/synpath/tree/main/synpath/ws"
click node_grpc "https://github.com/synpath-ai/synpath/blob/main/synpath/ws/grpc.py"
click node_stream_queue "https://github.com/synpath-ai/synpath/blob/main/synpath/ws/base.py"
click node_engine "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/engine.py"
click node_risk "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/risk.py"
click node_managed "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/orders/manager.py"
click node_order_types "https://github.com/synpath-ai/synpath/tree/main/synpath/engine/orders"
click node_router "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/router.py"
click node_journal "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/journal.py"
click node_ledger "https://github.com/synpath-ai/synpath/blob/main/synpath/engine/ledger.py"
click node_server_api "https://github.com/synpath-ai/synpath/blob/main/synpath/server/api.py"
click node_trading_api "https://github.com/synpath-ai/synpath/blob/main/synpath/server/trading.py"
click node_server_store "https://github.com/synpath-ai/synpath/blob/main/synpath/server/store.py"
click node_remote "https://github.com/synpath-ai/synpath/blob/main/synpath/remote.py"
click node_history "https://github.com/synpath-ai/synpath/blob/main/synpath/history.py"
click node_hosted_auth "https://github.com/synpath-ai/synpath/blob/main/synpath/hosted_auth.py"

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_client,node_types,node_remote,node_history,node_hosted_auth toneBlue
class node_market_adapters,node_polymarket_data,node_us_data,node_trading toneAmber
class node_stream_api,node_grpc,node_stream_queue,node_venue_apis,node_hosted_service toneMint
class node_engine,node_risk,node_managed,node_order_types,node_router,node_journal,node_ledger toneRose
class node_server_api,node_trading_api,node_server_store,node_user toneIndigo
```

## Components

### Unified API

- [Unified Client](https://github.com/synpath-ai/synpath/blob/main/synpath/client.py): `synpath/client.py`
- [Shared Types](https://github.com/synpath-ai/synpath/blob/main/synpath/types.py): `synpath/types.py`
- [Remote Client](https://github.com/synpath-ai/synpath/blob/main/synpath/remote.py): `synpath/remote.py`
- [Hosted History](https://github.com/synpath-ai/synpath/blob/main/synpath/history.py): `synpath/history.py`
- [Hosted Auth](https://github.com/synpath-ai/synpath/blob/main/synpath/hosted_auth.py): `synpath/hosted_auth.py`

### Venue Adapters

- [Market Data](https://github.com/synpath-ai/synpath/blob/main/synpath/kalshi.py): `synpath/kalshi.py`
- [Polymarket Data](https://github.com/synpath-ai/synpath/blob/main/synpath/polymarket.py): `synpath/polymarket.py`
- [US Market Data](https://github.com/synpath-ai/synpath/blob/main/synpath/polymarket_us.py): `synpath/polymarket_us.py`
- [Trading Adapters](https://github.com/synpath-ai/synpath/tree/main/synpath/trading): `synpath/trading`

### Live Streams

- [Stream Adapters](https://github.com/synpath-ai/synpath/tree/main/synpath/ws): `synpath/ws`
- [gRPC Transport](https://github.com/synpath-ai/synpath/blob/main/synpath/ws/grpc.py): `synpath/ws/grpc.py`
- [Typed Event Stream](https://github.com/synpath-ai/synpath/blob/main/synpath/ws/base.py): `synpath/ws/base.py`

### Execution Engine

- [Engine](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/engine.py): `synpath/engine/engine.py`
- [Risk Rules](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/risk.py): `synpath/engine/risk.py`
- [Managed Orders](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/orders/manager.py): `synpath/engine/orders/manager.py`
- [Advanced Orders](https://github.com/synpath-ai/synpath/tree/main/synpath/engine/orders): `synpath/engine/orders`
- [Bucket Router](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/router.py): `synpath/engine/router.py`
- [Order Journal](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/journal.py): `synpath/engine/journal.py`
- [Account Ledger](https://github.com/synpath-ai/synpath/blob/main/synpath/engine/ledger.py): `synpath/engine/ledger.py`

### Server APIs

- [Read API](https://github.com/synpath-ai/synpath/blob/main/synpath/server/api.py): `synpath/server/api.py`
- [Trading API](https://github.com/synpath-ai/synpath/blob/main/synpath/server/trading.py): `synpath/server/trading.py`
- [Server Store](https://github.com/synpath-ai/synpath/blob/main/synpath/server/store.py): `synpath/server/store.py`

### Other components

- **Application**
- **Exchange APIs**
- **Hosted API**

## Connections

- Application → Unified Client: calls
- Unified Client → Market Data: routes reads
- Unified Client → Polymarket Data: routes reads
- Unified Client → US Market Data: routes reads
- Market Data → Exchange APIs: reads markets
- Polymarket Data → Exchange APIs: reads markets
- US Market Data → Exchange APIs: reads markets
- Unified Client → Trading Adapters: routes orders
- Trading Adapters → Exchange APIs: places orders
- Application → Stream Adapters: subscribes
- Stream Adapters → Exchange APIs: opens streams
- Stream Adapters → gRPC Transport: uses transport
- Stream Adapters → Typed Event Stream: publishes events
- Application → Engine: submits orders
- Engine → Risk Rules: checks risk
- Engine → Managed Orders: supervises
- Managed Orders → Advanced Orders: runs order hooks
- Engine → Trading Adapters: sends orders
- Engine → Order Journal: persists orders
- Engine → Account Ledger: tracks account state
- Engine → Bucket Router: plans bucket legs
- Application → Read API: requests data
- Read API → Market Data: fetches venue data
- Application → Trading API: submits requests
- Trading API → Server Store: authenticates and audits
- Trading API → Engine: dispatches trading
- Unified Client → Remote Client: uses server mode
- Remote Client → Read API: requests data
- Remote Client → Trading API: sends trading requests
- Application → Hosted Auth: manages credentials
- Hosted Auth → Hosted API: authenticates
- Hosted History → Hosted API: queries history