# spegel-org/spegel architecture

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

- Interactive diagram: https://gitdiagram.com/spegel-org/spegel
- Repository: https://github.com/spegel-org/spegel

## Overview

Spegel is a stateless, cluster-local OCI registry mirror. A workload’s image pull reaches Spegel’s registry API, which serves content from the local containerd store when available and can obtain missing content from external registries or peers. The runtime also shares content availability through libp2p and exposes operational metrics and a web interface. The graph preserves these documented capabilities; implementation details for some unsampled modules are limited to source-index references, so uncertain links are omitted.

Main entry points: [`main.go`](https://github.com/spegel-org/spegel/blob/main/main.go) (Runtime setup), [`pkg/registry/registry.go`](https://github.com/spegel-org/spegel/blob/main/pkg/registry/registry.go) (Registry API), [`pkg/oci/containerd/containerd.go`](https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/containerd.go) (Containerd store), [`pkg/web/web.go`](https://github.com/spegel-org/spegel/blob/main/pkg/web/web.go) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Runtime setup<br/>[main.go]"]
  node_registry["Registry API<br/>[registry.go]"]
end

subgraph group_content["Image content"]
  node_distribution["OCI protocol<br/>[distribution.go]"]
  node_oci_client["Remote OCI client<br/>[client.go]"]
  node_containerd[("Containerd store<br/>[containerd.go]")]
  node_content_index["Content index<br/>[index.go]"]
  node_mirror_config["Mirror configuration<br/>[mirror.go]"]
  node_oci_image["Image metadata<br/>[image.go]"]
end

subgraph group_peering["Peer network"]
  node_router["Libp2p router<br/>[libp2p.go]"]
  node_routing_core["Routing model<br/>[routing.go]"]
  node_routing_sync["Store sync<br/>[sync.go]"]
end

subgraph group_operations["Operations"]
  node_web["Web dashboard<br/>[web.go]"]
  node_metrics["Prometheus metrics<br/>[metrics.go]"]
  node_cleanup["Cleanup probes<br/>[cleanup.go]"]
  node_preflight["Preflight checks<br/>[preflight.go]"]
end

node_workload(("Image puller"))
node_external_registry["External registry"]

node_workload -->|"requests images"| node_registry
node_main -->|"initializes store"| node_containerd
node_main -->|"starts routing"| node_router
node_main -->|"starts API"| node_registry
node_main -->|"starts dashboard"| node_web
node_main -->|"registers metrics"| node_metrics
node_main -->|"configures mirrors"| node_mirror_config
node_main -->|"runs cleanup"| node_cleanup
node_registry -->|"reads content"| node_containerd
node_registry -->|"finds peers"| node_router
node_registry -->|"fetches content"| node_oci_client
node_registry -->|"parses requests"| node_distribution
node_oci_client -->|"fetches OCI data"| node_external_registry
node_containerd -->|"parses image refs"| node_oci_image
node_containerd -->|"updates index"| node_content_index
node_router -->|"uses routing types"| node_routing_core
node_web -->|"lists peers"| node_router
node_web -->|"lists images"| node_containerd
node_web -->|"measures pulls"| node_registry
node_metrics -.->|"tracks mirror activity"| node_registry
node_routing_sync -.->|"syncs store data"| node_containerd
node_preflight -.->|"checks startup"| node_main

click node_main "https://github.com/spegel-org/spegel/blob/main/main.go"
click node_registry "https://github.com/spegel-org/spegel/blob/main/pkg/registry/registry.go"
click node_distribution "https://github.com/spegel-org/spegel/blob/main/pkg/oci/distribution.go"
click node_oci_client "https://github.com/spegel-org/spegel/blob/main/pkg/oci/client.go"
click node_containerd "https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/containerd.go"
click node_content_index "https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/index.go"
click node_mirror_config "https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/mirror.go"
click node_oci_image "https://github.com/spegel-org/spegel/blob/main/pkg/oci/image.go"
click node_router "https://github.com/spegel-org/spegel/blob/main/pkg/routing/libp2p/libp2p.go"
click node_routing_core "https://github.com/spegel-org/spegel/blob/main/pkg/routing/routing.go"
click node_routing_sync "https://github.com/spegel-org/spegel/blob/main/pkg/routing/sync.go"
click node_web "https://github.com/spegel-org/spegel/blob/main/pkg/web/web.go"
click node_metrics "https://github.com/spegel-org/spegel/blob/main/pkg/metrics/metrics.go"
click node_cleanup "https://github.com/spegel-org/spegel/blob/main/pkg/cleanup/cleanup.go"
click node_preflight "https://github.com/spegel-org/spegel/blob/main/pkg/preflight/preflight.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_main,node_registry toneBlue
class node_distribution,node_oci_client,node_containerd,node_content_index,node_mirror_config,node_oci_image toneAmber
class node_router,node_routing_core,node_routing_sync toneMint
class node_web,node_metrics,node_cleanup,node_preflight toneRose
class node_workload,node_external_registry toneIndigo
```

## Components

### Runtime

- [Runtime setup](https://github.com/spegel-org/spegel/blob/main/main.go): `main.go`
- [Registry API](https://github.com/spegel-org/spegel/blob/main/pkg/registry/registry.go): `pkg/registry/registry.go`

### Image content

- [OCI protocol](https://github.com/spegel-org/spegel/blob/main/pkg/oci/distribution.go): `pkg/oci/distribution.go`
- [Remote OCI client](https://github.com/spegel-org/spegel/blob/main/pkg/oci/client.go): `pkg/oci/client.go`
- [Containerd store](https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/containerd.go): `pkg/oci/containerd/containerd.go`
- [Content index](https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/index.go): `pkg/oci/containerd/index.go`
- [Mirror configuration](https://github.com/spegel-org/spegel/blob/main/pkg/oci/containerd/mirror.go): `pkg/oci/containerd/mirror.go`
- [Image metadata](https://github.com/spegel-org/spegel/blob/main/pkg/oci/image.go): `pkg/oci/image.go`

### Peer network

- [Libp2p router](https://github.com/spegel-org/spegel/blob/main/pkg/routing/libp2p/libp2p.go): `pkg/routing/libp2p/libp2p.go`
- [Routing model](https://github.com/spegel-org/spegel/blob/main/pkg/routing/routing.go): `pkg/routing/routing.go`
- [Store sync](https://github.com/spegel-org/spegel/blob/main/pkg/routing/sync.go): `pkg/routing/sync.go`

### Operations

- [Web dashboard](https://github.com/spegel-org/spegel/blob/main/pkg/web/web.go): `pkg/web/web.go`
- [Prometheus metrics](https://github.com/spegel-org/spegel/blob/main/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`
- [Cleanup probes](https://github.com/spegel-org/spegel/blob/main/pkg/cleanup/cleanup.go): `pkg/cleanup/cleanup.go`
- [Preflight checks](https://github.com/spegel-org/spegel/blob/main/pkg/preflight/preflight.go): `pkg/preflight/preflight.go`

### Other components

- **Image puller**
- **External registry**

## Connections

- Image puller → Registry API: requests images (evidence: `pkg/registry/registry.go`)
- Runtime setup → Containerd store: initializes store (evidence: `main.go`)
- Runtime setup → Libp2p router: starts routing (evidence: `main.go`)
- Runtime setup → Registry API: starts API (evidence: `main.go`)
- Runtime setup → Web dashboard: starts dashboard (evidence: `main.go`)
- Runtime setup → Prometheus metrics: registers metrics (evidence: `main.go`)
- Runtime setup → Mirror configuration: configures mirrors (evidence: `main.go`)
- Runtime setup → Cleanup probes: runs cleanup (evidence: `main.go`)
- Registry API → Containerd store: reads content (evidence: `pkg/registry/registry.go`)
- Registry API → Libp2p router: finds peers (evidence: `pkg/registry/registry.go`)
- Registry API → Remote OCI client: fetches content (evidence: `pkg/registry/registry.go`)
- Registry API → OCI protocol: parses requests (evidence: `pkg/registry/registry.go`)
- Remote OCI client → External registry: fetches OCI data (evidence: `pkg/oci/client.go`)
- Containerd store → Image metadata: parses image refs (evidence: `pkg/oci/containerd/containerd.go`)
- Containerd store → Content index: updates index (evidence: `pkg/oci/containerd/containerd.go`)
- Libp2p router → Routing model: uses routing types (evidence: `pkg/routing/libp2p/libp2p.go`)
- Web dashboard → Libp2p router: lists peers (evidence: `pkg/web/web.go`)
- Web dashboard → Containerd store: lists images (evidence: `pkg/web/web.go`)
- Web dashboard → Registry API: measures pulls (evidence: `pkg/web/web.go`)
- Prometheus metrics → Registry API: tracks mirror activity
- Store sync → Containerd store: syncs store data
- Preflight checks → Runtime setup: checks startup
