# gigabraingg/hypaper architecture

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

- Interactive diagram: https://gitdiagram.com/gigabraingg/hypaper
- Repository: https://github.com/gigabraingg/hypaper

## Overview

HyPaper is a HyperLiquid-compatible paper-trading backend. Bots submit exchange and account requests; the API routes them through order/account logic, while a market-data worker drives matching and funding. Redis is the live state store, with PostgreSQL receiving selected durable records; API queries and WebSocket subscriptions expose state and updates. The README documents proxied live-market queries and HL-compatible WebSocket channels. Edges reflect the shown route, worker, and event-sink wiring; unsampled route and WebSocket internals are represented only where documented or indexed.

Main entry points: [`src/engine/order.ts`](https://github.com/gigabraingg/hypaper/blob/main/src/engine/order.ts) (Order Management), [`src/store/redis.ts`](https://github.com/gigabraingg/hypaper/blob/main/src/store/redis.ts) (Redis Live State), [`src/worker/index.ts`](https://github.com/gigabraingg/hypaper/blob/main/src/worker/index.ts) (Worker Coordinator), [`src/api/routes/info.ts`](https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/info.ts) (Info Queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_server["API Router<br/>[server.ts]"]
  node_exchange["Exchange Actions<br/>[exchange.ts]"]
  node_info["Info Queries<br/>[info.ts]"]
  node_account_api["Paper Account API<br/>[hypaper.ts]"]
  node_auth["Account Initialization<br/>[auth.ts]"]
end

subgraph group_trading["Trading Engine"]
  node_order_logic["Order Management<br/>[order.ts]"]
  node_position["Positions and Margin<br/>[position.ts]"]
  node_margin["Margin Checks<br/>[margin.ts]"]
  node_fill["Fill Model<br/>[fill.ts]"]
  node_math["Decimal Math<br/>[math.ts]"]
  node_slippage["Fill Pricing<br/>[slippage.ts]"]
end

subgraph group_market["Market Workers"]
  node_matcher["Order Matching<br/>[order-matcher.ts]"]
  node_funding["Funding Worker<br/>[funding-worker.ts]"]
  node_worker["Worker Coordinator<br/>[index.ts]"]
  node_price_updater["Price Updates<br/>[price-updater.ts]"]
  node_hl_client["HL WebSocket Client<br/>[ws-client.ts]"]
end

subgraph group_state["State and Persistence"]
  node_redis[("Redis Live State<br/>[redis.ts]")]
  node_pg_sink["Postgres Event Sink<br/>[pg-sink.ts]"]
  node_config["Runtime Configuration<br/>[config.ts]"]
end

subgraph group_realtime["Realtime Interface"]
  node_ws_server["WebSocket Server<br/>[server.ts]"]
  node_event_bus["Event Bus<br/>[index.ts]"]
end

node_bot(("Trading Bot"))
node_hl_feed["HyperLiquid Feed"]
node_postgres[("PostgreSQL")]
node_hl_proxy["HyperLiquid Info API"]

node_bot -->|"sends requests"| node_api_server
node_bot -->|"subscribes"| node_ws_server
node_api_server -->|"routes exchange"| node_exchange
node_api_server -->|"routes queries"| node_info
node_api_server -->|"routes account"| node_account_api
node_exchange -->|"ensures account"| node_auth
node_exchange -->|"dispatches actions"| node_order_logic
node_account_api -->|"ensures account"| node_auth
node_auth -->|"creates account"| node_redis
node_auth -->|"queues user sync"| node_pg_sink
node_order_logic -->|"reads and writes"| node_redis
node_order_logic -->|"checks margin"| node_margin
node_order_logic -->|"executes immediate fills"| node_matcher
node_order_logic -->|"computes fill price"| node_slippage
node_order_logic -->|"compares prices"| node_math
node_worker -->|"connects and subscribes"| node_hl_client
node_worker -->|"handles feed data"| node_price_updater
node_worker -->|"matches on price updates"| node_matcher
node_worker -->|"starts funding"| node_funding
node_hl_feed -->|"streams market data"| node_hl_client
node_hl_client -->|"delivers feed messages"| node_price_updater
node_price_updater -->|"updates market state"| node_redis
node_matcher -->|"reads and updates orders"| node_redis
node_matcher -.->|"updates positions"| node_position
node_matcher -.->|"emits fill events"| node_event_bus
node_order_logic -.->|"emits order updates"| node_event_bus
node_event_bus -->|"dispatches events"| node_pg_sink
node_pg_sink -->|"persists records"| node_postgres
node_info -->|"reads paper state"| node_redis
node_info -->|"builds account state"| node_position
node_info -->|"formats fill data"| node_fill
node_info -->|"proxies live queries"| node_hl_proxy
node_ws_server -->|"serves market state"| node_redis
node_event_bus -.->|"broadcasts updates"| node_ws_server
node_config -->|"configures connection"| node_redis
node_worker -->|"seeds market data"| node_hl_proxy
node_hl_proxy -->|"supplies initial data"| node_redis

click node_api_server "https://github.com/gigabraingg/hypaper/blob/main/src/api/server.ts"
click node_exchange "https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/exchange.ts"
click node_info "https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/info.ts"
click node_account_api "https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/hypaper.ts"
click node_auth "https://github.com/gigabraingg/hypaper/blob/main/src/api/middleware/auth.ts"
click node_order_logic "https://github.com/gigabraingg/hypaper/blob/main/src/engine/order.ts"
click node_matcher "https://github.com/gigabraingg/hypaper/blob/main/src/worker/order-matcher.ts"
click node_position "https://github.com/gigabraingg/hypaper/blob/main/src/engine/position.ts"
click node_margin "https://github.com/gigabraingg/hypaper/blob/main/src/engine/margin.ts"
click node_fill "https://github.com/gigabraingg/hypaper/blob/main/src/engine/fill.ts"
click node_funding "https://github.com/gigabraingg/hypaper/blob/main/src/worker/funding-worker.ts"
click node_worker "https://github.com/gigabraingg/hypaper/blob/main/src/worker/index.ts"
click node_price_updater "https://github.com/gigabraingg/hypaper/blob/main/src/worker/price-updater.ts"
click node_hl_client "https://github.com/gigabraingg/hypaper/blob/main/src/worker/ws-client.ts"
click node_redis "https://github.com/gigabraingg/hypaper/blob/main/src/store/redis.ts"
click node_pg_sink "https://github.com/gigabraingg/hypaper/blob/main/src/store/pg-sink.ts"
click node_ws_server "https://github.com/gigabraingg/hypaper/blob/main/src/ws/server.ts"
click node_event_bus "https://github.com/gigabraingg/hypaper/blob/main/src/worker/index.ts"
click node_config "https://github.com/gigabraingg/hypaper/blob/main/src/config.ts"
click node_math "https://github.com/gigabraingg/hypaper/blob/main/src/utils/math.ts"
click node_slippage "https://github.com/gigabraingg/hypaper/blob/main/src/utils/slippage.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_api_server,node_exchange,node_info,node_account_api,node_auth toneBlue
class node_order_logic,node_position,node_margin,node_fill,node_math,node_slippage,node_postgres toneAmber
class node_matcher,node_funding,node_worker,node_price_updater,node_hl_client,node_hl_proxy toneMint
class node_redis,node_pg_sink,node_config toneRose
class node_ws_server,node_event_bus,node_bot,node_hl_feed toneIndigo
```

## Components

### HTTP API

- [API Router](https://github.com/gigabraingg/hypaper/blob/main/src/api/server.ts): `src/api/server.ts`
- [Exchange Actions](https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/exchange.ts): `src/api/routes/exchange.ts`
- [Info Queries](https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/info.ts): `src/api/routes/info.ts`
- [Paper Account API](https://github.com/gigabraingg/hypaper/blob/main/src/api/routes/hypaper.ts): `src/api/routes/hypaper.ts`
- [Account Initialization](https://github.com/gigabraingg/hypaper/blob/main/src/api/middleware/auth.ts): `src/api/middleware/auth.ts`

### Trading Engine

- [Order Management](https://github.com/gigabraingg/hypaper/blob/main/src/engine/order.ts): `src/engine/order.ts`
- [Positions and Margin](https://github.com/gigabraingg/hypaper/blob/main/src/engine/position.ts): `src/engine/position.ts`
- [Margin Checks](https://github.com/gigabraingg/hypaper/blob/main/src/engine/margin.ts): `src/engine/margin.ts`
- [Fill Model](https://github.com/gigabraingg/hypaper/blob/main/src/engine/fill.ts): `src/engine/fill.ts`
- [Decimal Math](https://github.com/gigabraingg/hypaper/blob/main/src/utils/math.ts): `src/utils/math.ts`
- [Fill Pricing](https://github.com/gigabraingg/hypaper/blob/main/src/utils/slippage.ts): `src/utils/slippage.ts`

### Market Workers

- [Order Matching](https://github.com/gigabraingg/hypaper/blob/main/src/worker/order-matcher.ts): `src/worker/order-matcher.ts`
- [Funding Worker](https://github.com/gigabraingg/hypaper/blob/main/src/worker/funding-worker.ts): `src/worker/funding-worker.ts`
- [Worker Coordinator](https://github.com/gigabraingg/hypaper/blob/main/src/worker/index.ts): `src/worker/index.ts`
- [Price Updates](https://github.com/gigabraingg/hypaper/blob/main/src/worker/price-updater.ts): `src/worker/price-updater.ts`
- [HL WebSocket Client](https://github.com/gigabraingg/hypaper/blob/main/src/worker/ws-client.ts): `src/worker/ws-client.ts`

### State and Persistence

- [Redis Live State](https://github.com/gigabraingg/hypaper/blob/main/src/store/redis.ts): `src/store/redis.ts`
- [Postgres Event Sink](https://github.com/gigabraingg/hypaper/blob/main/src/store/pg-sink.ts): `src/store/pg-sink.ts`
- [Runtime Configuration](https://github.com/gigabraingg/hypaper/blob/main/src/config.ts): `src/config.ts`

### Realtime Interface

- [WebSocket Server](https://github.com/gigabraingg/hypaper/blob/main/src/ws/server.ts): `src/ws/server.ts`
- [Event Bus](https://github.com/gigabraingg/hypaper/blob/main/src/worker/index.ts): `src/worker/index.ts`

### Other components

- **Trading Bot**
- **HyperLiquid Feed**
- **PostgreSQL**
- **HyperLiquid Info API**

## Connections

- Trading Bot → API Router: sends requests (evidence: `README.md`)
- Trading Bot → WebSocket Server: subscribes (evidence: `README.md`)
- API Router → Exchange Actions: routes exchange (evidence: `src/api/server.ts`)
- API Router → Info Queries: routes queries (evidence: `src/api/server.ts`)
- API Router → Paper Account API: routes account (evidence: `src/api/server.ts`)
- Exchange Actions → Account Initialization: ensures account (evidence: `src/api/routes/exchange.ts`)
- Exchange Actions → Order Management: dispatches actions (evidence: `src/api/routes/exchange.ts`)
- Paper Account API → Account Initialization: ensures account (evidence: `src/api/routes/hypaper.ts`)
- Account Initialization → Redis Live State: creates account (evidence: `src/api/middleware/auth.ts`)
- Account Initialization → Postgres Event Sink: queues user sync (evidence: `src/api/middleware/auth.ts`)
- Order Management → Redis Live State: reads and writes (evidence: `src/engine/order.ts`)
- Order Management → Margin Checks: checks margin (evidence: `src/engine/order.ts`)
- Order Management → Order Matching: executes immediate fills (evidence: `src/engine/order.ts`)
- Order Management → Fill Pricing: computes fill price (evidence: `src/engine/order.ts`)
- Order Management → Decimal Math: compares prices (evidence: `src/engine/order.ts`)
- Worker Coordinator → HL WebSocket Client: connects and subscribes (evidence: `src/worker/index.ts`)
- Worker Coordinator → Price Updates: handles feed data (evidence: `src/worker/index.ts`)
- Worker Coordinator → Order Matching: matches on price updates (evidence: `src/worker/index.ts`)
- Worker Coordinator → Funding Worker: starts funding (evidence: `src/worker/index.ts`)
- HyperLiquid Feed → HL WebSocket Client: streams market data (evidence: `README.md`)
- HL WebSocket Client → Price Updates: delivers feed messages (evidence: `src/worker/index.ts`)
- Price Updates → Redis Live State: updates market state (evidence: `src/worker/price-updater.ts`)
- Order Matching → Redis Live State: reads and updates orders (evidence: `src/worker/order-matcher.ts`)
- Order Matching → Positions and Margin: updates positions
- Order Matching → Event Bus: emits fill events (evidence: `src/worker/index.ts`)
- Order Management → Event Bus: emits order updates (evidence: `src/engine/order.ts`)
- Event Bus → Postgres Event Sink: dispatches events (evidence: `src/index.ts`)
- Postgres Event Sink → PostgreSQL: persists records (evidence: `src/store/pg-sink.ts`)
- Info Queries → Redis Live State: reads paper state (evidence: `src/api/routes/info.ts`)
- Info Queries → Positions and Margin: builds account state (evidence: `src/api/routes/info.ts`)
- Info Queries → Fill Model: formats fill data (evidence: `src/api/routes/info.ts`)
- Info Queries → HyperLiquid Info API: proxies live queries (evidence: `README.md`)
- WebSocket Server → Redis Live State: serves market state (evidence: `src/ws/server.ts`)
- Event Bus → WebSocket Server: broadcasts updates
- Runtime Configuration → Redis Live State: configures connection (evidence: `src/store/redis.ts`)
- Worker Coordinator → HyperLiquid Info API: seeds market data (evidence: `src/worker/index.ts`)
- HyperLiquid Info API → Redis Live State: supplies initial data
