Skip to main content

​
System Architecture

Dorgu is a two-component system: a CLI that analyzes applications and generates Kubernetes manifests, and an Operator that validates deployments and manages cluster state. They communicate through Kubernetes CRDs and a WebSocket connection.

​
System Diagram

​
Component Overview

ComponentRepositoryDescription
Dorgu CLIdorgu-ai/dorguCLI for manifest generation, persona management, cluster interaction
Dorgu Operatordorgu-ai/dorgu-operatorK8s operator for deployment validation, cluster discovery, persona management
ApplicationPersona CRDdorgu.io/v1App identity, requirements, and operational context (namespaced)
ClusterPersona CRDdorgu.io/v1Cluster identity and state (cluster-scoped singleton)

​
Design Principles

​
Don’t replace, integrate

Dorgu generates standard Kubernetes, ArgoCD, and GitHub Actions manifests that work with your existing tooling. It does not introduce a proprietary deployment format or require you to change your workflow. The generated YAML is plain, readable, and fully customizable.

​
Operator is read-only

The operator NEVER creates or modifies workload resources (Deployments, Services). It only reads cluster state, validates deployments against persona expectations, and updates Persona CRD status fields. This means Dorgu cannot accidentally break your running applications.

​
Source-of-truth hierarchy

The CLI and GitOps pipelines own the spec fields of Persona CRDs, representing desired intent. The Operator owns the status fields, representing observed reality and learned patterns. This separation ensures a clean contract between what you declare and what the cluster reports.

​
Repository Structure

The CLI follows a standard Go project layout: 
dorgu/
├── cmd/dorgu/main.go
├── internal/
│   ├── analyzer/      # Dockerfile, Compose, Code analysis
│   ├── cli/           # Cobra commands
│   ├── config/        # Config loading and merging
│   ├── generator/     # Manifest generators + validation
│   ├── llm/           # LLM provider interface + implementations
│   ├── output/        # File writer and terminal formatter
│   ├── setup/         # Cluster setup wizard
│   ├── types/         # Shared AppAnalysis type
│   └── ws/            # WebSocket client
├── testdata/          # Test fixtures
└── testapps/          # Sample applications
All business logic lives under internal/ to enforce Go’s package boundary. The cmd/dorgu/main.go entry point is intentionally thin — it only wires together the CLI commands.