# talyguryn/konta architecture

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

- Interactive diagram: https://gitdiagram.com/talyguryn/konta
- Repository: https://github.com/talyguryn/konta

## Overview

Konta is a single-server GitOps tool for Docker Compose. A user bootstraps a repository and configuration, then runs or enables Konta; its runtime fetches repository changes, reconciles Compose projects, and records deployment state. Reconciliation also supports managed-service labels, rolling deployments, health checks, drift recovery, and lifecycle hooks. The README documents these capabilities, but the supplied excerpts do not expose every implementation detail, so uncertain connections are omitted.

Main entry points: [`internal/cmd/cmd.go`](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd.go) (CLI commands), [`internal/cmd/cmd_fetch.go`](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_fetch.go) (Fetch workflow), [`internal/reconcile/reconcile.go`](https://github.com/talyguryn/konta/blob/main/internal/reconcile/reconcile.go) (Compose reconciliation), [`internal/state/state.go`](https://github.com/talyguryn/konta/blob/main/internal/state/state.go) (Deployment state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_entrypoint["CLI entrypoint<br/>[main.go]"]
  node_app["Command router<br/>[app.go]"]
  node_commands["CLI commands<br/>[cmd.go]"]
  node_bootstrap["Bootstrap<br/>[cmd_bootstrap.go]"]
  node_daemon["Daemon control<br/>[daemon.go]"]
end

subgraph group_sync["Repository and config"]
  node_config["Configuration<br/>[config.go]"]
  node_repo_sync["Git fetch and diff<br/>[git.go]"]
  node_native_git["Native Git fallback<br/>[git_native.go]"]
  node_fetch["Fetch workflow<br/>[cmd_fetch.go]"]
end

subgraph group_deploy["Deployment runtime"]
  node_reconcile["Compose reconciliation<br/>[reconcile.go]"]
  node_dockerutil["Docker command helper<br/>[dockerutil.go]"]
  node_state[("Deployment state<br/>[state.go]")]
  node_hooks["Lifecycle hooks<br/>[hooks.go]"]
end

subgraph group_operations["Operations and integrations"]
  node_github["GitHub deployment status<br/>[githubdeploy.go]"]
  node_gc["Container garbage collection<br/>[cmd_gc.go]"]
  node_status["Status and projects<br/>[cmd_status.go]"]
  node_updates["Konta updates<br/>[cmd_update.go]"]
  node_service["Platform service manager<br/>[manager.go]"]
end

node_operator(("Server operator"))
node_docker["Docker Compose runtime"]

node_operator -->|"runs"| node_entrypoint
node_entrypoint -->|"starts"| node_app
node_app -->|"dispatches"| node_commands
node_commands -->|"invokes"| node_bootstrap
node_commands -.->|"runs"| node_fetch
node_commands -.->|"manages"| node_daemon
node_bootstrap -->|"saves"| node_config
node_bootstrap -->|"initializes"| node_state
node_fetch -->|"fetches"| node_repo_sync
node_fetch -->|"creates reconciler"| node_reconcile
node_fetch -->|"loads state"| node_state
node_reconcile -->|"creates client"| node_dockerutil
node_dockerutil -.->|"runs commands"| node_docker
node_reconcile -->|"persists networks"| node_state
node_reconcile -->|"runs drift hooks"| node_hooks
node_repo_sync -->|"fallback diff"| node_native_git
node_commands -.->|"reports deployment"| node_github
node_commands -->|"runs deploy hooks"| node_hooks
node_commands -.->|"dispatches"| node_gc
node_commands -.->|"dispatches"| node_status
node_commands -->|"checks updates"| node_updates
node_daemon -->|"controls service"| node_service
node_status -->|"reads state"| node_state
node_updates -->|"runs post-update"| node_hooks

click node_entrypoint "https://github.com/talyguryn/konta/blob/main/cmd/konta/main.go"
click node_app "https://github.com/talyguryn/konta/blob/main/internal/app/app.go"
click node_commands "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd.go"
click node_bootstrap "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_bootstrap.go"
click node_daemon "https://github.com/talyguryn/konta/blob/main/internal/cmd/daemon.go"
click node_config "https://github.com/talyguryn/konta/blob/main/internal/config/config.go"
click node_repo_sync "https://github.com/talyguryn/konta/blob/main/internal/git/git.go"
click node_native_git "https://github.com/talyguryn/konta/blob/main/internal/git/git_native.go"
click node_fetch "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_fetch.go"
click node_reconcile "https://github.com/talyguryn/konta/blob/main/internal/reconcile/reconcile.go"
click node_dockerutil "https://github.com/talyguryn/konta/blob/main/internal/dockerutil/dockerutil.go"
click node_state "https://github.com/talyguryn/konta/blob/main/internal/state/state.go"
click node_hooks "https://github.com/talyguryn/konta/blob/main/internal/hooks/hooks.go"
click node_github "https://github.com/talyguryn/konta/blob/main/internal/githubdeploy/githubdeploy.go"
click node_gc "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_gc.go"
click node_status "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_status.go"
click node_updates "https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_update.go"
click node_service "https://github.com/talyguryn/konta/blob/main/internal/platform/service/manager.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_entrypoint,node_app,node_commands,node_bootstrap,node_daemon toneBlue
class node_config,node_repo_sync,node_native_git,node_fetch toneAmber
class node_reconcile,node_dockerutil,node_state,node_hooks,node_operator toneMint
class node_github,node_gc,node_status,node_updates,node_service toneRose
class node_docker toneIndigo
```

## Components

### CLI and setup

- [CLI entrypoint](https://github.com/talyguryn/konta/blob/main/cmd/konta/main.go): `cmd/konta/main.go`
- [Command router](https://github.com/talyguryn/konta/blob/main/internal/app/app.go): `internal/app/app.go`
- [CLI commands](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd.go): `internal/cmd/cmd.go`
- [Bootstrap](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_bootstrap.go): `internal/cmd/cmd_bootstrap.go`
- [Daemon control](https://github.com/talyguryn/konta/blob/main/internal/cmd/daemon.go): `internal/cmd/daemon.go`

### Repository and config

- [Configuration](https://github.com/talyguryn/konta/blob/main/internal/config/config.go): `internal/config/config.go`
- [Git fetch and diff](https://github.com/talyguryn/konta/blob/main/internal/git/git.go): `internal/git/git.go`
- [Native Git fallback](https://github.com/talyguryn/konta/blob/main/internal/git/git_native.go): `internal/git/git_native.go`
- [Fetch workflow](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_fetch.go): `internal/cmd/cmd_fetch.go`

### Deployment runtime

- [Compose reconciliation](https://github.com/talyguryn/konta/blob/main/internal/reconcile/reconcile.go): `internal/reconcile/reconcile.go`
- [Docker command helper](https://github.com/talyguryn/konta/blob/main/internal/dockerutil/dockerutil.go): `internal/dockerutil/dockerutil.go`
- [Deployment state](https://github.com/talyguryn/konta/blob/main/internal/state/state.go): `internal/state/state.go`
- [Lifecycle hooks](https://github.com/talyguryn/konta/blob/main/internal/hooks/hooks.go): `internal/hooks/hooks.go`

### Operations and integrations

- [GitHub deployment status](https://github.com/talyguryn/konta/blob/main/internal/githubdeploy/githubdeploy.go): `internal/githubdeploy/githubdeploy.go`
- [Container garbage collection](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_gc.go): `internal/cmd/cmd_gc.go`
- [Status and projects](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_status.go): `internal/cmd/cmd_status.go`
- [Konta updates](https://github.com/talyguryn/konta/blob/main/internal/cmd/cmd_update.go): `internal/cmd/cmd_update.go`
- [Platform service manager](https://github.com/talyguryn/konta/blob/main/internal/platform/service/manager.go): `internal/platform/service/manager.go`

### Other components

- **Server operator**
- **Docker Compose runtime**

## Connections

- Server operator → CLI entrypoint: runs (evidence: `README.md`)
- CLI entrypoint → Command router: starts (evidence: `cmd/konta/main.go`)
- Command router → CLI commands: dispatches (evidence: `internal/app/app.go`)
- CLI commands → Bootstrap: invokes (evidence: `internal/cmd/cmd.go`)
- CLI commands → Fetch workflow: runs
- CLI commands → Daemon control: manages
- Bootstrap → Configuration: saves (evidence: `internal/cmd/cmd_bootstrap.go`)
- Bootstrap → Deployment state: initializes (evidence: `internal/cmd/cmd_bootstrap.go`)
- Fetch workflow → Git fetch and diff: fetches (evidence: `internal/cmd/cmd_fetch.go`)
- Fetch workflow → Compose reconciliation: creates reconciler (evidence: `internal/cmd/cmd_fetch.go`)
- Fetch workflow → Deployment state: loads state (evidence: `internal/cmd/cmd_fetch.go`)
- Compose reconciliation → Docker command helper: creates client (evidence: `internal/reconcile/reconcile.go`)
- Docker command helper → Docker Compose runtime: runs commands
- Compose reconciliation → Deployment state: persists networks (evidence: `internal/reconcile/reconcile.go`)
- Compose reconciliation → Lifecycle hooks: runs drift hooks (evidence: `internal/reconcile/reconcile.go`)
- Git fetch and diff → Native Git fallback: fallback diff (evidence: `internal/git/git.go`)
- CLI commands → GitHub deployment status: reports deployment
- CLI commands → Lifecycle hooks: runs deploy hooks (evidence: `internal/cmd/cmd.go`)
- CLI commands → Container garbage collection: dispatches
- CLI commands → Status and projects: dispatches
- CLI commands → Konta updates: checks updates (evidence: `internal/cmd/cmd.go`)
- Daemon control → Platform service manager: controls service (evidence: `internal/cmd/daemon.go`)
- Status and projects → Deployment state: reads state (evidence: `internal/cmd/cmd_status.go`)
- Konta updates → Lifecycle hooks: runs post-update (evidence: `internal/cmd/cmd_update.go`)
