# jumpr15/simple-orchestrator architecture

> Architecture diagram of the GitHub repository jumpr15/simple-orchestrator, 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/jumpr15/simple-orchestrator
- Repository: https://github.com/jumpr15/simple-orchestrator

## Overview

Simple Orchestrator manages worker nodes and desired container counts from a master. Workers request cluster admission, then expose an RPC heartbeat endpoint; the master stores node addresses, schedules container configuration, and sends health checks that can trigger container creation. The README also describes client traffic through a reverse proxy and cluster state management. The load-balancer client exists, but sampled code does not wire it into health checks or show traffic routing; those links are therefore left separate. The worker container implementation is a stub, so container execution details are not shown.

Main entry points: [`master/healthService/healthService.go`](https://github.com/jumpr15/simple-orchestrator/blob/main/master/healthService/healthService.go) (Health service), [`worker/worker.go`](https://github.com/jumpr15/simple-orchestrator/blob/main/worker/worker.go) (Worker startup), [`common/heartbeat/heartbeat.go`](https://github.com/jumpr15/simple-orchestrator/blob/main/common/heartbeat/heartbeat.go) (Heartbeat handler), [`master/joinService/joinService.go`](https://github.com/jumpr15/simple-orchestrator/blob/main/master/joinService/joinService.go) (Join service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_master["Master control"]
  node_master_app["Master startup<br/>[master.go]"]
  node_join["Join service<br/>[joinService.go]"]
  node_node_store[("Node store<br/>[kvStore.go]")]
  node_health["Health service<br/>[healthService.go]"]
  node_scheduler["Container scheduler<br/>[scheduler.go]"]
end

subgraph group_worker["Worker runtime"]
  node_worker_app["Worker startup<br/>[worker.go]"]
  node_worker_cache[("Worker cache")]
  node_listener["RPC listener<br/>[listenerService.go]"]
  node_container_service["Container service"]
end

subgraph group_shared["Shared contracts"]
  node_heartbeat["Heartbeat handler<br/>[heartbeat.go]"]
  node_rpc_contract["Heartbeat contract<br/>[heartbeatTypes.go]"]
end

subgraph group_proxy["Traffic routing"]
  node_lb_client["Load balancer client<br/>[loadBalancer.go]"]
  node_caddy_config["Caddy config<br/>[caddy.json]"]
end

node_operator(("Joining worker"))
node_client(("Traffic client"))
node_caddy["Caddy proxy"]

node_operator -->|"starts"| node_worker_app
node_worker_app -->|"requests join"| node_join
node_join -->|"registers node"| node_node_store
node_master_app -->|"starts"| node_join
node_master_app -->|"starts"| node_health
node_health -->|"reads nodes"| node_node_store
node_health -->|"requests config"| node_scheduler
node_health -->|"sends RPC check"| node_listener
node_worker_app -->|"creates cache"| node_worker_cache
node_worker_app -->|"starts"| node_listener
node_listener -->|"dispatches RPC"| node_heartbeat
node_heartbeat -->|"reads and updates"| node_worker_cache
node_heartbeat -->|"starts containers"| node_container_service
node_health -->|"uses request types"| node_rpc_contract
node_heartbeat -->|"handles request types"| node_rpc_contract
node_lb_client -.->|"updates upstreams"| node_caddy
node_caddy_config -.->|"configures"| node_caddy
node_client -.->|"sends traffic"| node_caddy

click node_master_app "https://github.com/jumpr15/simple-orchestrator/blob/main/master/master.go"
click node_join "https://github.com/jumpr15/simple-orchestrator/blob/main/master/joinService/joinService.go"
click node_node_store "https://github.com/jumpr15/simple-orchestrator/blob/main/master/kvStore/kvStore.go"
click node_health "https://github.com/jumpr15/simple-orchestrator/blob/main/master/healthService/healthService.go"
click node_scheduler "https://github.com/jumpr15/simple-orchestrator/blob/main/master/scheduler/scheduler.go"
click node_lb_client "https://github.com/jumpr15/simple-orchestrator/blob/main/master/loadBalancer/loadBalancer.go"
click node_caddy_config "https://github.com/jumpr15/simple-orchestrator/blob/main/caddy.json"
click node_worker_app "https://github.com/jumpr15/simple-orchestrator/blob/main/worker/worker.go"
click node_listener "https://github.com/jumpr15/simple-orchestrator/blob/main/worker/listenerService/listenerService.go"
click node_heartbeat "https://github.com/jumpr15/simple-orchestrator/blob/main/common/heartbeat/heartbeat.go"
click node_container_service "https://github.com/jumpr15/simple-orchestrator/blob/main/worker/containerService/containerService.go"
click node_rpc_contract "https://github.com/jumpr15/simple-orchestrator/blob/main/common/types/heartbeatTypes/heartbeatTypes.go"

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_master_app,node_join,node_node_store,node_health,node_scheduler,node_client toneBlue
class node_worker_app,node_worker_cache,node_listener,node_container_service toneAmber
class node_heartbeat,node_rpc_contract toneMint
class node_lb_client,node_caddy_config,node_operator toneRose
class node_caddy toneIndigo
```

## Components

### Master control

- [Master startup](https://github.com/jumpr15/simple-orchestrator/blob/main/master/master.go): `master/master.go`
- [Join service](https://github.com/jumpr15/simple-orchestrator/blob/main/master/joinService/joinService.go): `master/joinService/joinService.go`
- [Node store](https://github.com/jumpr15/simple-orchestrator/blob/main/master/kvStore/kvStore.go): `master/kvStore/kvStore.go`
- [Health service](https://github.com/jumpr15/simple-orchestrator/blob/main/master/healthService/healthService.go): `master/healthService/healthService.go`
- [Container scheduler](https://github.com/jumpr15/simple-orchestrator/blob/main/master/scheduler/scheduler.go): `master/scheduler/scheduler.go`

### Worker runtime

- [Worker startup](https://github.com/jumpr15/simple-orchestrator/blob/main/worker/worker.go): `worker/worker.go`
- **Worker cache**
- [RPC listener](https://github.com/jumpr15/simple-orchestrator/blob/main/worker/listenerService/listenerService.go): `worker/listenerService/listenerService.go`
- [Container service](https://github.com/jumpr15/simple-orchestrator/blob/main/worker/containerService/containerService.go): `worker/containerService/containerService.go`

### Shared contracts

- [Heartbeat handler](https://github.com/jumpr15/simple-orchestrator/blob/main/common/heartbeat/heartbeat.go): `common/heartbeat/heartbeat.go`
- [Heartbeat contract](https://github.com/jumpr15/simple-orchestrator/blob/main/common/types/heartbeatTypes/heartbeatTypes.go): `common/types/heartbeatTypes/heartbeatTypes.go`

### Traffic routing

- [Load balancer client](https://github.com/jumpr15/simple-orchestrator/blob/main/master/loadBalancer/loadBalancer.go): `master/loadBalancer/loadBalancer.go`
- [Caddy config](https://github.com/jumpr15/simple-orchestrator/blob/main/caddy.json): `caddy.json`

### Other components

- **Joining worker**
- **Traffic client**
- **Caddy proxy**

## Connections

- Joining worker → Worker startup: starts
- Worker startup → Join service: requests join
- Join service → Node store: registers node
- Master startup → Join service: starts
- Master startup → Health service: starts
- Health service → Node store: reads nodes
- Health service → Container scheduler: requests config
- Health service → RPC listener: sends RPC check
- Worker startup → Worker cache: creates cache
- Worker startup → RPC listener: starts
- RPC listener → Heartbeat handler: dispatches RPC
- Heartbeat handler → Worker cache: reads and updates
- Heartbeat handler → Container service: starts containers
- Health service → Heartbeat contract: uses request types
- Heartbeat handler → Heartbeat contract: handles request types
- Load balancer client → Caddy proxy: updates upstreams
- Caddy config → Caddy proxy: configures
- Traffic client → Caddy proxy: sends traffic