# rapidfort/kimia architecture

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

- Interactive diagram: https://gitdiagram.com/rapidfort/kimia
- Repository: https://github.com/rapidfort/kimia

## Overview

Kimia is a Kubernetes-oriented, rootless OCI image builder. Its main workflow parses build options, prepares a local or Git context, configures registry authentication, invokes BuildKit or Buildah to build an image, and optionally pushes or exports the result. Preflight checks support safe rootless operation; documented capabilities also include caching, reproducible builds, and BuildKit attestations/signing. Several implementation details are unsampled, so those features are represented only where the tree or README supports them.

Main entry points: [`src/cmd/kimia/main.go`](https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/main.go) (CLI entry), [`src/internal/build/builder.go`](https://github.com/rapidfort/kimia/blob/main/src/internal/build/builder.go) (Builder execution), [`src/internal/preflight/validator.go`](https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/validator.go) (Runtime validation), [`src/internal/build`](https://github.com/rapidfort/kimia/tree/main/src/internal/build) (Attestation and signing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and orchestration"]
  node_entry["CLI entry<br/>[main.go]"]
  node_args["Argument parsing<br/>[args.go]"]
  node_config["Build options<br/>[config.go]"]
  node_validation["Input validation<br/>[validation.go]"]
end

subgraph group_build["Image build"]
  node_context["Build context<br/>[context.go]"]
  node_builder["Builder execution<br/>[builder.go]"]
  node_cache["Build caching"]
  node_repro["Reproducible builds"]
  node_output["Image output<br/>[push.go]"]
end

subgraph group_security["Rootless readiness"]
  node_preflight["Environment checks"]
  node_validator["Runtime validation<br/>[validator.go]"]
  node_userns["User namespaces<br/>[userns.go]"]
  node_storage["Storage checks<br/>[storage.go]"]
end

subgraph group_integrations["Registries and supply chain"]
  node_auth["Registry authentication<br/>[docker.go]"]
  node_registry["Cloud registry credentials<br/>[registry.go]"]
  node_attest["Attestation and signing"]
end

node_user(("Build operator"))
node_git(("Git repository"))
node_engine["BuildKit or Buildah"]
node_registry_service[("OCI registry")]
node_cosign["Cosign"]

node_user -->|"runs"| node_entry
node_entry -->|"parses flags"| node_args
node_args -->|"sets options"| node_config
node_entry -->|"checks environment"| node_preflight
node_preflight -->|"validates runtime"| node_validator
node_validator -->|"checks isolation"| node_userns
node_validator -->|"checks storage"| node_storage
node_entry -->|"validates inputs"| node_validation
node_entry -->|"prepares context"| node_context
node_context -.->|"fetches source"| node_git
node_entry -->|"sets up credentials"| node_auth
node_auth -.->|"refreshes cloud credentials"| node_registry
node_entry -->|"executes build"| node_builder
node_builder -->|"uses context"| node_context
node_builder -->|"invokes builder"| node_engine
node_builder -->|"uses cache options"| node_cache
node_builder -->|"applies build settings"| node_repro
node_entry -->|"pushes or exports"| node_output
node_output -->|"pushes image"| node_registry_service
node_builder -.->|"configures attestations"| node_attest
node_attest -.->|"signs image"| node_cosign
node_attest -.->|"publishes attestations"| node_registry_service

click node_entry "https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/main.go"
click node_args "https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/args.go"
click node_config "https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/config.go"
click node_validation "https://github.com/rapidfort/kimia/blob/main/src/internal/validation/validation.go"
click node_context "https://github.com/rapidfort/kimia/blob/main/src/internal/build/context.go"
click node_builder "https://github.com/rapidfort/kimia/blob/main/src/internal/build/builder.go"
click node_cache "https://github.com/rapidfort/kimia/tree/main/src/internal/build"
click node_repro "https://github.com/rapidfort/kimia/tree/main/src/internal/build"
click node_output "https://github.com/rapidfort/kimia/blob/main/src/internal/build/push.go"
click node_preflight "https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/check_environment.go"
click node_validator "https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/validator.go"
click node_userns "https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/userns.go"
click node_storage "https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/storage.go"
click node_auth "https://github.com/rapidfort/kimia/blob/main/src/internal/auth/docker.go"
click node_registry "https://github.com/rapidfort/kimia/blob/main/src/internal/auth/registry.go"
click node_attest "https://github.com/rapidfort/kimia/tree/main/src/internal/build"

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_args,node_config,node_validation toneBlue
class node_context,node_builder,node_cache,node_repro,node_output,node_registry_service toneAmber
class node_preflight,node_validator,node_userns,node_storage toneMint
class node_auth,node_registry,node_attest toneRose
class node_user,node_git,node_engine,node_cosign toneIndigo
```

## Components

### CLI and orchestration

- [CLI entry](https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/main.go): `src/cmd/kimia/main.go`
- [Argument parsing](https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/args.go): `src/cmd/kimia/args.go`
- [Build options](https://github.com/rapidfort/kimia/blob/main/src/cmd/kimia/config.go): `src/cmd/kimia/config.go`
- [Input validation](https://github.com/rapidfort/kimia/blob/main/src/internal/validation/validation.go): `src/internal/validation/validation.go`

### Image build

- [Build context](https://github.com/rapidfort/kimia/blob/main/src/internal/build/context.go): `src/internal/build/context.go`
- [Builder execution](https://github.com/rapidfort/kimia/blob/main/src/internal/build/builder.go): `src/internal/build/builder.go`
- [Build caching](https://github.com/rapidfort/kimia/tree/main/src/internal/build): `src/internal/build`
- [Reproducible builds](https://github.com/rapidfort/kimia/tree/main/src/internal/build): `src/internal/build`
- [Image output](https://github.com/rapidfort/kimia/blob/main/src/internal/build/push.go): `src/internal/build/push.go`

### Rootless readiness

- [Environment checks](https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/check_environment.go): `src/internal/preflight/check_environment.go`
- [Runtime validation](https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/validator.go): `src/internal/preflight/validator.go`
- [User namespaces](https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/userns.go): `src/internal/preflight/userns.go`
- [Storage checks](https://github.com/rapidfort/kimia/blob/main/src/internal/preflight/storage.go): `src/internal/preflight/storage.go`

### Registries and supply chain

- [Registry authentication](https://github.com/rapidfort/kimia/blob/main/src/internal/auth/docker.go): `src/internal/auth/docker.go`
- [Cloud registry credentials](https://github.com/rapidfort/kimia/blob/main/src/internal/auth/registry.go): `src/internal/auth/registry.go`
- [Attestation and signing](https://github.com/rapidfort/kimia/tree/main/src/internal/build): `src/internal/build`

### Other components

- **Build operator**
- **Git repository**
- **BuildKit or Buildah**
- **OCI registry**
- **Cosign**

## Connections

- Build operator → CLI entry: runs
- CLI entry → Argument parsing: parses flags
- Argument parsing → Build options: sets options
- CLI entry → Environment checks: checks environment
- Environment checks → Runtime validation: validates runtime
- Runtime validation → User namespaces: checks isolation
- Runtime validation → Storage checks: checks storage
- CLI entry → Input validation: validates inputs
- CLI entry → Build context: prepares context
- Build context → Git repository: fetches source
- CLI entry → Registry authentication: sets up credentials
- Registry authentication → Cloud registry credentials: refreshes cloud credentials
- CLI entry → Builder execution: executes build
- Builder execution → Build context: uses context
- Builder execution → BuildKit or Buildah: invokes builder
- Builder execution → Build caching: uses cache options
- Builder execution → Reproducible builds: applies build settings
- CLI entry → Image output: pushes or exports
- Image output → OCI registry: pushes image
- Builder execution → Attestation and signing: configures attestations
- Attestation and signing → Cosign: signs image
- Attestation and signing → OCI registry: publishes attestations
