# sdslabs/shogun-cd architecture

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

- Interactive diagram: https://gitdiagram.com/sdslabs/shogun-cd
- Repository: https://github.com/sdslabs/shogun-cd

## Overview

Shogun-CD is a self-hosted Git-based continuous-delivery service. Operators define YAML pipelines and targets in a manifest repository; repository changes, CI webhooks, or UI/API requests trigger ordered deployment steps. The backend indexes definitions, executes steps against remote hosts, and records run history, while the UI exposes pipeline, run, target, and webhook workflows. SSH/SFTP deployment, YAML mutation, encrypted secrets, and PostgreSQL-backed history are documented capabilities; some implementation links rely on the README because their source was not excerpted.

Main entry points: [`internal/store/store.go`](https://github.com/sdslabs/shogun-cd/blob/develop/internal/store/store.go) (Persistence), [`internal/pipeline/engine.go`](https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/engine.go) (Pipeline Engine), [`internal/orchestrator/orchestrator.go`](https://github.com/sdslabs/shogun-cd/blob/develop/internal/orchestrator/orchestrator.go) (Orchestrator), [`internal/pipeline/steps/step.go`](https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/steps/step.go) (Pipeline Steps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User and API"]
  node_ui["Web UI<br/>[app.tsx]"]
  node_api["HTTP API<br/>[server.go]"]
  node_routes["API Routes<br/>[routes.go]"]
  node_pipeline_api["Pipeline Controller<br/>[pipelines.go]"]
  node_webhook_api["Webhook Controller<br/>[webhooks.go]"]
end

subgraph group_catalog["Repository and Definitions"]
  node_indexer["Definition Indexer<br/>[indexer.go]"]
  node_git_service["Git Service<br/>[service.go]"]
  node_target_loader["Target Loader<br/>[loader.go]"]
end

subgraph group_execution["Pipeline Execution"]
  node_webhook_svc["Webhook Service<br/>[service.go]"]
  node_orchestrator["Orchestrator<br/>[orchestrator.go]"]
  node_pipeline_service["Pipeline Service<br/>[service.go]"]
  node_pipeline_engine["Pipeline Engine<br/>[engine.go]"]
  node_step_impl["Pipeline Steps<br/>[step.go]"]
end

subgraph group_integrations["External Services"]
  node_ssh["SSH/SFTP Client<br/>[sshmanager.go]"]
  node_remote{{"Deployment Hosts"}}
  node_postgres[("PostgreSQL")]
  node_manifest_repo{{"Manifest Repository"}}
end

subgraph group_state["Identity and State"]
  node_secret_service["Secret Service"]
  node_encryption["Encryption<br/>[service.go]"]
  node_users["User Service<br/>[service.go]"]
  node_store["Persistence<br/>[store.go]"]
end

node_operator(("Operator"))
node_ci(("CI System"))

node_operator -->|"uses"| node_ui
node_ui -.->|"requests"| node_api
node_api -->|"registers"| node_routes
node_routes -->|"routes runs"| node_pipeline_api
node_routes -->|"routes hooks"| node_webhook_api
node_pipeline_api -->|"starts run"| node_orchestrator
node_ci -->|"sends hook"| node_webhook_api
node_webhook_api -->|"resolves hook"| node_webhook_svc
node_webhook_svc -->|"triggers run"| node_orchestrator
node_manifest_repo -->|"hosts definitions"| node_git_service
node_orchestrator -->|"coordinates Git"| node_git_service
node_orchestrator -->|"runs pipelines"| node_pipeline_service
node_orchestrator -->|"loads targets"| node_target_loader
node_git_service -.->|"provides repository"| node_indexer
node_indexer -->|"indexes YAML"| node_manifest_repo
node_pipeline_service -->|"executes pipeline"| node_pipeline_engine
node_pipeline_engine -->|"executes steps"| node_step_impl
node_pipeline_engine -->|"creates client"| node_ssh
node_pipeline_engine -->|"records run steps"| node_store
node_pipeline_engine -->|"deploys remotely"| node_remote
node_ssh -->|"connects SSH/SFTP"| node_remote
node_step_impl -->|"syncs and executes"| node_remote
node_step_impl -->|"pushes mutations"| node_git_service
node_step_impl -.->|"accesses secrets"| node_secret_service
node_secret_service -.->|"encrypts secrets"| node_encryption
node_secret_service -.->|"persists secrets"| node_store
node_users -->|"reads and writes users"| node_store
node_store -->|"persists data"| node_postgres
node_pipeline_api -->|"fetches run history"| node_store
node_webhook_svc -.->|"stores hooks"| node_store

click node_ui "https://github.com/sdslabs/shogun-cd/blob/develop/ui/src/app/app.tsx"
click node_api "https://github.com/sdslabs/shogun-cd/blob/develop/api/http/server.go"
click node_routes "https://github.com/sdslabs/shogun-cd/blob/develop/api/http/routes.go"
click node_pipeline_api "https://github.com/sdslabs/shogun-cd/blob/develop/api/http/controllers/pipelines.go"
click node_webhook_api "https://github.com/sdslabs/shogun-cd/blob/develop/api/http/controllers/webhooks.go"
click node_webhook_svc "https://github.com/sdslabs/shogun-cd/blob/develop/internal/webhooks/service.go"
click node_orchestrator "https://github.com/sdslabs/shogun-cd/blob/develop/internal/orchestrator/orchestrator.go"
click node_indexer "https://github.com/sdslabs/shogun-cd/blob/develop/internal/orchestrator/indexer.go"
click node_git_service "https://github.com/sdslabs/shogun-cd/blob/develop/internal/git/service.go"
click node_pipeline_service "https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/service.go"
click node_pipeline_engine "https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/engine.go"
click node_step_impl "https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/steps/step.go"
click node_target_loader "https://github.com/sdslabs/shogun-cd/blob/develop/internal/target/loader.go"
click node_ssh "https://github.com/sdslabs/shogun-cd/blob/develop/internal/sshclient/sshmanager.go"
click node_secret_service "https://github.com/sdslabs/shogun-cd/tree/develop/internal/secrets"
click node_encryption "https://github.com/sdslabs/shogun-cd/blob/develop/internal/encryption/service.go"
click node_users "https://github.com/sdslabs/shogun-cd/blob/develop/internal/users/service.go"
click node_store "https://github.com/sdslabs/shogun-cd/blob/develop/internal/store/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_ui,node_api,node_routes,node_pipeline_api,node_webhook_api toneBlue
class node_indexer,node_git_service,node_target_loader toneAmber
class node_webhook_svc,node_orchestrator,node_pipeline_service,node_pipeline_engine,node_step_impl toneMint
class node_ssh,node_remote,node_postgres,node_manifest_repo toneRose
class node_secret_service,node_encryption,node_users,node_store,node_operator,node_ci toneIndigo
```

## Components

### User and API

- [Web UI](https://github.com/sdslabs/shogun-cd/blob/develop/ui/src/app/app.tsx): `ui/src/app/app.tsx`
- [HTTP API](https://github.com/sdslabs/shogun-cd/blob/develop/api/http/server.go): `api/http/server.go`
- [API Routes](https://github.com/sdslabs/shogun-cd/blob/develop/api/http/routes.go): `api/http/routes.go`
- [Pipeline Controller](https://github.com/sdslabs/shogun-cd/blob/develop/api/http/controllers/pipelines.go): `api/http/controllers/pipelines.go`
- [Webhook Controller](https://github.com/sdslabs/shogun-cd/blob/develop/api/http/controllers/webhooks.go): `api/http/controllers/webhooks.go`

### Repository and Definitions

- [Definition Indexer](https://github.com/sdslabs/shogun-cd/blob/develop/internal/orchestrator/indexer.go): `internal/orchestrator/indexer.go`
- [Git Service](https://github.com/sdslabs/shogun-cd/blob/develop/internal/git/service.go): `internal/git/service.go`
- [Target Loader](https://github.com/sdslabs/shogun-cd/blob/develop/internal/target/loader.go): `internal/target/loader.go`

### Pipeline Execution

- [Webhook Service](https://github.com/sdslabs/shogun-cd/blob/develop/internal/webhooks/service.go): `internal/webhooks/service.go`
- [Orchestrator](https://github.com/sdslabs/shogun-cd/blob/develop/internal/orchestrator/orchestrator.go): `internal/orchestrator/orchestrator.go`
- [Pipeline Service](https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/service.go): `internal/pipeline/service.go`
- [Pipeline Engine](https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/engine.go): `internal/pipeline/engine.go`
- [Pipeline Steps](https://github.com/sdslabs/shogun-cd/blob/develop/internal/pipeline/steps/step.go): `internal/pipeline/steps/step.go`

### External Services

- [SSH/SFTP Client](https://github.com/sdslabs/shogun-cd/blob/develop/internal/sshclient/sshmanager.go): `internal/sshclient/sshmanager.go`
- **Deployment Hosts**
- **PostgreSQL**
- **Manifest Repository**

### Identity and State

- [Secret Service](https://github.com/sdslabs/shogun-cd/tree/develop/internal/secrets): `internal/secrets`
- [Encryption](https://github.com/sdslabs/shogun-cd/blob/develop/internal/encryption/service.go): `internal/encryption/service.go`
- [User Service](https://github.com/sdslabs/shogun-cd/blob/develop/internal/users/service.go): `internal/users/service.go`
- [Persistence](https://github.com/sdslabs/shogun-cd/blob/develop/internal/store/store.go): `internal/store/store.go`

### Other components

- **Operator**
- **CI System**

## Connections

- Operator → Web UI: uses
- Web UI → HTTP API: requests
- HTTP API → API Routes: registers (evidence: `api/http/server.go`)
- API Routes → Pipeline Controller: routes runs (evidence: `api/http/routes.go`)
- API Routes → Webhook Controller: routes hooks (evidence: `api/http/routes.go`)
- Pipeline Controller → Orchestrator: starts run (evidence: `api/http/controllers/pipelines.go`)
- CI System → Webhook Controller: sends hook
- Webhook Controller → Webhook Service: resolves hook (evidence: `api/http/controllers/webhooks.go`)
- Webhook Service → Orchestrator: triggers run (evidence: `internal/webhooks/service.go`)
- Manifest Repository → Git Service: hosts definitions
- Orchestrator → Git Service: coordinates Git (evidence: `internal/orchestrator/orchestrator.go`)
- Orchestrator → Pipeline Service: runs pipelines (evidence: `internal/orchestrator/orchestrator.go`)
- Orchestrator → Target Loader: loads targets (evidence: `internal/orchestrator/orchestrator.go`)
- Git Service → Definition Indexer: provides repository
- Definition Indexer → Manifest Repository: indexes YAML
- Pipeline Service → Pipeline Engine: executes pipeline (evidence: `internal/pipeline/engine.go`)
- Pipeline Engine → Pipeline Steps: executes steps (evidence: `internal/pipeline/engine.go`)
- Pipeline Engine → SSH/SFTP Client: creates client (evidence: `internal/pipeline/engine.go`)
- Pipeline Engine → Persistence: records run steps (evidence: `internal/pipeline/engine.go`)
- Pipeline Engine → Deployment Hosts: deploys remotely
- SSH/SFTP Client → Deployment Hosts: connects SSH/SFTP
- Pipeline Steps → Deployment Hosts: syncs and executes
- Pipeline Steps → Git Service: pushes mutations
- Pipeline Steps → Secret Service: accesses secrets
- Secret Service → Encryption: encrypts secrets
- Secret Service → Persistence: persists secrets
- User Service → Persistence: reads and writes users (evidence: `internal/users/service.go`)
- Persistence → PostgreSQL: persists data
- Pipeline Controller → Persistence: fetches run history (evidence: `api/http/controllers/pipelines.go`)
- Webhook Service → Persistence: stores hooks
