# wegoingprobyn/clusterservices architecture

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

- Interactive diagram: https://gitdiagram.com/wegoingprobyn/clusterservices
- Repository: https://github.com/wegoingprobyn/clusterservices
- Video tour (about a minute): https://gitdiagram.com/wegoingprobyn/clusterservices/video

## Overview

This workspace is a Rust framework for cluster agents and services: plugins sample data and respond to commands, while the runtime engine manages service lifecycles and communicates with peers over a framed transport. The principal flow is service sampling, encoding and transport, then server-side handler processing; commands travel back through the engine to targeted services. The README is empty and source excerpts are partial, so links for unsampled capabilities are limited to relationships established by the API, protocol schema, and excerpts.

Main entry points: [`crates/runtime/engine/src/service.rs`](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/service.rs) (Service lifecycle), [`crates/runtime/engine/src/engine.rs`](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/engine.rs) (Node engine), [`crates/runtime/transport/src/traits.rs`](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/traits.rs) (Transport API), [`crates/runtime/transport/src/frame.rs`](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/frame.rs) (Protocol frames)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Plugin API"]
  node_service_contract["Service contracts<br/>[service.rs]"]
  node_sampler_api["Sampler API<br/>[sampler.rs]"]
  node_handler_api["Handler API<br/>[handler.rs]"]
  node_command_api["Command API<br/>[command.rs]"]
  node_wire_api["Wire encoding<br/>[wire.rs]"]
end

subgraph group_engine["Runtime Engine"]
  node_engine_core["Node engine<br/>[engine.rs]"]
  node_service_runtime["Service lifecycle<br/>[service.rs]"]
  node_command_queue["Command routing<br/>[queue.rs]"]
  node_peer_state["Peer sessions<br/>[peer.rs]"]
  node_chunking["Message chunks<br/>[chunk.rs]"]
  node_worker_threads["Plugin workers<br/>[worker.rs]"]
  node_stats["Runtime stats<br/>[stats.rs]"]
end

subgraph group_wire["Peer Transport"]
  node_transport_api["Transport API<br/>[traits.rs]"]
  node_endpoint["Connection endpoints<br/>[endpoint.rs]"]
  node_frames["Protocol frames<br/>[frame.rs]"]
  node_protocol_schema["Wire schema<br/>[frame.proto]"]
end

subgraph group_plugin["Built-in Plugin"]
  node_cgroup["Cgroup service<br/>[lib.rs]"]
end

node_operator(("Command issuer"))
node_remote_peer(("Remote peer"))
node_service_store[("Service-owned state")]

node_cgroup -->|"implements"| node_service_contract
node_cgroup -->|"samples via"| node_sampler_api
node_engine_core -->|"manages"| node_service_runtime
node_engine_core -->|"connects through"| node_transport_api
node_engine_core -->|"tracks peers"| node_peer_state
node_engine_core -->|"dispatches commands"| node_command_queue
node_engine_core -->|"updates counters"| node_stats
node_service_runtime -->|"runs samplers"| node_sampler_api
node_service_runtime -->|"invokes handlers"| node_handler_api
node_service_runtime -->|"runs blocking work"| node_worker_threads
node_service_runtime -->|"encodes samples"| node_wire_api
node_service_runtime -->|"handles commands"| node_command_api
node_handler_api -->|"processes data"| node_service_store
node_operator -->|"requests command"| node_engine_core
node_command_queue -->|"targets peer"| node_peer_state
node_peer_state -->|"sends and receives"| node_transport_api
node_transport_api -->|"opens connection"| node_endpoint
node_transport_api -->|"transfers frames"| node_frames
node_frames -->|"follows schema"| node_protocol_schema
node_frames -->|"supports splitting"| node_chunking
node_remote_peer -->|"exchanges frames"| node_transport_api

