# nilsirl/dockerc architecture

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

- Interactive diagram: https://gitdiagram.com/nilsirl/dockerc
- Repository: https://github.com/nilsirl/dockerc

## Overview

##### Project Type and Purpose
- Project Type: A command-line tool written in Zig.
- Purpose: Fetch a Docker/OCI image (via Skopeo), unpack its filesystem layers, repackage them along with a minimal container runtime (crun + fuse-overlayfs + libfuse), and emit a single standalone binary that runs the container rootlessly.

##### File Structure
- Top-Level Files & Directories:
- build.zig / build.zig.zon – Zig build scripts
- src/ – Core Zig source files (CLI entrypoint, common utilities, extraction, runtime glue)
- argp-standalone, crun, fuse-overlayfs, libfuse, skopeo, squashfs-tools, squashfuse, umoci, zstd – Git submodules providing:
– Image loading (skopeo, umoci)
– Filesystem extraction and overlay (squashfs-tools, squashfuse, fuse-overlayfs, libfuse)
– Runtime execution (crun)
– Compression (zstd)
- src/tools/policy.json – Configuration for image policy
- .github/workflows/ci.yml – CI pipeline
- Patterns: A linear pipeline of components glued together in Zig, each coming from a Git submodule or from native Zig code.

##### README for Additional Insights
- Confirms:
- Use of Skopeo for fetching images (supports docker://, docker-daemon:)
- Rootless container execution
- CLI flags (-e, -v) mirror docker run
- Targets x86_64 and arm64 via Zig + MUSL

a. Main Components
1. CLI Frontend (src/main.zig + src/dockerc.zig)
2. Image Loader Module (Skopeo + Umoci)
3. Filesystem Extractor & Compressor (squashfs-tools, squashfuse, zstd)
4. Overlay Setup (fuse-overlayfs + libfuse)
5. Container Runtime (crun)
6. Binary Packager (Zig linker + embedded runtime libraries)
7. Host Environment (OS kernel + user namespaces)
b. Relationships & Data Flow
1. User invokes `dockerc --image ...` → CLI Frontend parses args
2. CLI calls Image Loader → fetches layers from registry or local daemon
3. Layers passed to Filesystem Extractor → decompress & assemble rootfs
4. Overlay Setup glues rootfs into an ephemeral filesystem mount
5. Container Runtime (crun) is embedded and configured to use user namespaces + FUSE overlay
6. Zig Binary Packager links all code + submodule artifacts into a single executable
7. Final Binary runs directly on Host → sets up rootfs & launches payload
c. Architectural Patterns & Principles
- Pipeline pattern: discrete stages (fetch → extract → package → run)
- Single-binary distribution: embed runtime + fs tools to avoid external deps
- Rootless container execution leveraging Linux namespaces + FUSE
d. Key Technologies & Libraries
- Language & build: Zig, Zig build scripts, Zig’s musl-linked target
- Image handling: Skopeo (Go), Umoci (Go)
- Filesystems: squashfs-tools (C), squashfuse, fuse-overlayfs, libfuse
- Runtime: crun (C)
- Compression: zstd (C)
- OS interfaces: FUSE, user namespaces, Linux kernel

##### Final Checklist
- Have you separated **Build-time** vs **Runtime** components?
- Are all Git submodules represented in their functional group?
- Are all interfaces (FUSE, user namespaces, registry APIs) clearly labeled?

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time Phase
    subgraph "Build-time"
        direction TB
        CI["CI Pipeline\n(.github/workflows/ci.yml)"]:::ext
        Build["Binary Packager\n(build.zig, build.zig.zon)"]:::zig
        subgraph "Zig Source Modules"
            direction TB
            MainZig["CLI Frontend\n(src/main.zig)"]:::zig
            DockercZig["Dockerc Entrypoint\n(src/dockerc.zig)"]:::zig
            CommonUtils["Common Utilities & Runtime Glue\n(src/common.zig, src/replace.zig, src/runtimes.zig)"]:::zig
            ExtractFS["Filesystem Extractor\n(src/extract_squashfs.zig)"]:::zig
            Policy["Policy Config\n(src/tools/policy.json)"]:::zig
        end
        subgraph "External Submodules"
            direction TB
            Gitmodules["Submodule Definitions\n(.gitmodules)"]:::sub
            subgraph "Image Fetchers"
                direction TB
                Skopeo["skopeo"]:::sub
                Umoci["umoci"]:::sub
            end
            subgraph "Filesystem Tools"
                direction TB
                SquashfsTools["squashfs-tools"]:::sub
                Squashfuse["squashfuse"]:::sub
                Zstd["zstd"]:::sub
            end
            subgraph "Overlay Setup"
                direction TB
                FuseOverlayfs["fuse-overlayfs"]:::sub
                Libfuse["libfuse"]:::sub
            end
            subgraph "Container Runtime"
                direction TB
                Crun["crun"]:::sub
            end
        end
        CI -->|triggers| Build
        Build -.->|links| MainZig
        Build -.->|links| DockercZig
        Build -.->|links| CommonUtils
        Build -.->|links| ExtractFS
        Build -.->|links| Policy
        Build -.->|includes| Skopeo
        Build -.->|includes| Umoci
        Build -.->|includes| SquashfsTools
        Build -.->|includes| Squashfuse
        Build -.->|includes| Zstd
        Build -.->|includes| FuseOverlayfs
        Build -.->|includes| Libfuse
        Build -.->|includes| Crun
        Build -.->|reads| Gitmodules

        Build -->|outputs| DockercBinary["dockerc\n(single standalone binary)"]:::zig
    end

    %% Runtime Phase
    subgraph "Runtime"
        direction TB
        DockercBinary -->|args parsing| CLIExec["CLI Execution"]:::zig
        CLIExec -->|fetch image| SkopeoRuntime["skopeo"]:::sub
        CLIExec -->|fetch image| UmociRuntime["umoci"]:::sub
        SkopeoRuntime -->|OCI layers.tar.gz| ExtractStage["Decompress & Assemble RootFS"]:::zig
        UmociRuntime -->|OCI layers.tar.gz| ExtractStage
        ExtractStage -->|rootfs| OverlayStage["FUSE Overlay Mount"]:::sub
        OverlayStage -->|mounted rootfs| CrunExec["crun"]:::sub
        CrunExec -->|launch container| HostKernel["Linux Kernel\n(user namespaces & FUSE)"]:::ext
        CLIExec -->|supports| DockerRegistry["Docker Registry"]:::ext
        CLIExec -->|supports| DockerDaemon["Docker Daemon"]:::ext
    end

    %% Click Events
    click MainZig "https://github.com/nilsirl/dockerc/blob/trunk/src/main.zig"
    click DockercZig "https://github.com/nilsirl/dockerc/blob/trunk/src/dockerc.zig"
    click CommonUtils "https://github.com/nilsirl/dockerc/blob/trunk/src/common.zig"
    click ExtractFS "https://github.com/nilsirl/dockerc/blob/trunk/src/extract_squashfs.zig"
    click Policy "https://github.com/nilsirl/dockerc/blob/trunk/src/tools/policy.json"
    click CI "https://github.com/nilsirl/dockerc/blob/trunk/.github/workflows/ci.yml"
    click Build "https://github.com/nilsirl/dockerc/blob/trunk/build.zig"
    click Build "https://github.com/nilsirl/dockerc/blob/trunk/build.zig.zon"
    click Skopeo "https://github.com/nilsirl/dockerc/tree/trunk/skopeo/"
    click Umoci "https://github.com/nilsirl/dockerc/tree/trunk/umoci/"
    click SquashfsTools "https://github.com/nilsirl/dockerc/tree/trunk/squashfs-tools/"
    click Squashfuse "https://github.com/nilsirl/dockerc/tree/trunk/squashfuse/"
    click Zstd "https://github.com/nilsirl/dockerc/tree/trunk/zstd/"
    click FuseOverlayfs "https://github.com/nilsirl/dockerc/tree/trunk/fuse-overlayfs/"
    click Libfuse "https://github.com/nilsirl/dockerc/tree/trunk/libfuse/"
    click Crun "https://github.com/nilsirl/dockerc/tree/trunk/crun/"
    click Gitmodules "https://github.com/nilsirl/dockerc/blob/trunk/.gitmodules"

    %% Styles
    classDef zig fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef sub fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef ext fill:#FFD580,stroke:#333,stroke-width:1px;
```
