# ray-27/alta-bus architecture

> Architecture diagram of the GitHub repository ray-27/alta-bus, 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/ray-27/alta-bus
- Repository: https://github.com/ray-27/alta-bus

## Overview

alta_bus is a low-latency TCP market-data message bus. Publishers encode and send binary frames; the bus classifies each connection, publishes data to a shared ring, then dispatches matching frames to subscribers. Subscribers choose all channels or a channel filter and read forwarded frames for application-side decoding. The protocol defines the fixed wire header, message types, and implemented payload formats. The bus implementation excerpt is partial, so the graph omits uncertain internal wiring; documented capabilities are included where their source paths are supported.

Main entry points: [`subscriber-client/src/lib.rs`](https://github.com/ray-27/alta-bus/blob/main/subscriber-client/src/lib.rs) (Subscriber SDK), [`bus/src/main.rs`](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs) (Connection Handler), [`protocol/src/header.rs`](https://github.com/ray-27/alta-bus/blob/main/protocol/src/header.rs) (Frame Header), [`publisher-client/src/lib.rs`](https://github.com/ray-27/alta-bus/blob/main/publisher-client/src/lib.rs) (Publisher SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client SDKs"]
  node_publisher_sdk["Publisher SDK<br/>[lib.rs]"]
  node_subscriber_sdk["Subscriber SDK<br/>[lib.rs]"]
end

subgraph group_bus["Bus Runtime"]
  node_bus_listener["TCP Listener<br/>[main.rs]"]
  node_connection_handler["Connection Handler<br/>[main.rs]"]
  node_publisher_loop["Publisher Loop<br/>[main.rs]"]
  node_publish_one["Ring Publisher<br/>[main.rs]"]
  node_dispatch["Frame Dispatcher<br/>[main.rs]"]
  node_subscription_registry["Subscription Registry<br/>[main.rs]"]
  node_subscriber_io["Subscriber I/O<br/>[main.rs]"]
end

subgraph group_protocol["Wire Protocol"]
  node_frame_header["Frame Header<br/>[header.rs]"]
  node_message_types["Message Types<br/>[types.rs]"]
  node_payload_codec["Encode Decode<br/>[codec.rs]"]
  node_price_tick["Price Tick<br/>[price_tick.rs]"]
  node_heartbeat["Heartbeat<br/>[heartbeat.rs]"]
  node_other_payloads["Other Message IDs<br/>[types.rs]"]
end

subgraph group_state["Message State"]
  node_ring[("Shared Ring<br/>[ring.rs]")]
end

node_publisher_actor(("Publisher"))
node_subscriber_actor(("Subscriber"))

node_publisher_actor -->|"publishes through"| node_publisher_sdk
node_publisher_sdk -->|"encodes header"| node_frame_header
node_publisher_sdk -->|"encodes payload"| node_payload_codec
node_publisher_sdk -->|"sends TCP frames"| node_bus_listener
node_subscriber_actor -->|"subscribes through"| node_subscriber_sdk
node_subscriber_sdk -->|"encodes control"| node_frame_header
node_subscriber_sdk -->|"opens TCP"| node_bus_listener
node_bus_listener -->|"dispatches connection"| node_connection_handler
node_connection_handler -->|"parses header"| node_frame_header
node_connection_handler -->|"starts publisher"| node_publisher_loop
node_publisher_loop -->|"parses frames"| node_frame_header
node_publisher_loop -->|"publishes message"| node_publish_one
node_publish_one -->|"writes message"| node_ring
node_connection_handler -->|"registers filter"| node_subscription_registry
node_connection_handler -->|"starts subscriber I/O"| node_subscriber_io
node_dispatch -->|"consumes messages"| node_ring
node_dispatch -->|"reads filters"| node_subscription_registry
node_dispatch -->|"queues matching frames"| node_subscriber_io
node_subscriber_io -->|"writes TCP frames"| node_subscriber_actor
node_subscriber_sdk -->|"decodes header"| node_frame_header
node_subscriber_sdk -->|"enables decoding"| node_payload_codec
node_payload_codec -->|"encodes and decodes"| node_price_tick
node_payload_codec -->|"encodes and decodes"| node_heartbeat
node_subscriber_actor -->|"selects payload decoder"| node_message_types
node_message_types -->|"defines reserved IDs"| node_other_payloads

click node_publisher_sdk "https://github.com/ray-27/alta-bus/blob/main/publisher-client/src/lib.rs"
click node_subscriber_sdk "https://github.com/ray-27/alta-bus/blob/main/subscriber-client/src/lib.rs"
click node_bus_listener "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_connection_handler "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_publisher_loop "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_publish_one "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_dispatch "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_subscription_registry "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_subscriber_io "https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs"
click node_ring "https://github.com/ray-27/alta-bus/blob/main/bus/src/ring.rs"
click node_frame_header "https://github.com/ray-27/alta-bus/blob/main/protocol/src/header.rs"
click node_message_types "https://github.com/ray-27/alta-bus/blob/main/protocol/src/types.rs"
click node_payload_codec "https://github.com/ray-27/alta-bus/blob/main/protocol/src/codec.rs"
click node_price_tick "https://github.com/ray-27/alta-bus/blob/main/protocol/src/messages/price_tick.rs"
click node_heartbeat "https://github.com/ray-27/alta-bus/blob/main/protocol/src/messages/heartbeat.rs"
click node_other_payloads "https://github.com/ray-27/alta-bus/blob/main/protocol/src/types.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_publisher_sdk,node_subscriber_sdk toneBlue
class node_bus_listener,node_connection_handler,node_publisher_loop,node_publish_one,node_dispatch,node_subscription_registry,node_subscriber_io toneAmber
class node_frame_header,node_message_types,node_payload_codec,node_price_tick,node_heartbeat,node_other_payloads toneMint
class node_ring toneRose
class node_publisher_actor,node_subscriber_actor toneIndigo
```

## Components

### Client SDKs

- [Publisher SDK](https://github.com/ray-27/alta-bus/blob/main/publisher-client/src/lib.rs): `publisher-client/src/lib.rs`
- [Subscriber SDK](https://github.com/ray-27/alta-bus/blob/main/subscriber-client/src/lib.rs): `subscriber-client/src/lib.rs`

### Bus Runtime

- [TCP Listener](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Connection Handler](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Publisher Loop](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Ring Publisher](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Frame Dispatcher](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Subscription Registry](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`
- [Subscriber I/O](https://github.com/ray-27/alta-bus/blob/main/bus/src/main.rs): `bus/src/main.rs`

### Wire Protocol

- [Frame Header](https://github.com/ray-27/alta-bus/blob/main/protocol/src/header.rs): `protocol/src/header.rs`
- [Message Types](https://github.com/ray-27/alta-bus/blob/main/protocol/src/types.rs): `protocol/src/types.rs`
- [Encode Decode](https://github.com/ray-27/alta-bus/blob/main/protocol/src/codec.rs): `protocol/src/codec.rs`
- [Price Tick](https://github.com/ray-27/alta-bus/blob/main/protocol/src/messages/price_tick.rs): `protocol/src/messages/price_tick.rs`
- [Heartbeat](https://github.com/ray-27/alta-bus/blob/main/protocol/src/messages/heartbeat.rs): `protocol/src/messages/heartbeat.rs`
- [Other Message IDs](https://github.com/ray-27/alta-bus/blob/main/protocol/src/types.rs): `protocol/src/types.rs`

### Message State

- [Shared Ring](https://github.com/ray-27/alta-bus/blob/main/bus/src/ring.rs): `bus/src/ring.rs`

### Other components

- **Publisher**
- **Subscriber**

## Connections

- Publisher → Publisher SDK: publishes through
- Publisher SDK → Frame Header: encodes header
- Publisher SDK → Encode Decode: encodes payload
- Publisher SDK → TCP Listener: sends TCP frames
- Subscriber → Subscriber SDK: subscribes through
- Subscriber SDK → Frame Header: encodes control
- Subscriber SDK → TCP Listener: opens TCP
- TCP Listener → Connection Handler: dispatches connection
- Connection Handler → Frame Header: parses header
- Connection Handler → Publisher Loop: starts publisher
- Publisher Loop → Frame Header: parses frames
- Publisher Loop → Ring Publisher: publishes message
- Ring Publisher → Shared Ring: writes message
- Connection Handler → Subscription Registry: registers filter
- Connection Handler → Subscriber I/O: starts subscriber I/O
- Frame Dispatcher → Shared Ring: consumes messages
- Frame Dispatcher → Subscription Registry: reads filters
- Frame Dispatcher → Subscriber I/O: queues matching frames
- Subscriber I/O → Subscriber: writes TCP frames
- Subscriber SDK → Frame Header: decodes header
- Subscriber SDK → Encode Decode: enables decoding
- Encode Decode → Price Tick: encodes and decodes
- Encode Decode → Heartbeat: encodes and decodes
- Subscriber → Message Types: selects payload decoder
- Message Types → Other Message IDs: defines reserved IDs