# nshaibu/volnux architecture

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

## Overview

Volnux is a workflow orchestration framework: users can define task graphs in Pointy-Lang, build pipeline flows, and execute workflows with conditional, sequential, and parallel task handling. Its broader documented capabilities include hybrid concurrency, distributed execution, extensible signals, and event-driven behavior; the tree also shows persistence backends, telemetry, and adaptive scaling. The sampled engine explicitly dispatches execution contexts, while several integrations and subsystem connections are represented only by their supported entry points because their wiring was not sampled.

Main entry points: [`volnux/pipeline.py`](https://github.com/nshaibu/volnux/blob/main/volnux/pipeline.py) (Pipeline coordination), [`volnux/task/build_pipeline_flow.py`](https://github.com/nshaibu/volnux/blob/main/volnux/task/build_pipeline_flow.py) (Flow builder), [`volnux/engine/default_engine.py`](https://github.com/nshaibu/volnux/blob/main/volnux/engine/default_engine.py) (Workflow engine), [`volnux/execution/context.py`](https://github.com/nshaibu/volnux/blob/main/volnux/execution/context.py) (Execution context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Workflow authoring"]
  node_pointy["Pointy parser<br/>[__init__.py]"]
  node_flow_builder["Flow builder"]
  node_task_graph["Task graph<br/>[task.py]"]
  node_cli["Command interface<br/>[main.py]"]
  node_run_command["Run workflow<br/>[run_workflow.py]"]
end

subgraph group_runtime["Workflow runtime"]
  node_pipeline["Pipeline coordination<br/>[pipeline.py]"]
  node_engine["Workflow engine<br/>[default_engine.py]"]
  node_workflow_loaders["Workflow loading"]
  node_execution_context["Execution context<br/>[context.py]"]
  node_execution_state[("Execution state<br/>[state_manager.py]")]
  node_workflow_result["Workflow result<br/>[result.py]"]
end

subgraph group_execution["Task execution"]
  node_task_executor["Task executors"]
  node_remote_executor["Remote execution<br/>[remote_executor.py]"]
  node_remote_managers["Remote managers"]
end

subgraph group_integrations["State and integrations"]
  node_backend_connectors["Backend connectors"]
  node_backend_stores[("Backend stores")]
  node_signals["Signals and events<br/>[signals.py]"]
end

subgraph group_operations["Operations"]
  node_telemetry["Telemetry"]
  node_adaptive_scaling["Adaptive scaling<br/>[engine.py]"]
end

node_author(("Workflow author"))
node_cli_user(("CLI user"))

node_author -->|"provides DSL"| node_flow_builder
node_flow_builder -->|"parses code"| node_pointy
node_flow_builder -->|"generates flow"| node_task_graph
node_cli_user -->|"runs command"| node_cli
node_cli -->|"dispatches command"| node_run_command
node_run_command -->|"starts workflow"| node_pipeline
node_workflow_loaders -->|"loads workflow"| node_pipeline
node_pipeline -->|"executes workflow"| node_engine
node_engine -->|"dispatches context"| node_execution_context
node_execution_context -->|"runs tasks"| node_task_executor
node_engine -->|"produces result"| node_workflow_result
node_execution_context -->|"records state"| node_execution_state
node_remote_executor -->|"sends tasks"| node_remote_managers
node_backend_connectors -->|"connects storage"| node_backend_stores
node_pipeline -.->|"emits lifecycle events"| node_signals
node_pipeline -.->|"reports execution"| node_telemetry
node_task_executor -.->|"scales workers"| node_adaptive_scaling

click node_pointy "https://github.com/nshaibu/volnux/blob/main/volnux/parser/__init__.py"
click node_flow_builder "https://github.com/nshaibu/volnux/blob/main/volnux/task/build_pipeline_flow.py"
click node_task_graph "https://github.com/nshaibu/volnux/blob/main/volnux/task/task.py"
click node_cli "https://github.com/nshaibu/volnux/blob/main/volnux/cli/main.py"
click node_run_command "https://github.com/nshaibu/volnux/blob/main/volnux/cli/command/builtins/run_workflow.py"
click node_pipeline "https://github.com/nshaibu/volnux/blob/main/volnux/pipeline.py"
click node_engine "https://github.com/nshaibu/volnux/blob/main/volnux/engine/default_engine.py"
click node_workflow_loaders "https://github.com/nshaibu/volnux/tree/main/volnux/engine/workflows/loaders"
click node_execution_context "https://github.com/nshaibu/volnux/blob/main/volnux/execution/context.py"
click node_execution_state "https://github.com/nshaibu/volnux/blob/main/volnux/execution/state_manager.py"
click node_task_executor "https://github.com/nshaibu/volnux/blob/main/volnux/executors/default_executor.py"
click node_remote_executor "https://github.com/nshaibu/volnux/blob/main/volnux/executors/remote_executor.py"
click node_remote_managers "https://github.com/nshaibu/volnux/tree/main/volnux/manager"
click node_backend_connectors "https://github.com/nshaibu/volnux/tree/main/volnux/backends/connectors"
click node_backend_stores "https://github.com/nshaibu/volnux/tree/main/volnux/backends/stores"
click node_signals "https://github.com/nshaibu/volnux/blob/main/volnux/signal/signals.py"
click node_telemetry "https://github.com/nshaibu/volnux/tree/main/volnux/telemetry"
click node_adaptive_scaling "https://github.com/nshaibu/volnux/blob/main/volnux/scaling/adaptive/engine.py"
click node_workflow_result "https://github.com/nshaibu/volnux/blob/main/volnux/execution/result.py"

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_pointy,node_flow_builder,node_task_graph,node_cli,node_run_command,node_cli_user toneBlue
class node_pipeline,node_engine,node_workflow_loaders,node_execution_context,node_execution_state,node_workflow_result toneAmber
class node_task_executor,node_remote_executor,node_remote_managers toneMint
class node_backend_connectors,node_backend_stores,node_signals toneRose
class node_telemetry,node_adaptive_scaling,node_author toneIndigo
```

## Components

### Workflow authoring

- [Pointy parser](https://github.com/nshaibu/volnux/blob/main/volnux/parser/__init__.py): `volnux/parser/__init__.py`
- [Flow builder](https://github.com/nshaibu/volnux/blob/main/volnux/task/build_pipeline_flow.py): `volnux/task/build_pipeline_flow.py`
- [Task graph](https://github.com/nshaibu/volnux/blob/main/volnux/task/task.py): `volnux/task/task.py`
- [Command interface](https://github.com/nshaibu/volnux/blob/main/volnux/cli/main.py): `volnux/cli/main.py`
- [Run workflow](https://github.com/nshaibu/volnux/blob/main/volnux/cli/command/builtins/run_workflow.py): `volnux/cli/command/builtins/run_workflow.py`

### Workflow runtime

- [Pipeline coordination](https://github.com/nshaibu/volnux/blob/main/volnux/pipeline.py): `volnux/pipeline.py`
- [Workflow engine](https://github.com/nshaibu/volnux/blob/main/volnux/engine/default_engine.py): `volnux/engine/default_engine.py`
- [Workflow loading](https://github.com/nshaibu/volnux/tree/main/volnux/engine/workflows/loaders): `volnux/engine/workflows/loaders`
- [Execution context](https://github.com/nshaibu/volnux/blob/main/volnux/execution/context.py): `volnux/execution/context.py`
- [Execution state](https://github.com/nshaibu/volnux/blob/main/volnux/execution/state_manager.py): `volnux/execution/state_manager.py`
- [Workflow result](https://github.com/nshaibu/volnux/blob/main/volnux/execution/result.py): `volnux/execution/result.py`

### Task execution

- [Task executors](https://github.com/nshaibu/volnux/blob/main/volnux/executors/default_executor.py): `volnux/executors/default_executor.py`
- [Remote execution](https://github.com/nshaibu/volnux/blob/main/volnux/executors/remote_executor.py): `volnux/executors/remote_executor.py`
- [Remote managers](https://github.com/nshaibu/volnux/tree/main/volnux/manager): `volnux/manager`

### State and integrations

- [Backend connectors](https://github.com/nshaibu/volnux/tree/main/volnux/backends/connectors): `volnux/backends/connectors`
- [Backend stores](https://github.com/nshaibu/volnux/tree/main/volnux/backends/stores): `volnux/backends/stores`
- [Signals and events](https://github.com/nshaibu/volnux/blob/main/volnux/signal/signals.py): `volnux/signal/signals.py`

### Operations

- [Telemetry](https://github.com/nshaibu/volnux/tree/main/volnux/telemetry): `volnux/telemetry`
- [Adaptive scaling](https://github.com/nshaibu/volnux/blob/main/volnux/scaling/adaptive/engine.py): `volnux/scaling/adaptive/engine.py`

### Other components

- **Workflow author**
- **CLI user**

## Connections

- Workflow author → Flow builder: provides DSL
- Flow builder → Pointy parser: parses code
- Flow builder → Task graph: generates flow
- CLI user → Command interface: runs command
- Command interface → Run workflow: dispatches command
- Run workflow → Pipeline coordination: starts workflow
- Workflow loading → Pipeline coordination: loads workflow
- Pipeline coordination → Workflow engine: executes workflow
- Workflow engine → Execution context: dispatches context
- Execution context → Task executors: runs tasks
- Workflow engine → Workflow result: produces result
- Execution context → Execution state: records state
- Remote execution → Remote managers: sends tasks
- Backend connectors → Backend stores: connects storage
- Pipeline coordination → Signals and events: emits lifecycle events
- Pipeline coordination → Telemetry: reports execution
- Task executors → Adaptive scaling: scales workers