# msr327/edge-swarm architecture

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

- Interactive diagram: https://gitdiagram.com/msr327/edge-swarm
- Repository: https://github.com/msr327/edge-swarm

## Overview

edge-swarm is a peer-to-peer runtime for distributing LLM inference across heterogeneous LAN devices. The documented workflow discovers peers and hardware, assigns contiguous model-layer slices, then runs token generation locally or streams activations to remote workers over gRPC; workers keep per-session KV caches and the final slice samples tokens. The CLI exposes discovery, planning, and worker startup, while the sampled runner provides the generation coordinator. README capabilities such as simulation and hardware support are documented, but their implementation paths are not mapped here. Edges are limited to sampled calls and explicit README relationships.

Main entry points: [`swarm/cli.py`](https://github.com/msr327/edge-swarm/blob/main/swarm/cli.py) (CLI Commands), [`swarm/network/grpc_server.py`](https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_server.py) (gRPC Server), [`swarm/engine/pipeline_runner.py`](https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py) (Local Pipeline Worker), [`swarm/network/grpc_client.py`](https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_client.py) (gRPC Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["CLI and Coordination"]
  node_cli["CLI Commands<br/>[cli.py]"]
  node_coordinator["Pipeline Coordinator<br/>[pipeline_runner.py]"]
end

subgraph group_cluster["Peer Discovery and Scheduling"]
  node_discovery["Peer Discovery<br/>[peer_discovery.py]"]
  node_partitioner["Layer Partitioner<br/>[partitioner.py]"]
  node_slices["Pipeline Plan<br/>[partitioner.py]"]
end

subgraph group_compute["Model Execution"]
  node_submodel["Sliced Transformer<br/>[model_loader.py]"]
  node_worker["Local Pipeline Worker<br/>[pipeline_runner.py]"]
  node_kv["Session KV Cache<br/>[pipeline_runner.py]"]
end

subgraph group_transport["Tensor Transport"]
  node_grpcserver["gRPC Server<br/>[grpc_server.py]"]
  node_grpcclient["gRPC Client<br/>[grpc_client.py]"]
  node_serializer["Tensor Serializer<br/>[serializer.py]"]
  node_rpccontract["RPC Messages<br/>[swarm.proto]"]
end

node_operator(("Operator"))
node_lan(("LAN Peers"))

node_operator -->|"invokes"| node_cli
node_cli -->|"starts discovery"| node_discovery
node_cli -->|"calculates plan"| node_partitioner
node_cli -->|"creates model"| node_submodel
node_cli -->|"creates worker"| node_worker
node_cli -->|"starts server"| node_grpcserver
node_lan -->|"advertises peers"| node_discovery
node_discovery -->|"provides nodes"| node_partitioner
node_partitioner -->|"produces slices"| node_slices
node_coordinator -->|"iterates slices"| node_slices
node_coordinator -->|"runs local slice"| node_worker
node_worker -->|"executes forward"| node_submodel
node_worker -->|"updates cache"| node_kv
node_coordinator -->|"forwards remote slice"| node_grpcclient
node_grpcclient -->|"streams activations"| node_grpcserver
node_grpcserver -->|"invokes callback"| node_worker
node_grpcclient -->|"serializes tensors"| node_serializer
node_grpcserver -->|"encodes tensors"| node_serializer
node_grpcclient -->|"uses messages"| node_rpccontract
node_grpcserver -->|"implements service"| node_rpccontract

click node_cli "https://github.com/msr327/edge-swarm/blob/main/swarm/cli.py"
click node_coordinator "https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py"
click node_discovery "https://github.com/msr327/edge-swarm/blob/main/swarm/discovery/peer_discovery.py"
click node_partitioner "https://github.com/msr327/edge-swarm/blob/main/swarm/scheduler/partitioner.py"
click node_slices "https://github.com/msr327/edge-swarm/blob/main/swarm/scheduler/partitioner.py"
click node_submodel "https://github.com/msr327/edge-swarm/blob/main/swarm/engine/model_loader.py"
click node_worker "https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py"
click node_kv "https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py"
click node_grpcserver "https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_server.py"
click node_grpcclient "https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_client.py"
click node_serializer "https://github.com/msr327/edge-swarm/blob/main/swarm/network/serializer.py"
click node_rpccontract "https://github.com/msr327/edge-swarm/blob/main/protos/swarm.proto"

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_cli,node_coordinator toneBlue
class node_discovery,node_partitioner,node_slices toneAmber
class node_submodel,node_worker,node_kv toneMint
class node_grpcserver,node_grpcclient,node_serializer,node_rpccontract toneRose
class node_operator,node_lan toneIndigo
```

## Components

### CLI and Coordination

- [CLI Commands](https://github.com/msr327/edge-swarm/blob/main/swarm/cli.py): `swarm/cli.py`
- [Pipeline Coordinator](https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py): `swarm/engine/pipeline_runner.py`

### Peer Discovery and Scheduling

- [Peer Discovery](https://github.com/msr327/edge-swarm/blob/main/swarm/discovery/peer_discovery.py): `swarm/discovery/peer_discovery.py`
- [Layer Partitioner](https://github.com/msr327/edge-swarm/blob/main/swarm/scheduler/partitioner.py): `swarm/scheduler/partitioner.py`
- [Pipeline Plan](https://github.com/msr327/edge-swarm/blob/main/swarm/scheduler/partitioner.py): `swarm/scheduler/partitioner.py`

### Model Execution

- [Sliced Transformer](https://github.com/msr327/edge-swarm/blob/main/swarm/engine/model_loader.py): `swarm/engine/model_loader.py`
- [Local Pipeline Worker](https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py): `swarm/engine/pipeline_runner.py`
- [Session KV Cache](https://github.com/msr327/edge-swarm/blob/main/swarm/engine/pipeline_runner.py): `swarm/engine/pipeline_runner.py`

### Tensor Transport

- [gRPC Server](https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_server.py): `swarm/network/grpc_server.py`
- [gRPC Client](https://github.com/msr327/edge-swarm/blob/main/swarm/network/grpc_client.py): `swarm/network/grpc_client.py`
- [Tensor Serializer](https://github.com/msr327/edge-swarm/blob/main/swarm/network/serializer.py): `swarm/network/serializer.py`
- [RPC Messages](https://github.com/msr327/edge-swarm/blob/main/protos/swarm.proto): `protos/swarm.proto`

### Other components

- **Operator**
- **LAN Peers**

## Connections

- Operator → CLI Commands: invokes (evidence: `README.md`)
- CLI Commands → Peer Discovery: starts discovery (evidence: `swarm/cli.py`)
- CLI Commands → Layer Partitioner: calculates plan (evidence: `swarm/cli.py`)
- CLI Commands → Sliced Transformer: creates model (evidence: `swarm/cli.py`)
- CLI Commands → Local Pipeline Worker: creates worker (evidence: `swarm/cli.py`)
- CLI Commands → gRPC Server: starts server (evidence: `swarm/cli.py`)
- LAN Peers → Peer Discovery: advertises peers (evidence: `README.md`)
- Peer Discovery → Layer Partitioner: provides nodes (evidence: `swarm/scheduler/partitioner.py`)
- Layer Partitioner → Pipeline Plan: produces slices (evidence: `swarm/scheduler/partitioner.py`)
- Pipeline Coordinator → Pipeline Plan: iterates slices (evidence: `swarm/engine/pipeline_runner.py`)
- Pipeline Coordinator → Local Pipeline Worker: runs local slice (evidence: `swarm/engine/pipeline_runner.py`)
- Local Pipeline Worker → Sliced Transformer: executes forward (evidence: `swarm/engine/pipeline_runner.py`)
- Local Pipeline Worker → Session KV Cache: updates cache (evidence: `swarm/engine/pipeline_runner.py`)
- Pipeline Coordinator → gRPC Client: forwards remote slice (evidence: `swarm/engine/pipeline_runner.py`)
- gRPC Client → gRPC Server: streams activations (evidence: `README.md`)
- gRPC Server → Local Pipeline Worker: invokes callback (evidence: `swarm/network/grpc_server.py`)
- gRPC Client → Tensor Serializer: serializes tensors (evidence: `swarm/network/grpc_client.py`)
- gRPC Server → Tensor Serializer: encodes tensors (evidence: `swarm/network/grpc_server.py`)
- gRPC Client → RPC Messages: uses messages (evidence: `protos/swarm.proto`)
- gRPC Server → RPC Messages: implements service (evidence: `protos/swarm.proto`)
