# j3ssie/osmedeus architecture

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

- Interactive diagram: https://gitdiagram.com/j3ssie/osmedeus
- Repository: https://github.com/j3ssie/osmedeus

## Overview

Osmedeus is a security workflow orchestration engine, exposed through a CLI and REST API. Users select or trigger YAML workflows; workflows are parsed, then executed through host, Docker, or SSH runners and can use utility functions, LLM agents, or distributed workers. Results and operational data are retained for queries and surfaced through the API and embedded dashboard. The README documents the major capabilities; source excerpts show several key call paths, while some subsystem connections below are documented only at a high level.

Main entry points: [`pkg/cli`](https://github.com/j3ssie/osmedeus/tree/main/pkg/cli) (CLI commands), [`internal/executor`](https://github.com/j3ssie/osmedeus/tree/main/internal/executor) (Workflow executor), [`pkg/server/server.go`](https://github.com/j3ssie/osmedeus/blob/main/pkg/server/server.go) (REST API), [`internal/database/database.go`](https://github.com/j3ssie/osmedeus/blob/main/internal/database/database.go) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI commands"]
  node_api["REST API<br/>[server.go]"]
  node_dashboard["Web dashboard"]
end

subgraph group_workflow["Workflow execution"]
  node_parser["Workflow parser<br/>[parser.go]"]
  node_executor["Workflow executor"]
  node_runners["Execution runners"]
  node_functions["Utility functions"]
  node_llm["LLM steps<br/>[llm_executor.go]"]
  node_acp["ACP agents<br/>[acp_client.go]"]
  node_linter["Workflow linter<br/>[rules.go]"]
end

subgraph group_operations["Scheduling and scale"]
  node_scheduler["Event scheduler<br/>[scheduler.go]"]
  node_distributed["Worker execution<br/>[worker.go]"]
  node_redis["Redis queue<br/>[client.go]"]
end

subgraph group_data["State and results"]
  node_database[("Application database<br/>[database.go]")]
  node_snapshots["Run snapshots<br/>[snapshot.go]"]
  node_storage[("Object storage<br/>[storage.go]")]
end

subgraph group_services["Integrations"]
  node_installer["Tool installer<br/>[binary.go]"]
  node_webhooks["Webhook notifications<br/>[webhook.go]"]
  node_cloud["Cloud provisioning"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -.->|"selects workflows"| node_parser
node_cli -->|"starts server"| node_api
node_operator -.->|"uses dashboard"| node_dashboard
node_dashboard -.->|"calls API"| node_api
node_api -->|"loads workflows"| node_parser
node_parser -.->|"provides workflow"| node_executor
node_executor -.->|"dispatches steps"| node_runners
node_executor -.->|"invokes utilities"| node_functions
node_executor -.->|"runs LLM steps"| node_llm
node_executor -.->|"runs ACP agents"| node_acp
node_cli -.->|"lints workflows"| node_linter
node_scheduler -.->|"triggers workflows"| node_executor
node_distributed -.->|"queues tasks"| node_redis
node_distributed -->|"executes tasks"| node_executor
node_distributed -->|"records runs"| node_database
node_api -.->|"serves data"| node_database
node_cli -->|"queries records"| node_database
node_snapshots -.->|"uses run data"| node_database
node_snapshots -.->|"stores snapshots"| node_storage
node_functions -->|"sends events"| node_webhooks
node_cli -.->|"installs tools"| node_installer
node_cli -.->|"manages infrastructure"| node_cloud

click node_cli "https://github.com/j3ssie/osmedeus/tree/main/pkg/cli"
click node_api "https://github.com/j3ssie/osmedeus/blob/main/pkg/server/server.go"
click node_dashboard "https://github.com/j3ssie/osmedeus/tree/main/platform/osmedeus-dashboard"
click node_parser "https://github.com/j3ssie/osmedeus/blob/main/internal/parser/parser.go"
click node_executor "https://github.com/j3ssie/osmedeus/tree/main/internal/executor"
click node_runners "https://github.com/j3ssie/osmedeus/tree/main/internal/runner"
click node_functions "https://github.com/j3ssie/osmedeus/tree/main/internal/functions"
click node_llm "https://github.com/j3ssie/osmedeus/blob/main/internal/executor/llm_executor.go"
click node_acp "https://github.com/j3ssie/osmedeus/blob/main/internal/executor/acp_client.go"
click node_linter "https://github.com/j3ssie/osmedeus/blob/main/internal/linter/rules.go"
click node_scheduler "https://github.com/j3ssie/osmedeus/blob/main/internal/scheduler/scheduler.go"
click node_distributed "https://github.com/j3ssie/osmedeus/blob/main/internal/distributed/worker.go"
click node_database "https://github.com/j3ssie/osmedeus/blob/main/internal/database/database.go"
click node_snapshots "https://github.com/j3ssie/osmedeus/blob/main/internal/snapshot/snapshot.go"
click node_storage "https://github.com/j3ssie/osmedeus/blob/main/internal/storage/storage.go"
click node_installer "https://github.com/j3ssie/osmedeus/blob/main/internal/installer/binary.go"
click node_webhooks "https://github.com/j3ssie/osmedeus/blob/main/internal/notify/webhook.go"
click node_redis "https://github.com/j3ssie/osmedeus/blob/main/internal/distributed/client.go"
click node_cloud "https://github.com/j3ssie/osmedeus/tree/main/internal/cloud"

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_api,node_dashboard toneBlue
class node_parser,node_executor,node_runners,node_functions,node_llm,node_acp,node_linter toneAmber
class node_scheduler,node_distributed,node_redis toneMint
class node_database,node_snapshots,node_storage toneRose
class node_installer,node_webhooks,node_cloud,node_operator toneIndigo
```

## Components

### User entry points

- [CLI commands](https://github.com/j3ssie/osmedeus/tree/main/pkg/cli): `pkg/cli`
- [REST API](https://github.com/j3ssie/osmedeus/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Web dashboard](https://github.com/j3ssie/osmedeus/tree/main/platform/osmedeus-dashboard): `platform/osmedeus-dashboard`

### Workflow execution

- [Workflow parser](https://github.com/j3ssie/osmedeus/blob/main/internal/parser/parser.go): `internal/parser/parser.go`
- [Workflow executor](https://github.com/j3ssie/osmedeus/tree/main/internal/executor): `internal/executor`
- [Execution runners](https://github.com/j3ssie/osmedeus/tree/main/internal/runner): `internal/runner`
- [Utility functions](https://github.com/j3ssie/osmedeus/tree/main/internal/functions): `internal/functions`
- [LLM steps](https://github.com/j3ssie/osmedeus/blob/main/internal/executor/llm_executor.go): `internal/executor/llm_executor.go`
- [ACP agents](https://github.com/j3ssie/osmedeus/blob/main/internal/executor/acp_client.go): `internal/executor/acp_client.go`
- [Workflow linter](https://github.com/j3ssie/osmedeus/blob/main/internal/linter/rules.go): `internal/linter/rules.go`

### Scheduling and scale

- [Event scheduler](https://github.com/j3ssie/osmedeus/blob/main/internal/scheduler/scheduler.go): `internal/scheduler/scheduler.go`
- [Worker execution](https://github.com/j3ssie/osmedeus/blob/main/internal/distributed/worker.go): `internal/distributed/worker.go`
- [Redis queue](https://github.com/j3ssie/osmedeus/blob/main/internal/distributed/client.go): `internal/distributed/client.go`

### State and results

- [Application database](https://github.com/j3ssie/osmedeus/blob/main/internal/database/database.go): `internal/database/database.go`
- [Run snapshots](https://github.com/j3ssie/osmedeus/blob/main/internal/snapshot/snapshot.go): `internal/snapshot/snapshot.go`
- [Object storage](https://github.com/j3ssie/osmedeus/blob/main/internal/storage/storage.go): `internal/storage/storage.go`

### Integrations

- [Tool installer](https://github.com/j3ssie/osmedeus/blob/main/internal/installer/binary.go): `internal/installer/binary.go`
- [Webhook notifications](https://github.com/j3ssie/osmedeus/blob/main/internal/notify/webhook.go): `internal/notify/webhook.go`
- [Cloud provisioning](https://github.com/j3ssie/osmedeus/tree/main/internal/cloud): `internal/cloud`

### Other components

- **Operator**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Workflow parser: selects workflows
- CLI commands → REST API: starts server (evidence: `pkg/cli/server.go`)
- Operator → Web dashboard: uses dashboard
- Web dashboard → REST API: calls API
- REST API → Workflow parser: loads workflows
- Workflow parser → Workflow executor: provides workflow
- Workflow executor → Execution runners: dispatches steps
- Workflow executor → Utility functions: invokes utilities
- Workflow executor → LLM steps: runs LLM steps
- Workflow executor → ACP agents: runs ACP agents
- CLI commands → Workflow linter: lints workflows
- Event scheduler → Workflow executor: triggers workflows
- Worker execution → Redis queue: queues tasks
- Worker execution → Workflow executor: executes tasks (evidence: `internal/distributed/worker.go`)
- Worker execution → Application database: records runs (evidence: `internal/distributed/worker.go`)
- REST API → Application database: serves data
- CLI commands → Application database: queries records (evidence: `pkg/cli/query.go`)
- Run snapshots → Application database: uses run data
- Run snapshots → Object storage: stores snapshots
- Utility functions → Webhook notifications: sends events (evidence: `internal/functions/webhook_functions.go`)
- CLI commands → Tool installer: installs tools
- CLI commands → Cloud provisioning: manages infrastructure