click node_service_contract "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/service.rs"
click node_sampler_api "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/sampler.rs"
click node_handler_api "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/handler.rs"
click node_command_api "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/command.rs"
click node_wire_api "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/wire.rs"
click node_engine_core "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/engine.rs"
click node_service_runtime "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/service.rs"
click node_command_queue "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/queue.rs"
click node_peer_state "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/peer.rs"
click node_chunking "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/chunk.rs"
click node_worker_threads "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/worker.rs"
click node_stats "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/stats.rs"
click node_transport_api "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/traits.rs"
click node_endpoint "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/endpoint.rs"
click node_frames "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/frame.rs"
click node_protocol_schema "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/proto/frame.proto"
click node_cgroup "https://github.com/wegoingprobyn/clusterservices/blob/main/crates/plugins/cgroup/src/lib.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_service_contract,node_sampler_api,node_handler_api,node_command_api,node_wire_api toneBlue
class node_engine_core,node_service_runtime,node_command_queue,node_peer_state,node_chunking,node_worker_threads,node_stats,node_service_store toneAmber
class node_transport_api,node_endpoint,node_frames,node_protocol_schema toneMint
class node_cgroup toneRose
class node_operator,node_remote_peer toneIndigo
```

## Components

### Plugin API

- [Service contracts](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/service.rs): `crates/core/api/src/service.rs`
- [Sampler API](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/sampler.rs): `crates/core/api/src/sampler.rs`
- [Handler API](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/handler.rs): `crates/core/api/src/handler.rs`
- [Command API](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/command.rs): `crates/core/api/src/command.rs`
- [Wire encoding](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/core/api/src/wire.rs): `crates/core/api/src/wire.rs`

### Runtime Engine

- [Node engine](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/engine.rs): `crates/runtime/engine/src/engine.rs`
- [Service lifecycle](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/service.rs): `crates/runtime/engine/src/service.rs`
- [Command routing](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/queue.rs): `crates/runtime/engine/src/queue.rs`
- [Peer sessions](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/peer.rs): `crates/runtime/engine/src/peer.rs`
- [Message chunks](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/chunk.rs): `crates/runtime/engine/src/chunk.rs`
- [Plugin workers](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/worker.rs): `crates/runtime/engine/src/worker.rs`
- [Runtime stats](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/engine/src/stats.rs): `crates/runtime/engine/src/stats.rs`

### Peer Transport

- [Transport API](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/traits.rs): `crates/runtime/transport/src/traits.rs`
- [Connection endpoints](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/endpoint.rs): `crates/runtime/transport/src/endpoint.rs`
- [Protocol frames](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/src/frame.rs): `crates/runtime/transport/src/frame.rs`
- [Wire schema](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/runtime/transport/proto/frame.proto): `crates/runtime/transport/proto/frame.proto`

### Built-in Plugin

- [Cgroup service](https://github.com/wegoingprobyn/clusterservices/blob/main/crates/plugins/cgroup/src/lib.rs): `crates/plugins/cgroup/src/lib.rs`

### Other components

- **Command issuer**
- **Remote peer**
- **Service-owned state**

## Connections

- Cgroup service → Service contracts: implements
- Cgroup service → Sampler API: samples via
- Node engine → Service lifecycle: manages
- Node engine → Transport API: connects through
- Node engine → Peer sessions: tracks peers
- Node engine → Command routing: dispatches commands
- Node engine → Runtime stats: updates counters
- Service lifecycle → Sampler API: runs samplers
- Service lifecycle → Handler API: invokes handlers
- Service lifecycle → Plugin workers: runs blocking work
- Service lifecycle → Wire encoding: encodes samples
- Service lifecycle → Command API: handles commands
- Handler API → Service-owned state: processes data
- Command issuer → Node engine: requests command
- Command routing → Peer sessions: targets peer
- Peer sessions → Transport API: sends and receives
- Transport API → Connection endpoints: opens connection
- Transport API → Protocol frames: transfers frames
- Protocol frames → Wire schema: follows schema
- Protocol frames → Message chunks: supports splitting
- Remote peer → Transport API: exchanges frames