# blalabs/ansible-worker architecture

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

- Interactive diagram: https://gitdiagram.com/blalabs/ansible-worker
- Repository: https://github.com/blalabs/ansible-worker

## Overview

ansible-worker receives playbook requests through either MQTT or HTTP, validates and queues them, then executes one task at a time with ansible-playbook. Execution updates task state and parses Ansible output into progress counters and terminal results. The orchestrator routes those updates back through the selected transport. Configuration supports shared MQTT delivery, authenticated/TLS HTTP or MQTT, optional Git pulls, bounded queues, timeouts, and graceful cancellation. Some wiring is inferred only from documented interfaces and sampled excerpts.

Main entry points: [`src/main.rs`](https://github.com/blalabs/ansible-worker/blob/main/src/main.rs) (Worker Orchestrator), [`src/executor.rs`](https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs) (Task Executor), [`src/transport/mqtt.rs`](https://github.com/blalabs/ansible-worker/blob/main/src/transport/mqtt.rs) (MQTT Receiver), [`src/transport/http.rs`](https://github.com/blalabs/ansible-worker/blob/main/src/transport/http.rs) (HTTP Receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_config["Config Loader<br/>[config.rs]"]
  node_orchestrator["Worker Orchestrator<br/>[main.rs]"]
end

subgraph group_ingress["Task Ingress"]
  node_mqtt_receiver["MQTT Receiver<br/>[mqtt.rs]"]
  node_http_receiver["HTTP Receiver<br/>[http.rs]"]
  node_task_request["Task Request<br/>[models.rs]"]
  node_task_queue["Bounded Task Queue<br/>[task_queue.rs]"]
end

subgraph group_execution["Execution"]
  node_executor["Task Executor<br/>[executor.rs]"]
  node_path_validation["Path Validation<br/>[executor.rs]"]
  node_output_parser["Output Parser<br/>[executor.rs]"]
end

subgraph group_reporting["Status Reporting"]
  node_task_status["Task Status<br/>[models.rs]"]
  node_mqtt_publisher["MQTT Publisher<br/>[mqtt.rs]"]
  node_http_publisher["HTTP Publisher<br/>[http.rs]"]
end

subgraph group_external["External Dependencies"]
  node_ansible["ansible-playbook"]
  node_mqtt_broker["MQTT Broker"]
  node_http_api["HTTP Task API"]
  node_git["Git Repository"]
end

node_operator(("Operator"))

node_operator -->|"starts worker"| node_orchestrator
node_orchestrator -->|"loads config"| node_config
node_orchestrator -.->|"starts transport"| node_mqtt_receiver
node_orchestrator -.->|"starts transport"| node_http_receiver
node_orchestrator -->|"creates queue"| node_task_queue
node_orchestrator -->|"starts executor"| node_executor
node_mqtt_broker -.->|"delivers tasks"| node_mqtt_receiver
node_http_api -.->|"serves tasks"| node_http_receiver
node_mqtt_receiver -->|"parses payload"| node_task_request
node_http_receiver -->|"parses JSON"| node_task_request
node_mqtt_receiver -->|"enqueues tasks"| node_task_queue
node_http_receiver -->|"enqueues tasks"| node_task_queue
node_task_queue -->|"provides tasks"| node_executor
node_executor -->|"validates paths"| node_path_validation
node_executor -.->|"pulls repository"| node_git
node_executor -->|"runs playbook"| node_ansible
node_ansible -->|"writes stdout"| node_output_parser
node_output_parser -->|"updates counts"| node_task_status
node_executor -->|"sets state"| node_task_status
node_executor -->|"sends status"| node_orchestrator
node_orchestrator -.->|"dispatches updates"| node_mqtt_publisher
node_orchestrator -.->|"dispatches updates"| node_http_publisher
node_mqtt_publisher -.->|"publishes status"| node_mqtt_broker
node_http_publisher -.->|"posts status"| node_http_api

click node_config "https://github.com/blalabs/ansible-worker/blob/main/src/config.rs"
click node_orchestrator "https://github.com/blalabs/ansible-worker/blob/main/src/main.rs"
click node_mqtt_receiver "https://github.com/blalabs/ansible-worker/blob/main/src/transport/mqtt.rs"
click node_http_receiver "https://github.com/blalabs/ansible-worker/blob/main/src/transport/http.rs"
click node_task_request "https://github.com/blalabs/ansible-worker/blob/main/src/models.rs"
click node_task_queue "https://github.com/blalabs/ansible-worker/blob/main/src/task_queue.rs"
click node_executor "https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs"
click node_path_validation "https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs"
click node_output_parser "https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs"
click node_task_status "https://github.com/blalabs/ansible-worker/blob/main/src/models.rs"
click node_mqtt_publisher "https://github.com/blalabs/ansible-worker/blob/main/src/transport/mqtt.rs"
click node_http_publisher "https://github.com/blalabs/ansible-worker/blob/main/src/transport/http.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_config,node_orchestrator toneBlue
class node_mqtt_receiver,node_http_receiver,node_task_request,node_task_queue toneAmber
class node_executor,node_path_validation,node_output_parser toneMint
class node_task_status,node_mqtt_publisher,node_http_publisher toneRose
class node_ansible,node_mqtt_broker,node_http_api,node_git,node_operator toneIndigo
```

## Components

### Control Plane

- [Config Loader](https://github.com/blalabs/ansible-worker/blob/main/src/config.rs): `src/config.rs`
- [Worker Orchestrator](https://github.com/blalabs/ansible-worker/blob/main/src/main.rs): `src/main.rs`

### Task Ingress

- [MQTT Receiver](https://github.com/blalabs/ansible-worker/blob/main/src/transport/mqtt.rs): `src/transport/mqtt.rs`
- [HTTP Receiver](https://github.com/blalabs/ansible-worker/blob/main/src/transport/http.rs): `src/transport/http.rs`
- [Task Request](https://github.com/blalabs/ansible-worker/blob/main/src/models.rs): `src/models.rs`
- [Bounded Task Queue](https://github.com/blalabs/ansible-worker/blob/main/src/task_queue.rs): `src/task_queue.rs`

### Execution

- [Task Executor](https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs): `src/executor.rs`
- [Path Validation](https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs): `src/executor.rs`
- [Output Parser](https://github.com/blalabs/ansible-worker/blob/main/src/executor.rs): `src/executor.rs`

### Status Reporting

- [Task Status](https://github.com/blalabs/ansible-worker/blob/main/src/models.rs): `src/models.rs`
- [MQTT Publisher](https://github.com/blalabs/ansible-worker/blob/main/src/transport/mqtt.rs): `src/transport/mqtt.rs`
- [HTTP Publisher](https://github.com/blalabs/ansible-worker/blob/main/src/transport/http.rs): `src/transport/http.rs`

### External Dependencies

- **ansible-playbook**
- **MQTT Broker**
- **HTTP Task API**
- **Git Repository**

### Other components

- **Operator**

## Connections

- Operator → Worker Orchestrator: starts worker
- Worker Orchestrator → Config Loader: loads config
- Worker Orchestrator → MQTT Receiver: starts transport
- Worker Orchestrator → HTTP Receiver: starts transport
- Worker Orchestrator → Bounded Task Queue: creates queue
- Worker Orchestrator → Task Executor: starts executor
- MQTT Broker → MQTT Receiver: delivers tasks
- HTTP Task API → HTTP Receiver: serves tasks
- MQTT Receiver → Task Request: parses payload
- HTTP Receiver → Task Request: parses JSON
- MQTT Receiver → Bounded Task Queue: enqueues tasks
- HTTP Receiver → Bounded Task Queue: enqueues tasks
- Bounded Task Queue → Task Executor: provides tasks
- Task Executor → Path Validation: validates paths
- Task Executor → Git Repository: pulls repository
- Task Executor → ansible-playbook: runs playbook
- ansible-playbook → Output Parser: writes stdout
- Output Parser → Task Status: updates counts
- Task Executor → Task Status: sets state
- Task Executor → Worker Orchestrator: sends status
- Worker Orchestrator → MQTT Publisher: dispatches updates
- Worker Orchestrator → HTTP Publisher: dispatches updates
- MQTT Publisher → MQTT Broker: publishes status
- HTTP Publisher → HTTP Task API: posts status
