# userfrm/thetadatadx architecture

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

- Interactive diagram: https://gitdiagram.com/userfrm/thetadatadx
- Repository: https://github.com/userfrm/thetadatadx

## Overview

ThetaDataDx is a multi-language market-data SDK backed by one Rust engine, with an optional compatible REST/WebSocket server and MCP interface. The main workflow is to configure credentials, connect a client to ThetaData, request historical data, subscribe to live data, or download flat files, then consume typed or columnar results. The README establishes the product capabilities and client modes; source-index references and excerpts support the internal and binding relationships shown. Some implementation details are unsampled, so uncertain links are omitted.

Main entry points: [`thetadatadx-rs/src/client.rs`](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/client.rs) (Unified Client), [`thetadatadx-rs/src/mdds/client.rs`](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/mdds/client.rs) (History & Snapshots), [`thetadatadx-rs/src/fpss/session.rs`](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/fpss/session.rs) (Live Streaming), [`thetadatadx-rs/src/lib.rs`](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/lib.rs) (Rust SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Rust Engine"]
  node_builder["Client Builder<br/>[client_builder.rs]"]
  node_auth["Credentials &amp; Auth<br/>[nexus.rs]"]
  node_config["Connection Config<br/>[mod.rs]"]
  node_client["Unified Client<br/>[client.rs]"]
  node_errors["Typed Errors<br/>[error.rs]"]
  node_columnar["Typed &amp; Columnar Data<br/>[columns.rs]"]
end

subgraph group_feeds["Data Access"]
  node_history["History &amp; Snapshots<br/>[client.rs]"]
  node_grpc["gRPC Transport<br/>[stream.rs]"]
  node_stream["Live Streaming<br/>[session.rs]"]
  node_batch["Stream Batches<br/>[batch_reader.rs]"]
  node_flatfiles["Flat Files<br/>[decoded.rs]"]
end

subgraph group_bindings["Language SDKs"]
  node_rustsdk["Rust SDK<br/>[lib.rs]"]
  node_pysdk["Python SDK<br/>[lib.rs]"]
  node_pystream["Python Streaming<br/>[fpss_client.rs]"]
  node_pyflat["Python Flat Files"]
  node_ts["TypeScript SDK<br/>[lib.rs]"]
  node_ffi["C FFI<br/>[lib.rs]"]
  node_cpp["C++ SDK<br/>[thetadatadx.cpp]"]
end

subgraph group_services["Optional Services"]
  node_server["Compat Server<br/>[main.rs]"]
  node_routes["REST Routes<br/>[handler.rs]"]
  node_flatroute["Flat-file Routes<br/>[flatfile_routes.rs]"]
  node_ws["WebSocket Service<br/>[session.rs]"]
  node_mcp["MCP Tools<br/>[main.rs]"]
end

node_developer(("SDK User"))
node_theta(("ThetaData"))
node_result(("Application"))

node_developer -->|"configures"| node_builder
node_builder -->|"resolves credentials"| node_auth
node_builder -->|"connects"| node_client
node_client -->|"uses settings"| node_config
node_client -->|"requests history"| node_history
node_client -->|"starts lazily"| node_stream
node_client -->|"downloads"| node_flatfiles
node_auth -->|"authenticates"| node_theta
node_history -->|"uses transport"| node_grpc
node_stream -->|"dispatches batches"| node_batch
node_history -->|"fetches market data"| node_theta
node_stream -->|"connects live feed"| node_theta
node_flatfiles -->|"downloads datasets"| node_theta
node_history -->|"returns typed data"| node_columnar
node_stream -->|"emits events"| node_developer
node_flatfiles -->|"returns rows"| node_developer
node_rustsdk -->|"exposes"| node_client
node_pysdk -->|"wraps engine"| node_rustsdk
node_pysdk -->|"exposes"| node_pystream
node_pysdk -->|"exposes"| node_pyflat
node_ts -.->|"wraps engine"| node_rustsdk
node_ffi -->|"exposes engine"| node_rustsdk
node_cpp -.->|"uses bindings"| node_ffi
node_server -->|"routes requests"| node_routes
node_server -->|"registers routes"| node_flatroute
node_server -.->|"starts service"| node_ws
node_routes -->|"invokes SDK"| node_theta
node_flatroute -.->|"serves downloads"| node_theta
node_developer -->|"invokes tools"| node_mcp
node_client -->|"delivers data"| node_result

click node_builder "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/client_builder.rs"
click node_auth "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/auth/nexus.rs"
click node_config "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/config/mod.rs"
click node_client "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/client.rs"
click node_errors "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/error.rs"
click node_history "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/mdds/client.rs"
click node_grpc "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/grpc/stream.rs"
click node_stream "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/fpss/session.rs"
click node_batch "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/fpss/batch_reader.rs"
click node_flatfiles "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/flatfiles/decoded.rs"
click node_columnar "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/columns.rs"
click node_rustsdk "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/lib.rs"
click node_pysdk "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/lib.rs"
click node_pystream "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/fpss_client.rs"
click node_pyflat "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/flatfile_methods.rs"
click node_ts "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-ts/src/lib.rs"
click node_ffi "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-ffi/src/lib.rs"
click node_cpp "https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-cpp/src/thetadatadx.cpp"
click node_server "https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/main.rs"
click node_routes "https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/handler.rs"
click node_flatroute "https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/flatfile_routes.rs"
click node_ws "https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/ws/session.rs"
click node_mcp "https://github.com/userfrm/thetadatadx/blob/main/tools/mcp/src/main.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_builder,node_auth,node_config,node_client,node_errors,node_columnar,node_developer toneBlue
class node_history,node_grpc,node_stream,node_batch,node_flatfiles toneAmber
class node_rustsdk,node_pysdk,node_pystream,node_pyflat,node_ts,node_ffi,node_cpp toneMint
class node_server,node_routes,node_flatroute,node_ws,node_mcp toneRose
class node_theta,node_result toneIndigo
```

## Components

### Rust Engine

- [Client Builder](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/client_builder.rs): `thetadatadx-rs/src/client_builder.rs`
- [Credentials & Auth](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/auth/nexus.rs): `thetadatadx-rs/src/auth/nexus.rs`
- [Connection Config](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/config/mod.rs): `thetadatadx-rs/src/config/mod.rs`
- [Unified Client](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/client.rs): `thetadatadx-rs/src/client.rs`
- [Typed Errors](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/error.rs): `thetadatadx-rs/src/error.rs`
- [Typed & Columnar Data](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/columns.rs): `thetadatadx-rs/src/columns.rs`

### Data Access

- [History & Snapshots](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/mdds/client.rs): `thetadatadx-rs/src/mdds/client.rs`
- [gRPC Transport](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/grpc/stream.rs): `thetadatadx-rs/src/grpc/stream.rs`
- [Live Streaming](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/fpss/session.rs): `thetadatadx-rs/src/fpss/session.rs`
- [Stream Batches](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/fpss/batch_reader.rs): `thetadatadx-rs/src/fpss/batch_reader.rs`
- [Flat Files](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/flatfiles/decoded.rs): `thetadatadx-rs/src/flatfiles/decoded.rs`

### Language SDKs

- [Rust SDK](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-rs/src/lib.rs): `thetadatadx-rs/src/lib.rs`
- [Python SDK](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/lib.rs): `thetadatadx-py/src/lib.rs`
- [Python Streaming](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/fpss_client.rs): `thetadatadx-py/src/fpss_client.rs`
- [Python Flat Files](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-py/src/flatfile_methods.rs): `thetadatadx-py/src/flatfile_methods.rs`
- [TypeScript SDK](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-ts/src/lib.rs): `thetadatadx-ts/src/lib.rs`
- [C FFI](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-ffi/src/lib.rs): `thetadatadx-ffi/src/lib.rs`
- [C++ SDK](https://github.com/userfrm/thetadatadx/blob/main/thetadatadx-cpp/src/thetadatadx.cpp): `thetadatadx-cpp/src/thetadatadx.cpp`

### Optional Services

- [Compat Server](https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/main.rs): `tools/server/src/main.rs`
- [REST Routes](https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/handler.rs): `tools/server/src/handler.rs`
- [Flat-file Routes](https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/flatfile_routes.rs): `tools/server/src/flatfile_routes.rs`
- [WebSocket Service](https://github.com/userfrm/thetadatadx/blob/main/tools/server/src/ws/session.rs): `tools/server/src/ws/session.rs`
- [MCP Tools](https://github.com/userfrm/thetadatadx/blob/main/tools/mcp/src/main.rs): `tools/mcp/src/main.rs`

### Other components

- **SDK User**
- **ThetaData**
- **Application**

## Connections

- SDK User → Client Builder: configures (evidence: `README.md`)
- Client Builder → Credentials & Auth: resolves credentials (evidence: `thetadatadx-rs/src/client_builder.rs`)
- Client Builder → Unified Client: connects (evidence: `thetadatadx-rs/src/client_builder.rs`)
- Unified Client → Connection Config: uses settings (evidence: `thetadatadx-rs/src/client.rs`)
- Unified Client → History & Snapshots: requests history (evidence: `thetadatadx-rs/src/client.rs`)
- Unified Client → Live Streaming: starts lazily (evidence: `thetadatadx-rs/src/client.rs`)
- Unified Client → Flat Files: downloads (evidence: `thetadatadx-rs/src/client.rs`)
- Credentials & Auth → ThetaData: authenticates
- History & Snapshots → gRPC Transport: uses transport (evidence: `thetadatadx-rs/src/mdds/client.rs`)
- Live Streaming → Stream Batches: dispatches batches
- History & Snapshots → ThetaData: fetches market data (evidence: `README.md`)
- Live Streaming → ThetaData: connects live feed (evidence: `README.md`)
- Flat Files → ThetaData: downloads datasets (evidence: `README.md`)
- History & Snapshots → Typed & Columnar Data: returns typed data (evidence: `README.md`)
- Live Streaming → SDK User: emits events (evidence: `README.md`)
- Flat Files → SDK User: returns rows
- Rust SDK → Unified Client: exposes (evidence: `thetadatadx-rs/src/lib.rs`)
- Python SDK → Rust SDK: wraps engine (evidence: `thetadatadx-py/src/lib.rs`)
- Python SDK → Python Streaming: exposes (evidence: `thetadatadx-py/src/lib.rs`)
- Python SDK → Python Flat Files: exposes (evidence: `thetadatadx-py/src/lib.rs`)
- TypeScript SDK → Rust SDK: wraps engine
- C FFI → Rust SDK: exposes engine (evidence: `thetadatadx-ffi/src/lib.rs`)
- C++ SDK → C FFI: uses bindings
- Compat Server → REST Routes: routes requests (evidence: `tools/server/src/main.rs`)
- Compat Server → Flat-file Routes: registers routes (evidence: `tools/server/src/main.rs`)
- Compat Server → WebSocket Service: starts service
- REST Routes → ThetaData: invokes SDK (evidence: `tools/server/src/handler.rs`)
- Flat-file Routes → ThetaData: serves downloads
- SDK User → MCP Tools: invokes tools (evidence: `README.md`)
- Unified Client → Application: delivers data (evidence: `README.md`)
