# floor-licker/polyfill-rs architecture

> Architecture diagram of the GitHub repository floor-licker/polyfill-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floor-licker/polyfill-rs
- Repository: https://github.com/floor-licker/polyfill-rs

## Overview

1. **What this repo is**
   - `polyfill-rs` is a Rust client library for Polymarket’s CLOB API, not an application server.
   - The main architectural goal is low-latency market data and trading access, with “zero-allocation hot paths” after warm-up.

2. **Top-level library boundary**
   - `src/lib.rs` is the public entrypoint and re-exports the main client-facing types.
   - Consumers interact primarily through `ClobClient`, order enums/types, market/book types, and streaming primitives rather than internal modules directly.

3. **Request/response client subsystem**
   - `src/client.rs` is the core API surface for REST-style operations such as fetching markets, posting orders, and other CLOB calls.
   - `src/http_config.rs`, `src/connection_manager.rs`, `src/dns_cache.rs`, `src/buffer_pool.rs`, and `src/config.rs` form the transport/performance layer around the client, optimizing request setup, reuse, resolution, and memory reuse.

4. **Authentication and trading boundary**
   - `src/auth.rs` encapsulates authenticated trading concerns, likely including signing and request credential handling.
   - `src/orders.rs` models order construction and posting, while `src/errors.rs` defines the failure boundary shared across network, auth, decode, and domain logic.
   - README notes the `0.4.x` line is V2-native and intentionally breaking for authenticated trading flows, so auth/order handling is a key compatibility boundary.

5. **Market data and order book domain model**
   - `src/book.rs` is the central order book subsystem, holding market depth and applying updates.
   - `src/types.rs`, `src/stream.rs`, and `src/fill.rs` provide the domain types and live-update representations used by the book and stream pipeline.
   - The README’s performance notes indicate book creation and new price levels are intentional allocation points, while steady-state updates avoid heap activity.

6. **WebSocket / real-time ingestion path**
   - `src/ws_hot_path.rs` is a dedicated low-overhead path for decoding and applying websocket book updates.
   - `src/decode.rs` appears to be the shared parsing layer feeding both REST and websocket flows, with an emphasis on fast JSON handling and minimal allocations.
   - The data flow here is: websocket message in → decode → domain update → apply to book/fill state.

7. **Derived calculations and read-side queries**
   - `src/book.rs` likely also owns fast read operations such as mid-price, spread, and depth queries.
   - `src/utils.rs` and `src/fill.rs` support these computations and transformations, keeping hot read paths simple and branch-efficient.
   - The architecture separates ingestion/update cost from frequent query cost so read-side metrics stay fast.

8. **Precision and numerical handling**
   - The README emphasizes fixed-point conversion at ingress and IEEE 754 conversion at egress.
   - That means the repo likely treats price/tick math as a domain boundary: internal integer/fixed-point arithmetic for determinism, with float-compatible outputs only when needed for API compatibility.

9. **Performance-oriented infrastructure**
   - `src/buffer_pool.rs`, `src/dns_cache.rs`, and `src/connection_manager.rs` are infrastructure modules aimed at reducing allocation and network setup overhead.
   - These pieces support keep-alive behavior, pre-warming, and request reuse so latency-sensitive operations stay predictable.

10. **Public examples as usage archetypes**
   - `examples/` contains focused executables for demos, benchmarking, HTTP/2 tuning, keep-alive behavior, and trading/order scenarios.
   - These examples act as reference entrypoints for different integration patterns: market reads, websocket handling, and performance evaluation.

11. **Benchmarks as a first-class subsystem**
   - `benches/` includes separate benchmarks for book updates, network performance, fill processing, websocket hot paths, and comparison runs.
   - This signals that the repo’s architecture is explicitly validated around throughput, allocation behavior, and end-to-end latency rather than only correctness.

