# checkpoint-restore/go-criu architecture

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

- Interactive diagram: https://gitdiagram.com/checkpoint-restore/go-criu
- Repository: https://github.com/checkpoint-restore/go-criu

## Overview

##### Project Type and Purpose
- go-criu is primarily a Go library exposing bindings for the CRIU checkpoint/restore daemon (“criu”), plus ancillary tools:
- A CRIU RPC client (core “go-criu” package)
- The “crit” package for reading/writing CRIU image files, plus a CLI tool (“crit” binary)
- The “phaul” package implementing the PHaul image‐streaming protocol (server & client)
- Support packages (“stats” for metrics, “magic” for file‐type detection, utility shims)
- Code‐generation scripts for Protobuf and magic data

##### High‐Level Components
- External CRIU Daemon
- go-criu Core Library
- RPC Layer (rpc/rpc.proto → rpc/rpc.pb.go)
- Crit Library (crit/*.go)
- PHaul API (phaul/*.go)
- Stats Package (stats/*.proto, stats/*.go)
- Magic Package (magic/magic.go)
- Utility Shims (utils/*.go)
- Binaries
- crit CLI (crit/cmd/main.go + crit/cli)
- phaul Server (phaul/server.go)
- phaul Client (phaul/client.go) – can be embedded in user apps
- Top‐level main.go (if present)
- Build & Codegen
- scripts/proto-gen (generates .pb.go from .proto)
- scripts/magic-gen (generates magic data)
- Tests & Examples (test/*)

##### Relationships & Data Flows
- User’s Go application → imports go-criu → invokes MakeCriu() → RPC Layer → UNIX socket/TCP → External CRIU Daemon
- crit CLI → Crit Library → reads/writes image files on disk
- phaul Client ↔ phaul Server → streams image data → Server uses go-criu RPC layer → CRIU Daemon
- Stats package can be used by user code or server to collect and serialize metrics (via Protobuf)
- Codegen scripts run offline or during CI to keep .pb.go files up to date

##### Architectural Patterns & Design Principles
- Layered Architecture:
- Presentation layer: CLI binaries & user applications
- Library layer: core go-criu packages (RPC, Crit, PHaul, Stats, Magic)
- External layer: CRIU daemon, filesystem (image files), network (RPC & PHaul streams)
- Separation of Concerns:
- RPC protocol handling is isolated under rpc/
- Image encoding/decoding under crit/
- Streaming protocol under phaul/
- Codegen decoupled into scripts/
- Use of Protobuf for cross‐language contracts (rpc.proto, stats.proto)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CritCLI["Crit CLI Binary"]:::bin
        PhaulServer["PHaul Server"]:::bin
        PhaulClient["PHaul Client"]:::bin
        TopMain["Top-Level main.go"]:::bin
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        RPC["RPC Layer"]:::core
        CritLib["Crit Library"]:::core
        PHaul["PHaul API"]:::core
        Stats["Stats Package"]:::core
        Magic["Magic Package"]:::core
        Utils["Utility Shims"]:::core
    end

    %% Code Generation Scripts
    subgraph "Codegen Scripts"
        direction TB
        ProtoGen["Protobuf Generator"]:::script
        MagicGen["Magic Data Generator"]:::script
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        CRIUDaemon["External CRIU Daemon"]:::external
        FileSystem["Image File System"]:::external
    end

    %% Flows
    TopMain -->|"imports go-criu\nMakeCriu()"| RPC
    RPC -->|"UNIX socket RPC"| CRIUDaemon
    CritCLI -->|"uses Crit Library"| CritLib
    CritLib -->|"reads/writes"| FileSystem
    PhaulClient <-->|"Protobuf stream"| PhaulServer
    PhaulServer -->|"via RPC Layer"| RPC
    Stats -->|"serialize metrics"| FileSystem
    Stats -.->|"used by"| PhaulServer
    Stats -.->|"used by"| TopMain
    ProtoGen -.->|"generates .pb.go for RPC/Stats"| RPC
    ProtoGen -.->|"generates .pb.go for RPC/Stats"| Stats
    MagicGen -.->|"generates magic data"| Magic

    %% Click Events
    click RPC "https://github.com/checkpoint-restore/go-criu/blob/master/rpc/rpc.proto"
    click CritLib "https://github.com/checkpoint-restore/go-criu/tree/master/crit/"
    click CritCLI "https://github.com/checkpoint-restore/go-criu/blob/master/crit/cmd/main.go"
    click PHaul "https://github.com/checkpoint-restore/go-criu/tree/master/phaul/"
    click Stats "https://github.com/checkpoint-restore/go-criu/tree/master/stats/"
    click Magic "https://github.com/checkpoint-restore/go-criu/blob/master/magic/magic.go"
    click Utils "https://github.com/checkpoint-restore/go-criu/tree/master/utils/"
    click TopMain "https://github.com/checkpoint-restore/go-criu/blob/master/main.go"
    click ProtoGen "https://github.com/checkpoint-restore/go-criu/tree/master/scripts/proto-gen/"
    click MagicGen "https://github.com/checkpoint-restore/go-criu/tree/master/scripts/magic-gen/"
    click FileSystem "https://github.com/checkpoint-restore/go-criu/tree/master/test/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#3399FF,color:#001F4D
    classDef bin fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef script fill:#FFE4C4,stroke:#FF8C00,color:#8B4513
    classDef external fill:#F2F2F2,stroke:#A9A9A9,color:#666666
```
