# bhangun/gamelan architecture

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

- Interactive diagram: https://gitdiagram.com/bhangun/gamelan
- Repository: https://github.com/bhangun/gamelan

## Overview

Gamelan is a multi-tenant workflow engine with client and CLI entry points, workflow definition and run management, node execution, executor discovery, and runtime recovery. The README documents workflow, executor, Kafka, gRPC, SDK, plugin, and agent-context capabilities; the tree provides exact implementation paths for many, but not all, of these. Edges are limited to README-documented relationships or source-index/excerpt evidence, so unsampled runtime wiring is omitted.

Main entry points: [`framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowDefinition.java`](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowDefinition.java) (Workflow definitions), [`runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowExecutionEngine.java`](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowExecutionEngine.java) (Workflow execution), [`framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunId.java`](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunId.java) (Workflow runs), [`ui/gamelan-cli/src/main/java/tech/kayys/gamelan/cli/GrpcClientManager.java`](https://github.com/bhangun/gamelan/blob/main/ui/gamelan-cli/src/main/java/tech/kayys/gamelan/cli/GrpcClientManager.java) (Gamelan CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_cli["Gamelan CLI"]
  node_sdk["Client SDK"]
  node_grpc["gRPC executor service"]
end

subgraph group_workflow["Workflow lifecycle"]
  node_definitions["Workflow definitions"]
  node_definition_service["Definition service"]
  node_runs["Workflow runs<br/>[WorkflowRunId.java]"]
  node_run_manager["Run manager"]
  node_run_repo[("Run repository")]
end

subgraph group_runtime["Execution runtime"]
  node_engine["Workflow execution"]
  node_node_dispatch["Node dispatch"]
  node_dag["DAG scheduling"]
  node_recovery["Run recovery"]
  node_engine_context["Engine context"]
end

subgraph group_extensions["Extensions"]
  node_registry[("Executor registry")]
  node_kafka["Kafka integration"]
  node_plugins["Plugin service"]
  node_agent_context[("Agent context store")]
  node_consul["Consul discovery"]
end

node_user(("Workflow operator"))
node_executor(("Workflow executor"))

node_user -->|"manages workflows"| node_cli
node_user -.->|"uses clients"| node_sdk
node_cli -->|"connects via gRPC"| node_grpc
node_user -->|"creates definitions"| node_definitions
node_definitions -->|"starts runs from"| node_runs
node_user -->|"creates and controls"| node_runs
node_definitions -.->|"managed by"| node_definition_service
node_run_manager -.->|"uses repository"| node_run_repo
node_runs -.->|"executes"| node_engine
node_engine -.->|"dispatches nodes"| node_node_dispatch
node_engine -.->|"schedules DAGs"| node_dag
node_recovery -->|"scans active runs"| node_run_repo
node_engine_context -->|"loads and starts"| node_plugins
node_node_dispatch -->|"dispatches work"| node_executor
node_executor -->|"registers remotely"| node_grpc
node_registry -.->|"selects executors"| node_executor
node_kafka -.->|"notifies status"| node_user
node_consul -.->|"discovers services"| node_registry

click node_cli "https://github.com/bhangun/gamelan/blob/main/ui/gamelan-cli/src/main/java/tech/kayys/gamelan/cli/GrpcClientManager.java"
click node_sdk "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-sdk-client-core/src/main/java/tech/kayys/gamelan/sdk/client/WorkflowRunClient.java"
click node_grpc "https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-runtime-distributed/src/main/java/tech/kayys/gamelan/runtime/grpc/ExecutorServiceImpl.java"
click node_definitions "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowDefinition.java"
click node_definition_service "https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowDefinitionService.java"
click node_runs "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunId.java"
click node_run_manager "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunManager.java"
click node_run_repo "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/repository/WorkflowRunRepository.java"
click node_engine "https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowExecutionEngine.java"
click node_node_dispatch "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/execution/DefaultWorkflowEngine.java"
click node_dag "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-dag/src/main/java/tech/kayys/gamelan/dag/DefaultDagSchedulerService.java"
click node_recovery "https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowRecoveryService.java"
click node_engine_context "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/engine/DefaultEngineContext.java"
click node_registry "https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-executor-registry/src/main/java/tech/kayys/gamelan/registry/ExecutorRegistryService.java"
click node_kafka "https://github.com/bhangun/gamelan/blob/main/runtime/protocol/gamelan-protocol-kafka/src/main/java/tech/kayys/gamelan/kafka/EventProjectionService.java"
click node_plugins "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-plugin-spi/src/main/java/tech/kayys/gamelan/plugin/impl/DefaultPluginService.java"
click node_agent_context "https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/agent/context/FileAgentContextStore.java"
click node_consul "https://github.com/bhangun/gamelan/blob/main/runtime/plugins/gamelan-plugin-consul/src/main/java/tech/kayys/gamelan/plugin/consul/ConsulServiceDiscoveryPlugin.java"

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_sdk,node_grpc toneBlue
class node_definitions,node_definition_service,node_runs,node_run_manager,node_run_repo toneAmber
class node_engine,node_node_dispatch,node_dag,node_recovery,node_engine_context toneMint
class node_registry,node_kafka,node_plugins,node_agent_context,node_consul toneRose
class node_user,node_executor toneIndigo
```

## Components

### Clients

- [Gamelan CLI](https://github.com/bhangun/gamelan/blob/main/ui/gamelan-cli/src/main/java/tech/kayys/gamelan/cli/GrpcClientManager.java): `ui/gamelan-cli/src/main/java/tech/kayys/gamelan/cli/GrpcClientManager.java`
- [Client SDK](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-sdk-client-core/src/main/java/tech/kayys/gamelan/sdk/client/WorkflowRunClient.java): `framework/gamelan-sdk-client-core/src/main/java/tech/kayys/gamelan/sdk/client/WorkflowRunClient.java`
- [gRPC executor service](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-runtime-distributed/src/main/java/tech/kayys/gamelan/runtime/grpc/ExecutorServiceImpl.java): `runtime/gamelan-runtime-distributed/src/main/java/tech/kayys/gamelan/runtime/grpc/ExecutorServiceImpl.java`

### Workflow lifecycle

- [Workflow definitions](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowDefinition.java): `framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowDefinition.java`
- [Definition service](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowDefinitionService.java): `runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowDefinitionService.java`
- [Workflow runs](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunId.java): `framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunId.java`
- [Run manager](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunManager.java): `framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/workflow/WorkflowRunManager.java`
- [Run repository](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/repository/WorkflowRunRepository.java): `framework/gamelan-engine-spi/src/main/java/tech/kayys/gamelan/engine/repository/WorkflowRunRepository.java`

### Execution runtime

- [Workflow execution](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowExecutionEngine.java): `runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowExecutionEngine.java`
- [Node dispatch](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/execution/DefaultWorkflowEngine.java): `framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/execution/DefaultWorkflowEngine.java`
- [DAG scheduling](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-dag/src/main/java/tech/kayys/gamelan/dag/DefaultDagSchedulerService.java): `framework/gamelan-dag/src/main/java/tech/kayys/gamelan/dag/DefaultDagSchedulerService.java`
- [Run recovery](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowRecoveryService.java): `runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowRecoveryService.java`
- [Engine context](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/engine/DefaultEngineContext.java): `framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/engine/DefaultEngineContext.java`

### Extensions

- [Executor registry](https://github.com/bhangun/gamelan/blob/main/runtime/gamelan-executor-registry/src/main/java/tech/kayys/gamelan/registry/ExecutorRegistryService.java): `runtime/gamelan-executor-registry/src/main/java/tech/kayys/gamelan/registry/ExecutorRegistryService.java`
- [Kafka integration](https://github.com/bhangun/gamelan/blob/main/runtime/protocol/gamelan-protocol-kafka/src/main/java/tech/kayys/gamelan/kafka/EventProjectionService.java): `runtime/protocol/gamelan-protocol-kafka/src/main/java/tech/kayys/gamelan/kafka/EventProjectionService.java`
- [Plugin service](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-plugin-spi/src/main/java/tech/kayys/gamelan/plugin/impl/DefaultPluginService.java): `framework/gamelan-plugin-spi/src/main/java/tech/kayys/gamelan/plugin/impl/DefaultPluginService.java`
- [Agent context store](https://github.com/bhangun/gamelan/blob/main/framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/agent/context/FileAgentContextStore.java): `framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/agent/context/FileAgentContextStore.java`
- [Consul discovery](https://github.com/bhangun/gamelan/blob/main/runtime/plugins/gamelan-plugin-consul/src/main/java/tech/kayys/gamelan/plugin/consul/ConsulServiceDiscoveryPlugin.java): `runtime/plugins/gamelan-plugin-consul/src/main/java/tech/kayys/gamelan/plugin/consul/ConsulServiceDiscoveryPlugin.java`

### Other components

- **Workflow operator**
- **Workflow executor**

## Connections

- Workflow operator → Gamelan CLI: manages workflows
- Workflow operator → Client SDK: uses clients
- Gamelan CLI → gRPC executor service: connects via gRPC
- Workflow operator → Workflow definitions: creates definitions
- Workflow definitions → Workflow runs: starts runs from
- Workflow operator → Workflow runs: creates and controls
- Workflow definitions → Definition service: managed by
- Run manager → Run repository: uses repository
- Workflow runs → Workflow execution: executes
- Workflow execution → Node dispatch: dispatches nodes
- Workflow execution → DAG scheduling: schedules DAGs
- Run recovery → Run repository: scans active runs (evidence: `runtime/gamelan-engine/src/main/java/tech/kayys/gamelan/workflow/WorkflowRecoveryService.java`)
- Engine context → Plugin service: loads and starts (evidence: `framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/engine/DefaultEngineContext.java`)
- Node dispatch → Workflow executor: dispatches work (evidence: `framework/gamelan-engine-core/src/main/java/tech/kayys/gamelan/core/execution/DefaultWorkflowEngine.java`)
- Workflow executor → gRPC executor service: registers remotely
- Executor registry → Workflow executor: selects executors
- Kafka integration → Workflow operator: notifies status
- Consul discovery → Executor registry: discovers services