12. **Testing and validation boundaries**
   - `tests/` includes integration tests for websocket, auth, order posting, price history, and no-alloc hot paths.
   - `tests/common` provides shared test harness support, indicating the repo validates both protocol correctness and performance-sensitive invariants.

13. **Tooling and delivery**
   - CI is defined in `.github/workflows/ci.yml`, and the repo includes scripts for benchmark runs and integration tests.
   - `Cargo.toml`/`Cargo.lock` define a standard Rust crate layout; there is no separate runtime service, queue, or database layer in this repository.

Main entry points: [`src/client.rs`](https://github.com/floor-licker/polyfill-rs/blob/main/src/client.rs) (client), [`src/lib.rs`](https://github.com/floor-licker/polyfill-rs/blob/main/src/lib.rs) (lib), [`src/book.rs`](https://github.com/floor-licker/polyfill-rs/blob/main/src/book.rs) (book), [`src/ws_hot_path.rs`](https://github.com/floor-licker/polyfill-rs/blob/main/src/ws_hot_path.rs) (ws hot path)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["Library"]
  node_src_lib["lib<br/>crate root<br/>[lib.rs]"]
  node_src_client["client<br/>[client.rs]"]
  node_src_auth["auth<br/>[auth.rs]"]
  node_src_orders["orders<br/>order model<br/>[orders.rs]"]
  node_src_errors["errors<br/>error boundary<br/>[errors.rs]"]
  node_src_types["types<br/>[types.rs]"]
  node_src_book[("book<br/>[book.rs]")]
  node_src_fill["fill<br/>[fill.rs]"]
  node_src_stream["stream<br/>[stream.rs]"]
  node_src_utils["utils<br/>math/helpers<br/>[utils.rs]"]
end

subgraph group_group_perf["Performance layer"]
  node_src_config["config<br/>[config.rs]"]
  node_src_http_config["http config<br/>transport config<br/>[http_config.rs]"]
  node_src_connection_manager["conn manager<br/>connection reuse"]
  node_src_dns_cache["dns cache<br/>name cache<br/>[dns_cache.rs]"]
  node_src_buffer_pool["buffer pool<br/>memory reuse<br/>[buffer_pool.rs]"]
end

subgraph group_group_realtime["Realtime flow"]
  node_src_decode["decode<br/>parser<br/>[decode.rs]"]
  node_src_ws_hot_path["ws hot path<br/>realtime ingest<br/>[ws_hot_path.rs]"]
end

subgraph group_group_validation["Validation"]
  node_src_lib_examples_tests["examples/tests<br/>validation surface"]
end

node_src_lib -->|"re-exports"| node_src_client
node_src_lib -->|"re-exports"| node_src_auth
node_src_lib -->|"re-exports"| node_src_orders
node_src_lib -->|"re-exports"| node_src_book
node_src_lib -->|"re-exports"| node_src_stream
node_src_lib -->|"re-exports"| node_src_types
node_src_client -->|"uses"| node_src_config
node_src_client -->|"uses"| node_src_http_config
node_src_client -->|"uses"| node_src_connection_manager
node_src_client -->|"uses"| node_src_dns_cache
node_src_client -->|"uses"| node_src_buffer_pool
node_src_client -->|"authenticates"| node_src_auth
node_src_client -->|"places"| node_src_orders
node_src_client -->|"parses"| node_src_decode
node_src_decode -->|"fails via"| node_src_errors
node_src_auth -->|"fails via"| node_src_errors
node_src_orders -->|"builds on"| node_src_types
node_src_book -->|"stores"| node_src_types
node_src_book -->|"tracks"| node_src_fill
node_src_book -->|"computes"| node_src_utils
node_src_ws_hot_path -->|"decodes"| node_src_decode
node_src_ws_hot_path -->|"applies"| node_src_book
node_src_ws_hot_path -->|"updates"| node_src_fill
node_src_ws_hot_path -->|"emits"| node_src_stream
node_src_stream -->|"carries"| node_src_types
node_src_lib_examples_tests -.->|"exercises"| node_src_client
node_src_lib_examples_tests -.->|"exercises"| node_src_book
node_src_lib_examples_tests -.->|"exercises"| node_src_ws_hot_path
node_src_lib_examples_tests -.->|"exercises"| node_src_auth

click node_src_lib "https://github.com/floor-licker/polyfill-rs/blob/main/src/lib.rs"
click node_src_client "https://github.com/floor-licker/polyfill-rs/blob/main/src/client.rs"
click node_src_auth "https://github.com/floor-licker/polyfill-rs/blob/main/src/auth.rs"
click node_src_orders "https://github.com/floor-licker/polyfill-rs/blob/main/src/orders.rs"
click node_src_errors "https://github.com/floor-licker/polyfill-rs/blob/main/src/errors.rs"
click node_src_types "https://github.com/floor-licker/polyfill-rs/blob/main/src/types.rs"
click node_src_book "https://github.com/floor-licker/polyfill-rs/blob/main/src/book.rs"
click node_src_fill "https://github.com/floor-licker/polyfill-rs/blob/main/src/fill.rs"
click node_src_stream "https://github.com/floor-licker/polyfill-rs/blob/main/src/stream.rs"
click node_src_utils "https://github.com/floor-licker/polyfill-rs/blob/main/src/utils.rs"
click node_src_config "https://github.com/floor-licker/polyfill-rs/blob/main/src/config.rs"
click node_src_http_config "https://github.com/floor-licker/polyfill-rs/blob/main/src/http_config.rs"
click node_src_connection_manager "https://github.com/floor-licker/polyfill-rs/blob/main/src/connection_manager.rs"
click node_src_dns_cache "https://github.com/floor-licker/polyfill-rs/blob/main/src/dns_cache.rs"
click node_src_buffer_pool "https://github.com/floor-licker/polyfill-rs/blob/main/src/buffer_pool.rs"
click node_src_decode "https://github.com/floor-licker/polyfill-rs/blob/main/src/decode.rs"
click node_src_ws_hot_path "https://github.com/floor-licker/polyfill-rs/blob/main/src/ws_hot_path.rs"

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_src_lib,node_src_client,node_src_auth,node_src_orders,node_src_errors,node_src_types,node_src_book,node_src_fill,node_src_stream,node_src_utils toneBlue
class node_src_config,node_src_http_config,node_src_connection_manager,node_src_dns_cache,node_src_buffer_pool toneAmber
class node_src_decode,node_src_ws_hot_path toneMint
class node_src_lib_examples_tests toneRose
```

## Components

### Library

Public crate entrypoint and core runtime modules

- [lib](https://github.com/floor-licker/polyfill-rs/blob/main/src/lib.rs): crate root · Public entrypoint that re-exports client-facing types and modules · `src/lib.rs`
- [client](https://github.com/floor-licker/polyfill-rs/blob/main/src/client.rs): REST client · Core CLOB API surface for markets, orders, and other request/response calls · `src/client.rs`
- [auth](https://github.com/floor-licker/polyfill-rs/blob/main/src/auth.rs): trading auth · Authenticated trading and request-signing boundary · `src/auth.rs`
- [orders](https://github.com/floor-licker/polyfill-rs/blob/main/src/orders.rs): order model · Order construction and posting types · `src/orders.rs`
- [errors](https://github.com/floor-licker/polyfill-rs/blob/main/src/errors.rs): error boundary · Shared error types across network, auth, decode, and domain logic · `src/errors.rs`
- [types](https://github.com/floor-licker/polyfill-rs/blob/main/src/types.rs): domain types · Core market, price, and API domain types · `src/types.rs`
- [book](https://github.com/floor-licker/polyfill-rs/blob/main/src/book.rs): order book · Central market depth state and fast read operations · `src/book.rs`
- [fill](https://github.com/floor-licker/polyfill-rs/blob/main/src/fill.rs): fill state · Fill and execution update representations · `src/fill.rs`
- [stream](https://github.com/floor-licker/polyfill-rs/blob/main/src/stream.rs): stream types · Live-update and streaming primitives used by realtime flows · `src/stream.rs`
- [utils](https://github.com/floor-licker/polyfill-rs/blob/main/src/utils.rs): math/helpers · Support code for derived calculations and transformations · `src/utils.rs`

### Performance layer

Connection, caching, and buffer reuse infrastructure

- [config](https://github.com/floor-licker/polyfill-rs/blob/main/src/config.rs): runtime config · Client and transport configuration knobs · `src/config.rs`
- [http config](https://github.com/floor-licker/polyfill-rs/blob/main/src/http_config.rs): transport config · HTTP tuning and request setup parameters · `src/http_config.rs`
- [conn manager](https://github.com/floor-licker/polyfill-rs/blob/main/src/connection_manager.rs): connection reuse · Manages persistent connections and request reuse · `src/connection_manager.rs`
- [dns cache](https://github.com/floor-licker/polyfill-rs/blob/main/src/dns_cache.rs): name cache · Caches DNS resolution to reduce network setup overhead · `src/dns_cache.rs`
- [buffer pool](https://github.com/floor-licker/polyfill-rs/blob/main/src/buffer_pool.rs): memory reuse · Reusable buffers for low-allocation hot paths · `src/buffer_pool.rs`

### Realtime flow

WebSocket ingestion and order book updates

- [decode](https://github.com/floor-licker/polyfill-rs/blob/main/src/decode.rs): parser · Shared fast parsing layer for REST and WebSocket payloads · `src/decode.rs`
- [ws hot path](https://github.com/floor-licker/polyfill-rs/blob/main/src/ws_hot_path.rs): realtime ingest · Low-overhead WebSocket decode and book-apply path · `src/ws_hot_path.rs`

### Validation

Examples, benchmarks, and tests used to exercise the crate

- **examples/tests**: validation surface · Representative demos, benchmarks, integration tests, and CI coverage

## Connections

- lib → client: re-exports · Public API exposes the main client surface
- lib → auth: re-exports · Public API exposes auth-related types
- lib → orders: re-exports · Public API exposes order types
- lib → book: re-exports · Public API exposes order book types
- lib → stream: re-exports · Public API exposes streaming primitives
- lib → types: re-exports · Public API exposes core domain types
- client → config: uses · Client behavior is driven by runtime config
- client → http config: uses · HTTP tuning is part of request execution
- client → conn manager: uses · Client relies on persistent connection management
- client → dns cache: uses · Network setup benefits from cached DNS resolution
- client → buffer pool: uses · Client reuses buffers on hot paths
- client → auth: authenticates · REST trading flows require authenticated requests
- client → orders: places · Client posts constructed orders
- client → decode: parses · REST responses are decoded through shared parsing code
- decode → errors: fails via · Parsing issues surface through shared errors
- auth → errors: fails via · Authentication and signing errors use shared errors
- orders → types: builds on · Orders are assembled from shared domain types
- book → types: stores · Book state is organized around market domain types
- book → fill: tracks · Book maintains fill and execution state
- book → utils: computes · Derived metrics and queries use helper math
- ws hot path → decode: decodes · WebSocket messages are parsed through the shared decoder
- ws hot path → book: applies · Decoded updates are applied into the order book
- ws hot path → fill: updates · Realtime events update fill state
- ws hot path → stream: emits · Realtime flow produces stream primitives
- stream → types: carries · Streaming payloads use core domain types
- examples/tests → client: exercises · Examples and tests cover client workflows
- examples/tests → book: exercises · Examples and tests validate book behavior
- examples/tests → ws hot path: exercises · Benchmarks and tests validate the WebSocket hot path
- examples/tests → auth: exercises · Integration coverage includes authenticated trading flows
