# docker/sandbox-kit-spec architecture

> Architecture diagram of the GitHub repository docker/sandbox-kit-spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker/sandbox-kit-spec
- Repository: https://github.com/docker/sandbox-kit-spec

## Overview

This repository defines the Docker Sandbox Kit descriptor and provides a BuildKit frontend plus conformance tools. The primary authoring-to-artifact workflow declares and validates a Kit, resolves and fetches its dependencies, then builds or composes an OCI image; consumers can inspect or validate published artifacts, while runtime conformance suites exercise a runtime through an adapter. Edges reflect explicit README statements, shown calls, or source-index references; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`fetch/fetch.go`](https://github.com/docker/sandbox-kit-spec/blob/main/fetch/fetch.go) (Fetch and compose), [`cmd/kit-tck/main.go`](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/kit-tck/main.go) (Conformance CLI), [`tck/sandbox/checks.go`](https://github.com/docker/sandbox-kit-spec/blob/main/tck/sandbox/checks.go) (Runtime checks), [`spec/types.go`](https://github.com/docker/sandbox-kit-spec/blob/main/spec/types.go) (Descriptor grammar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_descriptor["Descriptor model"]
  node_descriptor_model["Descriptor grammar<br/>[types.go]"]
  node_descriptor_decode["Decode and validate<br/>[decode.go]"]
  node_descriptor_compose["Merge declarations<br/>[merge.go]"]
  node_dependency_resolve["Dependency resolver<br/>[resolve.go]"]
end

subgraph group_artifact["Build and composition"]
  node_frontend_build["BuildKit frontend<br/>[build.go]"]
  node_frontend_set["Kit set builder<br/>[set.go]"]
  node_frontend_diff["Authority diff<br/>[diff.go]"]
  node_registry_fetch["Registry fetch<br/>[registry.go]"]
  node_fetch_compose["Fetch and compose<br/>[fetch.go]"]
  node_image_assembly["Image assembly<br/>[assemble.go]"]
end

subgraph group_kitchecks["Kit conformance"]
  node_tck_cli["Conformance CLI<br/>[main.go]"]
  node_artifact_source["OCI artifact reader<br/>[source_oci.go]"]
  node_kit_suite["Kit validation suite<br/>[kit.go]"]
  node_kit_inspect["Artifact inspection<br/>[inspect.go]"]
end

subgraph group_runtimechecks["Runtime conformance"]
  node_runtime_suite["Runtime checks<br/>[checks.go]"]
  node_runtime_adapter["Runtime adapter<br/>[adapter.go]"]
  node_test_report["Conformance reports<br/>[render.go]"]
  node_spec_links["Specification links<br/>[speclink.go]"]
end

node_author(("Kit author"))

node_author -->|"defines Kit"| node_frontend_build
node_frontend_build -->|"reads grammar"| node_descriptor_model
node_frontend_build -->|"validates descriptor"| node_descriptor_decode
node_frontend_set -->|"orders dependencies"| node_dependency_resolve
node_frontend_set -->|"merges declarations"| node_descriptor_compose
node_frontend_diff -->|"compares declarations"| node_descriptor_model
node_registry_fetch -->|"decodes descriptor"| node_descriptor_decode
node_fetch_compose -->|"fetches Kits"| node_registry_fetch
node_fetch_compose -->|"resolves set"| node_dependency_resolve
node_fetch_compose -->|"composes declarations"| node_descriptor_compose
node_fetch_compose -->|"assembles image"| node_image_assembly
node_tck_cli -->|"runs validation"| node_kit_suite
node_tck_cli -->|"runs runtime checks"| node_runtime_suite
node_tck_cli -->|"loads artifacts"| node_artifact_source
node_tck_cli -->|"inspects artifact"| node_kit_inspect
node_artifact_source -->|"reads descriptor"| node_descriptor_model
node_kit_suite -->|"checks artifact"| node_artifact_source
node_runtime_suite -->|"exercises runtime"| node_runtime_adapter
node_runtime_suite -->|"checks capabilities"| node_descriptor_model
node_runtime_suite -->|"records findings"| node_test_report
node_test_report -->|"links requirements"| node_spec_links

click node_descriptor_model "https://github.com/docker/sandbox-kit-spec/blob/main/spec/types.go"
click node_descriptor_decode "https://github.com/docker/sandbox-kit-spec/blob/main/spec/decode.go"
click node_descriptor_compose "https://github.com/docker/sandbox-kit-spec/blob/main/spec/merge.go"
click node_dependency_resolve "https://github.com/docker/sandbox-kit-spec/blob/main/resolve/resolve.go"
click node_frontend_build "https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/build.go"
click node_frontend_set "https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/set.go"
click node_frontend_diff "https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/diff.go"
click node_registry_fetch "https://github.com/docker/sandbox-kit-spec/blob/main/fetch/registry.go"
click node_fetch_compose "https://github.com/docker/sandbox-kit-spec/blob/main/fetch/fetch.go"
click node_image_assembly "https://github.com/docker/sandbox-kit-spec/blob/main/fetch/assemble.go"
click node_tck_cli "https://github.com/docker/sandbox-kit-spec/blob/main/cmd/kit-tck/main.go"
click node_artifact_source "https://github.com/docker/sandbox-kit-spec/blob/main/tck/kit/source_oci.go"
click node_kit_suite "https://github.com/docker/sandbox-kit-spec/blob/main/tck/kit/kit.go"
click node_kit_inspect "https://github.com/docker/sandbox-kit-spec/blob/main/cmd/kit-tck/inspect.go"
click node_runtime_suite "https://github.com/docker/sandbox-kit-spec/blob/main/tck/sandbox/checks.go"
click node_runtime_adapter "https://github.com/docker/sandbox-kit-spec/blob/main/tck/adapter/adapter.go"
click node_test_report "https://github.com/docker/sandbox-kit-spec/blob/main/tck/report/render.go"
click node_spec_links "https://github.com/docker/sandbox-kit-spec/blob/main/tck/speclink/speclink.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_descriptor_model,node_descriptor_decode,node_descriptor_compose,node_dependency_resolve toneBlue
class node_frontend_build,node_frontend_set,node_frontend_diff,node_registry_fetch,node_fetch_compose,node_image_assembly toneAmber
class node_tck_cli,node_artifact_source,node_kit_suite,node_kit_inspect toneMint
class node_runtime_suite,node_runtime_adapter,node_test_report,node_spec_links toneRose
class node_author toneIndigo
```

## Components

### Descriptor model

- [Descriptor grammar](https://github.com/docker/sandbox-kit-spec/blob/main/spec/types.go): `spec/types.go`
- [Decode and validate](https://github.com/docker/sandbox-kit-spec/blob/main/spec/decode.go): `spec/decode.go`
- [Merge declarations](https://github.com/docker/sandbox-kit-spec/blob/main/spec/merge.go): `spec/merge.go`
- [Dependency resolver](https://github.com/docker/sandbox-kit-spec/blob/main/resolve/resolve.go): `resolve/resolve.go`

### Build and composition

- [BuildKit frontend](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/build.go): `cmd/frontend/build.go`
- [Kit set builder](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/set.go): `cmd/frontend/set.go`
- [Authority diff](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/frontend/diff.go): `cmd/frontend/diff.go`
- [Registry fetch](https://github.com/docker/sandbox-kit-spec/blob/main/fetch/registry.go): `fetch/registry.go`
- [Fetch and compose](https://github.com/docker/sandbox-kit-spec/blob/main/fetch/fetch.go): `fetch/fetch.go`
- [Image assembly](https://github.com/docker/sandbox-kit-spec/blob/main/fetch/assemble.go): `fetch/assemble.go`

### Kit conformance

- [Conformance CLI](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/kit-tck/main.go): `cmd/kit-tck/main.go`
- [OCI artifact reader](https://github.com/docker/sandbox-kit-spec/blob/main/tck/kit/source_oci.go): `tck/kit/source_oci.go`
- [Kit validation suite](https://github.com/docker/sandbox-kit-spec/blob/main/tck/kit/kit.go): `tck/kit/kit.go`
- [Artifact inspection](https://github.com/docker/sandbox-kit-spec/blob/main/cmd/kit-tck/inspect.go): `cmd/kit-tck/inspect.go`

### Runtime conformance

- [Runtime checks](https://github.com/docker/sandbox-kit-spec/blob/main/tck/sandbox/checks.go): `tck/sandbox/checks.go`
- [Runtime adapter](https://github.com/docker/sandbox-kit-spec/blob/main/tck/adapter/adapter.go): `tck/adapter/adapter.go`
- [Conformance reports](https://github.com/docker/sandbox-kit-spec/blob/main/tck/report/render.go): `tck/report/render.go`
- [Specification links](https://github.com/docker/sandbox-kit-spec/blob/main/tck/speclink/speclink.go): `tck/speclink/speclink.go`

### Other components

- **Kit author**

## Connections

- Kit author → BuildKit frontend: defines Kit (evidence: `README.md`)
- BuildKit frontend → Descriptor grammar: reads grammar (evidence: `cmd/frontend/build.go`)
- BuildKit frontend → Decode and validate: validates descriptor (evidence: `cmd/frontend/build.go`)
- Kit set builder → Dependency resolver: orders dependencies (evidence: `cmd/frontend/set.go`)
- Kit set builder → Merge declarations: merges declarations (evidence: `cmd/frontend/set.go`)
- Authority diff → Descriptor grammar: compares declarations (evidence: `cmd/frontend/diff.go`)
- Registry fetch → Decode and validate: decodes descriptor (evidence: `fetch/registry.go`)
- Fetch and compose → Registry fetch: fetches Kits (evidence: `fetch/fetch.go`)
- Fetch and compose → Dependency resolver: resolves set (evidence: `fetch/fetch.go`)
- Fetch and compose → Merge declarations: composes declarations (evidence: `fetch/fetch.go`)
- Fetch and compose → Image assembly: assembles image (evidence: `fetch/assemble.go`)
- Conformance CLI → Kit validation suite: runs validation (evidence: `cmd/kit-tck/main.go`)
- Conformance CLI → Runtime checks: runs runtime checks (evidence: `cmd/kit-tck/main.go`)
- Conformance CLI → OCI artifact reader: loads artifacts
- Conformance CLI → Artifact inspection: inspects artifact (evidence: `cmd/kit-tck/main.go`)
- OCI artifact reader → Descriptor grammar: reads descriptor (evidence: `tck/kit/source_oci.go`)
- Kit validation suite → OCI artifact reader: checks artifact (evidence: `tck/kit/kit.go`)
- Runtime checks → Runtime adapter: exercises runtime (evidence: `tck/sandbox/checks.go`)
- Runtime checks → Descriptor grammar: checks capabilities (evidence: `tck/sandbox/checks.go`)
- Runtime checks → Conformance reports: records findings (evidence: `tck/sandbox/checks.go`)
- Conformance reports → Specification links: links requirements