# containers/storage architecture

> Architecture diagram of the GitHub repository containers/storage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containers/storage
- Repository: https://github.com/containers/storage

## Overview

##### Project type and purpose
- This is a Go-based library (called “storage”) with a secondary CLI wrapper (`containers-storage`) for managing container layers, images, and containers on disk.
- Primary use case: provide programmatic APIs for creating, querying, and modifying copy-on-write filesystem layers, plus a command-line interface for scripting and manual operations.

##### File-structure analysis
- Top-level
- cmd/containers-storage: CLI entrypoint, one file per CLI command, calls into library
- pkg/, internal/: Go packages implementing core functionality (archive, chunked, config, drivers, etc.)
- drivers/: pluggable filesystem drivers (overlay, aufs, btrfs, vfs, zfs, windows)
- types/: type definitions (IDs, options, error handling)
- check.go, store.go: top-level initializers
- tests/: Bash “bats” integration tests for CLI behavior
- Build & CI
- Makefile, .cirrus.yml, contrib/cirrus: build/test scripts
- vendor/: vendored dependencies

##### README insights
- Describes three managed entities: layers (CoW filesystems), images (top-layer refs + metadata), containers (read-write children with config)
- Mentions optional VM test environment via Vagrant+libvirt

##### Main components
a. CLI layer
- `containers-storage` binary (cmd/containers-storage)
b. Core library
- Storage Manager (store.go)
- Metadata store (in-memory/cache + on-disk bookkeeping)
- Big-data store (named chunked files for images/containers)
c. Subsystems
- Drivers subsystem (drivers/*)
- Archive subsystem (pkg/archive, pkg/chrootarchive)
- Chunking & compression (pkg/chunked)
- Configuration & options (pkg/config, internal/opts, types)
- File and filesystem utilities (pkg/fileutils, pkg/fsutils, pkg/mount, pkg/loopback, pkg/unshare)
d. Host environment
- OS kernel interfaces (mount, chroot, loopback, syscalls)
- Optional Vagrant + libvirt VM layer for CI tests

##### Relationships & data flows
- CLI → Storage Manager API calls → Core library
- Storage Manager → Drivers (via driver.Register) → Kernel
- Storage Manager → Archive/Chunked subsystems → Data files on disk
- Metadata cache ↔ On-disk metadata files
- Big-data read/write ↔ Named files on disk
- Tests & CI runners drive the CLI component

##### Architectural patterns & principles
- Layered architecture: CLI, API core, subsystem packages, OS drivers
- Plugin pattern for filesystem drivers (registerable drivers in drivers/register)
- Separation of concerns: distinct packages for archiving, chunking, config, and system calls
- Dependency injection: core components accept driver interfaces, config objects

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes / Layers
    subgraph "User & CLI Layer"
        direction TB
        CLI["containers-storage (CLI)"]:::cli
    end

    subgraph "Core Library & Subsystems"
        direction TB
        SM["Storage Manager"]:::core
        MS["Metadata Store"]:::storage
        BDS["Big-data Store"]:::storage
        subgraph "Subsystems"
            direction TB
            DR["Drivers Subsystem"]:::core
            DRR["Driver Registration"]:::core
            AR["Archive Subsystem"]:::core
            CH["Chunking & Compression"]:::core
            CFG["Configuration & Options"]:::core
            TP["Types Definitions"]:::core
            FU["File Utilities"]:::core
            FSU["Filesystem Utilities"]:::core
            MT["Mounting Interfaces"]:::core
            LB["Loopback Support"]:::core
            US["Unshare/Ns Isolation"]:::core
        end
    end

    subgraph "Host OS & Kernel"
        direction TB
        K["OS Kernel Interfaces"]:::external
    end

    subgraph "External CI/VM"
        direction TB
        CI["CI VM Environment"]:::external
    end

    %% Relationships
    CLI -->|"invokes"| SM
    SM -->|"loads config"| CFG
    SM -->|"manages metadata"| MS
    SM -->|"reads/writes big data"| BDS
    SM -->|"registers driver"| DRR
    DRR -->|"provides"| DR
    SM -->|"uses archive"| AR
    SM -->|"uses chunking"| CH
    SM -->|"uses file utils"| FU
    SM -->|"uses fs utils"| FSU
    SM -->|"uses mount"| MT
    SM -->|"uses loopback"| LB
    SM -->|"uses unshare"| US
    DR -->|"calls"| K
    AR -->|"read/write files"| BDS
    CH -->|"read/write files"| BDS
    MS <-->|"cache↔disk"| MS
    CI -->|"drives CLI tests"| CLI

    %% Click Events
    click CLI "https://github.com/containers/storage/tree/main/cmd/containers-storage"
    click SM "https://github.com/containers/storage/blob/main/store.go"
    click MS "https://github.com/containers/storage/blob/main/store.go"
    click TP "https://github.com/containers/storage/tree/main/types/"
    click BDS "https://github.com/containers/storage/tree/main/pkg/chunked"
    click DR "https://github.com/containers/storage/tree/main/drivers/"
    click DRR "https://github.com/containers/storage/tree/main/drivers/register/"
    click AR "https://github.com/containers/storage/tree/main/pkg/archive"
    click AR "https://github.com/containers/storage/tree/main/pkg/chrootarchive"
    click CH "https://github.com/containers/storage/tree/main/pkg/chunked"
    click CFG "https://github.com/containers/storage/tree/main/pkg/config"
    click CFG "https://github.com/containers/storage/tree/main/internal/opts"
    click TP "https://github.com/containers/storage/tree/main/types/"
    click FU "https://github.com/containers/storage/tree/main/pkg/fileutils"
    click FSU "https://github.com/containers/storage/tree/main/pkg/fsutils"
    click MT "https://github.com/containers/storage/tree/main/pkg/mount"
    click LB "https://github.com/containers/storage/tree/main/pkg/loopback"
    click US "https://github.com/containers/storage/tree/main/pkg/unshare"
    click CI "https://github.com/containers/storage/blob/main/hack/get_ci_vm.sh"
    click CI "https://github.com/containers/storage/tree/main/contrib/cirrus"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#036,stroke-width:1px
    classDef core fill:#89CFF0,stroke:#036,stroke-width:1px
    classDef storage fill:#98FB98,stroke:#036,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#666,stroke-width:1px
```
