# cabon-tech/zavictl architecture

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

## Overview

zavictl is a CLI-first DevOps control plane: engineers issue lifecycle and operations commands, which either manage catalog state directly or submit workflows for execution through provider adapters. The workflow engine persists execution progress, applies policy decisions, and dispatches steps to integrations. The README documents many additional command families, represented by their existing CLI files or enclosing directory; those handlers were not all sampled, so uncertain wiring is omitted.

Main entry points: [`pkg/execution/engine.go`](https://github.com/cabon-tech/zavictl/blob/main/pkg/execution/engine.go) (Execution engine), [`pkg/provider/registry.go`](https://github.com/cabon-tech/zavictl/blob/main/pkg/provider/registry.go) (Provider registry), [`pkg/state/state.go`](https://github.com/cabon-tech/zavictl/blob/main/pkg/state/state.go) (State store interface), [`cmd/zavictl/main.go`](https://github.com/cabon-tech/zavictl/blob/main/cmd/zavictl/main.go) (zavictl command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and catalog"]
  node_binary["zavictl command<br/>[main.go]"]
  node_cli["CLI commands"]
  node_service["Service catalog<br/>[service.go]"]
  node_database["Database operations<br/>[database.go]"]
  node_other_domains["Other lifecycle commands"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_engine["Execution engine<br/>[engine.go]"]
  node_workflow["Workflow definitions"]
  node_runner["Step runner<br/>[runner.go]"]
end

subgraph group_governance["Policy and state"]
  node_policy["CEL policy engine<br/>[engine.go]"]
  node_event_bus["Event bus<br/>[event.go]"]
  node_state_api["State store interface<br/>[state.go]"]
  node_sqlite[("SQLite state<br/>[store.go]")]
end

subgraph group_integrations["Provider integrations"]
  node_provider_registry["Provider registry<br/>[registry.go]"]
  node_github_adapter["GitHub adapter<br/>[connection.go]"]
  node_vault_adapter["Vault adapter<br/>[connection.go]"]
  node_prometheus_adapter["Prometheus adapter<br/>[connection.go]"]
  node_other_adapters["Other adapters"]
end

node_engineer(("Engineer"))
node_github_service["GitHub"]
node_vault_service["Vault"]
node_prometheus_service["Prometheus"]
node_cloud_runtime["Cloud and runtime tools"]

node_engineer -->|"runs"| node_binary
node_binary -->|"enters"| node_cli
node_service -->|"reads and writes"| node_state_api
node_database -->|"submits workflow"| node_engine
node_other_domains -.->|"orchestrates operations"| node_engine
node_engine -->|"executes definition"| node_workflow
node_engine -->|"runs steps"| node_runner
node_engine -->|"persists progress"| node_state_api
node_engine -->|"evaluates operation"| node_policy
node_runner -->|"dispatches operation"| node_provider_registry
node_provider_registry -->|"selects provider"| node_github_adapter
node_provider_registry -->|"selects provider"| node_vault_adapter
node_provider_registry -->|"selects provider"| node_prometheus_adapter
node_provider_registry -->|"selects provider"| node_other_adapters
node_github_adapter -->|"calls API"| node_github_service
node_vault_adapter -->|"calls API"| node_vault_service
node_prometheus_adapter -->|"queries API"| node_prometheus_service
node_other_adapters -.->|"integrates tools"| node_cloud_runtime
node_policy -->|"publishes audit event"| node_event_bus
node_event_bus -->|"persists events"| node_sqlite
node_state_api -->|"implemented by"| node_sqlite

click node_binary "https://github.com/cabon-tech/zavictl/blob/main/cmd/zavictl/main.go"
click node_cli "https://github.com/cabon-tech/zavictl/tree/main/internal/cli"
click node_service "https://github.com/cabon-tech/zavictl/blob/main/internal/cli/service.go"
click node_database "https://github.com/cabon-tech/zavictl/blob/main/internal/cli/database.go"
click node_other_domains "https://github.com/cabon-tech/zavictl/tree/main/internal/cli"
click node_engine "https://github.com/cabon-tech/zavictl/blob/main/pkg/execution/engine.go"
click node_workflow "https://github.com/cabon-tech/zavictl/tree/main/pkg/workflow"
click node_runner "https://github.com/cabon-tech/zavictl/blob/main/pkg/execution/runner.go"
click node_provider_registry "https://github.com/cabon-tech/zavictl/blob/main/pkg/provider/registry.go"
click node_github_adapter "https://github.com/cabon-tech/zavictl/blob/main/adapters/github/connection.go"
click node_vault_adapter "https://github.com/cabon-tech/zavictl/blob/main/adapters/vault/connection.go"
click node_prometheus_adapter "https://github.com/cabon-tech/zavictl/blob/main/adapters/prometheus/connection.go"
click node_other_adapters "https://github.com/cabon-tech/zavictl/tree/main/adapters"
click node_policy "https://github.com/cabon-tech/zavictl/blob/main/pkg/policy/engine.go"
click node_event_bus "https://github.com/cabon-tech/zavictl/blob/main/pkg/events/event.go"
click node_state_api "https://github.com/cabon-tech/zavictl/blob/main/pkg/state/state.go"
click node_sqlite "https://github.com/cabon-tech/zavictl/blob/main/pkg/state/sqlite/store.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_binary,node_cli,node_service,node_database,node_other_domains toneBlue
class node_engine,node_workflow,node_runner toneAmber
class node_policy,node_event_bus,node_state_api,node_sqlite toneMint
class node_provider_registry,node_github_adapter,node_vault_adapter,node_prometheus_adapter,node_other_adapters toneRose
class node_engineer,node_github_service,node_vault_service,node_prometheus_service,node_cloud_runtime toneIndigo
```

## Components

### CLI and catalog

- [zavictl command](https://github.com/cabon-tech/zavictl/blob/main/cmd/zavictl/main.go): `cmd/zavictl/main.go`
- [CLI commands](https://github.com/cabon-tech/zavictl/tree/main/internal/cli): `internal/cli`
- [Service catalog](https://github.com/cabon-tech/zavictl/blob/main/internal/cli/service.go): `internal/cli/service.go`
- [Database operations](https://github.com/cabon-tech/zavictl/blob/main/internal/cli/database.go): `internal/cli/database.go`
- [Other lifecycle commands](https://github.com/cabon-tech/zavictl/tree/main/internal/cli): `internal/cli`

### Workflow orchestration

- [Execution engine](https://github.com/cabon-tech/zavictl/blob/main/pkg/execution/engine.go): `pkg/execution/engine.go`
- [Workflow definitions](https://github.com/cabon-tech/zavictl/tree/main/pkg/workflow): `pkg/workflow`
- [Step runner](https://github.com/cabon-tech/zavictl/blob/main/pkg/execution/runner.go): `pkg/execution/runner.go`

### Policy and state

- [CEL policy engine](https://github.com/cabon-tech/zavictl/blob/main/pkg/policy/engine.go): `pkg/policy/engine.go`
- [Event bus](https://github.com/cabon-tech/zavictl/blob/main/pkg/events/event.go): `pkg/events/event.go`
- [State store interface](https://github.com/cabon-tech/zavictl/blob/main/pkg/state/state.go): `pkg/state/state.go`
- [SQLite state](https://github.com/cabon-tech/zavictl/blob/main/pkg/state/sqlite/store.go): `pkg/state/sqlite/store.go`

### Provider integrations

- [Provider registry](https://github.com/cabon-tech/zavictl/blob/main/pkg/provider/registry.go): `pkg/provider/registry.go`
- [GitHub adapter](https://github.com/cabon-tech/zavictl/blob/main/adapters/github/connection.go): `adapters/github/connection.go`
- [Vault adapter](https://github.com/cabon-tech/zavictl/blob/main/adapters/vault/connection.go): `adapters/vault/connection.go`
- [Prometheus adapter](https://github.com/cabon-tech/zavictl/blob/main/adapters/prometheus/connection.go): `adapters/prometheus/connection.go`
- [Other adapters](https://github.com/cabon-tech/zavictl/tree/main/adapters): `adapters`

### Other components

- **Engineer**
- **GitHub**
- **Vault**
- **Prometheus**
- **Cloud and runtime tools**

## Connections

- Engineer → zavictl command: runs
- zavictl command → CLI commands: enters
- Service catalog → State store interface: reads and writes
- Database operations → Execution engine: submits workflow
- Other lifecycle commands → Execution engine: orchestrates operations
- Execution engine → Workflow definitions: executes definition
- Execution engine → Step runner: runs steps
- Execution engine → State store interface: persists progress
- Execution engine → CEL policy engine: evaluates operation
- Step runner → Provider registry: dispatches operation
- Provider registry → GitHub adapter: selects provider
- Provider registry → Vault adapter: selects provider
- Provider registry → Prometheus adapter: selects provider
- Provider registry → Other adapters: selects provider
- GitHub adapter → GitHub: calls API
- Vault adapter → Vault: calls API
- Prometheus adapter → Prometheus: queries API
- Other adapters → Cloud and runtime tools: integrates tools
- CEL policy engine → Event bus: publishes audit event
- Event bus → SQLite state: persists events
- State store interface → SQLite state: implemented by