# kitops-ml/kitops architecture

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

- Interactive diagram: https://gitdiagram.com/kitops-ml/kitops
- Repository: https://github.com/kitops-ml/kitops

## Overview

KitOps is a CLI for defining, packaging, versioning, and exchanging AI/ML projects as OCI-compatible ModelKits or ModelPacks. The main workflow is to initialize or import a project, pack its Kitfile-defined assets, then push or pull the artifact through a registry and inspect or unpack it locally. Other documented stages include listing, tagging, diffing, authentication, and selective extraction. The tree also includes a local LLM development harness and browser chat UI. Command and storage wiring is inferred only where README capabilities and sampled code support it; unsampled subsystem links are omitted.

Main entry points: [`cmd/root.go`](https://github.com/kitops-ml/kitops/blob/main/cmd/root.go) (Command routing), [`pkg/lib/repo/local/storage.go`](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/local/storage.go) (Local OCI store), [`pkg/cmd/pack/pack.go`](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/pack/pack.go) (Pack artifact), [`pkg/lib/repo/remote/repository.go`](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/remote/repository.go) (Remote repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_entry["CLI entry<br/>[main.go]"]
  node_commands["Command routing<br/>[root.go]"]
  node_initialize["Initialize project<br/>[cmd.go]"]
  node_import["Import assets<br/>[cmd.go]"]
end

subgraph group_artifact["Artifact lifecycle"]
  node_pack["Pack artifact<br/>[pack.go]"]
  node_kitfile["Kitfile model<br/>[kitfile.go]"]
  node_layering["OCI layers<br/>[local-storage.go]"]
  node_unpack["Unpack layers<br/>[cmd.go]"]
  node_inspect["Inspect artifact<br/>[inspect.go]"]
  node_diff["Compare artifacts<br/>[diff.go]"]
  node_skill["Skill support<br/>[install.go]"]
end

subgraph group_storage["Storage and registries"]
  node_local[("Local OCI store<br/>[storage.go]")]
  node_localrepo[("Local repository<br/>[repository.go]")]
  node_push["Push artifact<br/>[push.go]"]
  node_pull["Pull artifact<br/>[pull.go]"]
  node_remote["Remote repository<br/>[repository.go]"]
end

subgraph group_dev["LLM development"]
  node_devcmd["Dev command<br/>[dev.go]"]
  node_harness["LLM harness<br/>[llm-harness.go]"]
  node_chat["Chat interface<br/>[App.vue]"]
  node_completion["Completion client<br/>[completion.ts]"]
end

node_user(("CLI user"))
node_registry[("OCI registry")]
node_hf["Hugging Face"]
node_llama["llama.cpp server"]

node_user -->|"runs CLI"| node_entry
node_entry -->|"executes"| node_commands
node_commands -->|"dispatches"| node_initialize
node_commands -->|"dispatches"| node_import
node_commands -->|"dispatches"| node_pack
node_commands -->|"dispatches"| node_unpack
node_commands -->|"dispatches"| node_inspect
node_commands -->|"dispatches"| node_diff
node_commands -->|"dispatches"| node_push
node_commands -->|"dispatches"| node_pull
node_commands -->|"dispatches"| node_devcmd
node_initialize -->|"generates"| node_kitfile
node_import -.->|"imports from"| node_hf
node_import -->|"filters metadata"| node_kitfile
node_pack -->|"reads definition"| node_kitfile
node_pack -->|"saves layers"| node_layering
node_layering -->|"writes blobs"| node_local
node_pack -->|"records manifest"| node_localrepo
node_unpack -->|"reads layers"| node_local
node_inspect -->|"reads artifact"| node_local
node_diff -->|"compares artifacts"| node_local
node_commands -->|"supports skills"| node_skill
node_push -->|"reads artifact"| node_local
node_push -->|"uploads content"| node_remote
node_remote -->|"sends OCI requests"| node_registry
node_pull -->|"fetches artifact"| node_remote
node_remote -->|"reads OCI content"| node_registry
node_pull -->|"stores content"| node_local
node_devcmd -->|"manages server"| node_harness
node_harness -->|"starts server"| node_llama
node_chat -->|"requests completion"| node_completion
node_completion -->|"calls API"| node_llama

click node_entry "https://github.com/kitops-ml/kitops/blob/main/main.go"
click node_commands "https://github.com/kitops-ml/kitops/blob/main/cmd/root.go"
click node_initialize "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/kitinit/cmd.go"
click node_import "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/kitimport/cmd.go"
click node_pack "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/pack/pack.go"
click node_kitfile "https://github.com/kitops-ml/kitops/blob/main/pkg/artifact/kitfile.go"
click node_layering "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/filesystem/local-storage.go"
click node_unpack "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/unpack/cmd.go"
click node_inspect "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/inspect/inspect.go"
click node_diff "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/diff/diff.go"
click node_skill "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/skill/install.go"
click node_local "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/local/storage.go"
click node_localrepo "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/local/repository.go"
click node_push "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/push/push.go"
click node_pull "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/pull/pull.go"
click node_remote "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/remote/repository.go"
click node_devcmd "https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/dev/dev.go"
click node_harness "https://github.com/kitops-ml/kitops/blob/main/pkg/lib/harness/llm-harness.go"
click node_chat "https://github.com/kitops-ml/kitops/blob/main/frontend/dev-mode/src/App.vue"
click node_completion "https://github.com/kitops-ml/kitops/blob/main/frontend/dev-mode/src/services/completion.ts"

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_entry,node_commands,node_initialize,node_import,node_user toneBlue
class node_pack,node_kitfile,node_layering,node_unpack,node_inspect,node_diff,node_skill,node_registry toneAmber
class node_local,node_localrepo,node_push,node_pull,node_remote,node_llama toneMint
class node_devcmd,node_harness,node_chat,node_completion toneRose
class node_hf toneIndigo
```

## Components

### CLI workflows

- [CLI entry](https://github.com/kitops-ml/kitops/blob/main/main.go): `main.go`
- [Command routing](https://github.com/kitops-ml/kitops/blob/main/cmd/root.go): `cmd/root.go`
- [Initialize project](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/kitinit/cmd.go): `pkg/cmd/kitinit/cmd.go`
- [Import assets](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/kitimport/cmd.go): `pkg/cmd/kitimport/cmd.go`

### Artifact lifecycle

- [Pack artifact](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/pack/pack.go): `pkg/cmd/pack/pack.go`
- [Kitfile model](https://github.com/kitops-ml/kitops/blob/main/pkg/artifact/kitfile.go): `pkg/artifact/kitfile.go`
- [OCI layers](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/filesystem/local-storage.go): `pkg/lib/filesystem/local-storage.go`
- [Unpack layers](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/unpack/cmd.go): `pkg/cmd/unpack/cmd.go`
- [Inspect artifact](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/inspect/inspect.go): `pkg/cmd/inspect/inspect.go`
- [Compare artifacts](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/diff/diff.go): `pkg/cmd/diff/diff.go`
- [Skill support](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/skill/install.go): `pkg/lib/skill/install.go`

### Storage and registries

- [Local OCI store](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/local/storage.go): `pkg/lib/repo/local/storage.go`
- [Local repository](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/local/repository.go): `pkg/lib/repo/local/repository.go`
- [Push artifact](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/push/push.go): `pkg/cmd/push/push.go`
- [Pull artifact](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/pull/pull.go): `pkg/cmd/pull/pull.go`
- [Remote repository](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/repo/remote/repository.go): `pkg/lib/repo/remote/repository.go`

### LLM development

- [Dev command](https://github.com/kitops-ml/kitops/blob/main/pkg/cmd/dev/dev.go): `pkg/cmd/dev/dev.go`
- [LLM harness](https://github.com/kitops-ml/kitops/blob/main/pkg/lib/harness/llm-harness.go): `pkg/lib/harness/llm-harness.go`
- [Chat interface](https://github.com/kitops-ml/kitops/blob/main/frontend/dev-mode/src/App.vue): `frontend/dev-mode/src/App.vue`
- [Completion client](https://github.com/kitops-ml/kitops/blob/main/frontend/dev-mode/src/services/completion.ts): `frontend/dev-mode/src/services/completion.ts`

### Other components

- **CLI user**
- **OCI registry**
- **Hugging Face**
- **llama.cpp server**

## Connections

- CLI user → CLI entry: runs CLI
- CLI entry → Command routing: executes
- Command routing → Initialize project: dispatches
- Command routing → Import assets: dispatches
- Command routing → Pack artifact: dispatches
- Command routing → Unpack layers: dispatches
- Command routing → Inspect artifact: dispatches
- Command routing → Compare artifacts: dispatches
- Command routing → Push artifact: dispatches
- Command routing → Pull artifact: dispatches
- Command routing → Dev command: dispatches
- Initialize project → Kitfile model: generates
- Import assets → Hugging Face: imports from
- Import assets → Kitfile model: filters metadata
- Pack artifact → Kitfile model: reads definition
- Pack artifact → OCI layers: saves layers
- OCI layers → Local OCI store: writes blobs
- Pack artifact → Local repository: records manifest
- Unpack layers → Local OCI store: reads layers
- Inspect artifact → Local OCI store: reads artifact
- Compare artifacts → Local OCI store: compares artifacts
- Command routing → Skill support: supports skills
- Push artifact → Local OCI store: reads artifact
- Push artifact → Remote repository: uploads content
- Remote repository → OCI registry: sends OCI requests
- Pull artifact → Remote repository: fetches artifact
- Remote repository → OCI registry: reads OCI content
- Pull artifact → Local OCI store: stores content
- Dev command → LLM harness: manages server
- LLM harness → llama.cpp server: starts server
- Chat interface → Completion client: requests completion
- Completion client → llama.cpp server: calls API