# project-zot/zot architecture

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

- Interactive diagram: https://gitdiagram.com/project-zot/zot
- Repository: https://github.com/project-zot/zot

## Overview

zot is a vendor-neutral OCI image registry: clients push and pull OCI artifacts through the distribution API, while zot authenticates requests, routes repositories to image storage, and maintains registry metadata. Its broader product includes replication, search/CVE scanning, retention, and event/monitoring extensions, plus separate administrative and search clients. The map follows documented and excerpted wiring; storage-driver and metadata-backend details are represented at their implementation boundaries where the excerpts do not establish finer call relationships.

Main entry points: [`pkg/api/controller.go`](https://github.com/project-zot/zot/blob/main/pkg/api/controller.go) (API controller), [`pkg/api/routes.go`](https://github.com/project-zot/zot/blob/main/pkg/api/routes.go) (OCI distribution API), [`pkg/storage/imagestore/imagestore.go`](https://github.com/project-zot/zot/blob/main/pkg/storage/imagestore/imagestore.go) (Image store), [`pkg/extensions/sync/service.go`](https://github.com/project-zot/zot/blob/main/pkg/extensions/sync/service.go) (Registry sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Registry serving"]
  node_server["Server startup<br/>[root.go]"]
  node_controller["API controller<br/>[controller.go]"]
  node_routes["OCI distribution API<br/>[routes.go]"]
  node_auth["Authentication<br/>[authn.go]"]
end

subgraph group_storage["Artifact and metadata"]
  node_storefactory["Store setup<br/>[storage.go]"]
  node_storemap["Store routing"]
  node_imagestore["Image store<br/>[imagestore.go]"]
  node_storagebackend["Storage drivers<br/>[common.go]"]
  node_metadb[("Metadata backends")]
end

subgraph group_extensions["Registry capabilities"]
  node_sync["Registry sync<br/>[service.go]"]
  node_search["Search and CVE"]
  node_retention["Retention<br/>[retention.go]"]
  node_scheduler["Background scheduler<br/>[scheduler.go]"]
  node_events["Event extensions"]
end

subgraph group_clients["Clients and operations"]
  node_cli["Registry CLI"]
  node_searchcli["Search CLI<br/>[service.go]"]
  node_exporter["Metrics exporter<br/>[exporter.go]"]
  node_zb["Benchmark tool<br/>[perf.go]"]
end

node_user(("Registry client"))
node_registry(("Upstream registry"))
node_objectstore[("Cloud object storage")]

node_user -->|"configures"| node_server
node_server -->|"starts"| node_controller
node_controller -->|"initializes stores"| node_storefactory
node_controller -->|"sets up router"| node_routes
node_user -->|"sends OCI requests"| node_routes
node_routes -->|"authenticates"| node_auth
node_routes -->|"routes repository"| node_storemap
node_storefactory -->|"builds store map"| node_storemap
node_storefactory -->|"creates drivers"| node_storagebackend
node_storemap -->|"selects image store"| node_imagestore
node_routes -->|"reads and writes artifacts"| node_imagestore
node_imagestore -.->|"records metadata"| node_metadb
node_storagebackend -.->|"stores artifacts"| node_objectstore
node_controller -->|"starts tasks"| node_scheduler
node_controller -->|"configures recorder"| node_events
node_controller -.->|"initializes sync"| node_sync
node_sync -->|"replicates from"| node_registry
node_sync -->|"writes synced content"| node_imagestore
node_sync -->|"uses metadata"| node_metadb
node_controller -->|"registers extension"| node_search
node_search -->|"queries metadata"| node_metadb
node_search -->|"searches images"| node_imagestore
node_controller -.->|"runs retention"| node_retention
node_user -->|"administers registry"| node_cli
node_cli -.->|"calls registry API"| node_routes
node_user -->|"requests image search"| node_searchcli
node_searchcli -->|"queries registry"| node_registry
node_user -.->|"scrapes metrics"| node_exporter
node_user -->|"runs benchmark"| node_zb
node_zb -.->|"benchmarks requests"| node_registry

click node_server "https://github.com/project-zot/zot/blob/main/pkg/cli/server/root.go"
click node_controller "https://github.com/project-zot/zot/blob/main/pkg/api/controller.go"
click node_routes "https://github.com/project-zot/zot/blob/main/pkg/api/routes.go"
click node_auth "https://github.com/project-zot/zot/blob/main/pkg/api/authn.go"
click node_storefactory "https://github.com/project-zot/zot/blob/main/pkg/storage/storage.go"
click node_storemap "https://github.com/project-zot/zot/blob/main/pkg/storage/storage_controller.go"
click node_imagestore "https://github.com/project-zot/zot/blob/main/pkg/storage/imagestore/imagestore.go"
click node_storagebackend "https://github.com/project-zot/zot/blob/main/pkg/storage/common/common.go"
click node_metadb "https://github.com/project-zot/zot/tree/main/pkg/meta"
click node_sync "https://github.com/project-zot/zot/blob/main/pkg/extensions/sync/service.go"
click node_search "https://github.com/project-zot/zot/blob/main/pkg/extensions/extension_search.go"
click node_retention "https://github.com/project-zot/zot/blob/main/pkg/retention/retention.go"
click node_scheduler "https://github.com/project-zot/zot/blob/main/pkg/scheduler/scheduler.go"
click node_events "https://github.com/project-zot/zot/tree/main/pkg/extensions/events"
click node_cli "https://github.com/project-zot/zot/tree/main/pkg/cli/client"
click node_searchcli "https://github.com/project-zot/zot/blob/main/pkg/cli/client/service.go"
click node_exporter "https://github.com/project-zot/zot/blob/main/pkg/exporter/api/exporter.go"
click node_zb "https://github.com/project-zot/zot/blob/main/cmd/zb/perf.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_server,node_controller,node_routes,node_auth,node_user toneBlue
class node_storefactory,node_storemap,node_imagestore,node_storagebackend,node_metadb,node_objectstore toneAmber
class node_sync,node_search,node_retention,node_scheduler,node_events toneMint
class node_cli,node_searchcli,node_exporter,node_zb toneRose
class node_registry toneIndigo
```

## Components

### Registry serving

- [Server startup](https://github.com/project-zot/zot/blob/main/pkg/cli/server/root.go): `pkg/cli/server/root.go`
- [API controller](https://github.com/project-zot/zot/blob/main/pkg/api/controller.go): `pkg/api/controller.go`
- [OCI distribution API](https://github.com/project-zot/zot/blob/main/pkg/api/routes.go): `pkg/api/routes.go`
- [Authentication](https://github.com/project-zot/zot/blob/main/pkg/api/authn.go): `pkg/api/authn.go`

### Artifact and metadata

- [Store setup](https://github.com/project-zot/zot/blob/main/pkg/storage/storage.go): `pkg/storage/storage.go`
- [Store routing](https://github.com/project-zot/zot/blob/main/pkg/storage/storage_controller.go): `pkg/storage/storage_controller.go`
- [Image store](https://github.com/project-zot/zot/blob/main/pkg/storage/imagestore/imagestore.go): `pkg/storage/imagestore/imagestore.go`
- [Storage drivers](https://github.com/project-zot/zot/blob/main/pkg/storage/common/common.go): `pkg/storage/common/common.go`
- [Metadata backends](https://github.com/project-zot/zot/tree/main/pkg/meta): `pkg/meta`

### Registry capabilities

- [Registry sync](https://github.com/project-zot/zot/blob/main/pkg/extensions/sync/service.go): `pkg/extensions/sync/service.go`
- [Search and CVE](https://github.com/project-zot/zot/blob/main/pkg/extensions/extension_search.go): `pkg/extensions/extension_search.go`
- [Retention](https://github.com/project-zot/zot/blob/main/pkg/retention/retention.go): `pkg/retention/retention.go`
- [Background scheduler](https://github.com/project-zot/zot/blob/main/pkg/scheduler/scheduler.go): `pkg/scheduler/scheduler.go`
- [Event extensions](https://github.com/project-zot/zot/tree/main/pkg/extensions/events): `pkg/extensions/events`

### Clients and operations

- [Registry CLI](https://github.com/project-zot/zot/tree/main/pkg/cli/client): `pkg/cli/client`
- [Search CLI](https://github.com/project-zot/zot/blob/main/pkg/cli/client/service.go): `pkg/cli/client/service.go`
- [Metrics exporter](https://github.com/project-zot/zot/blob/main/pkg/exporter/api/exporter.go): `pkg/exporter/api/exporter.go`
- [Benchmark tool](https://github.com/project-zot/zot/blob/main/cmd/zb/perf.go): `cmd/zb/perf.go`

### Other components

- **Registry client**
- **Upstream registry**
- **Cloud object storage**

## Connections

- Registry client → Server startup: configures (evidence: `pkg/cli/server/root.go`)
- Server startup → API controller: starts (evidence: `pkg/cli/server/root.go`)
- API controller → Store setup: initializes stores (evidence: `pkg/api/controller.go`)
- API controller → OCI distribution API: sets up router (evidence: `pkg/api/controller.go`)
- Registry client → OCI distribution API: sends OCI requests (evidence: `README.md`)
- OCI distribution API → Authentication: authenticates (evidence: `pkg/api/routes.go`)
- OCI distribution API → Store routing: routes repository (evidence: `pkg/api/routes.go`)
- Store setup → Store routing: builds store map (evidence: `pkg/storage/storage.go`)
- Store setup → Storage drivers: creates drivers (evidence: `pkg/storage/storage.go`)
- Store routing → Image store: selects image store (evidence: `pkg/storage/storage_controller.go`)
- OCI distribution API → Image store: reads and writes artifacts (evidence: `pkg/api/routes.go`)
- Image store → Metadata backends: records metadata
- Storage drivers → Cloud object storage: stores artifacts
- API controller → Background scheduler: starts tasks (evidence: `pkg/api/controller.go`)
- API controller → Event extensions: configures recorder (evidence: `pkg/api/controller.go`)
- API controller → Registry sync: initializes sync
- Registry sync → Upstream registry: replicates from (evidence: `pkg/extensions/sync/service.go`)
- Registry sync → Image store: writes synced content (evidence: `pkg/extensions/sync/service.go`)
- Registry sync → Metadata backends: uses metadata (evidence: `pkg/extensions/sync/service.go`)
- API controller → Search and CVE: registers extension (evidence: `pkg/extensions/extension_search.go`)
- Search and CVE → Metadata backends: queries metadata (evidence: `pkg/extensions/extension_search.go`)
- Search and CVE → Image store: searches images (evidence: `pkg/extensions/extension_search.go`)
- API controller → Retention: runs retention
- Registry client → Registry CLI: administers registry (evidence: `pkg/cli/client/client.go`)
- Registry CLI → OCI distribution API: calls registry API
- Registry client → Search CLI: requests image search (evidence: `pkg/cli/client/service.go`)
- Search CLI → Upstream registry: queries registry
- Registry client → Metrics exporter: scrapes metrics
- Registry client → Benchmark tool: runs benchmark
- Benchmark tool → Upstream registry: benchmarks requests
