# youki-dev/youki architecture

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

- Interactive diagram: https://gitdiagram.com/youki-dev/youki
- Repository: https://github.com/youki-dev/youki

## Overview

##### Project Type and Purpose
- youki is a systems‐level, open-source container runtime written in Rust. It implements the OCI runtime-spec (like runc), providing CLI commands to create, start, stop, and delete containers, and a set of Rust libraries to handle cgroups, namespaces, rootfs mounting, seccomp filters, and optional WebAssembly workloads.

##### File-Structure Analysis
Top-level crates/ modules:
- crates/libcgroups – a library abstracting cgroup v1/v2 controllers, with both direct FS and systemd/DBus backends.
- crates/libcontainer – the heart of container construction and lifecycle: builders for namespaces, capabilities, mounts, seccomp, rootfs, etc.
- crates/liboci-cli – a thin library parsing OCI spec JSON, providing the CLI command definitions (create, start, delete, state, exec, etc.).
- crates/youki – the binary glue that wires liboci-cli + libcontainer + libcgroups into the youki CLI executable; also implements workload executors (native process, WasmEdge, Wasmer, Wasmtime).
Other areas:
– scripts/ and justfile – automation of builds, tests, releases.
– tests/ – e2e/integration tests, contest framework, OCI-runtime-tests, etc.
– experiment/ – playgrounds for seccomp or SELinux prototypes.
– CI configs (.github/workflows/**/*.yml), devcontainer, Vagrantfile, cross (multi-arch build).

##### README Insights
- Confirms youki’s goal: a safe, fast, low-overhead OCI runtime in Rust.
- Points to an architecture SVG in docs.
- Describes command-line usage, system dependencies (libseccomp, systemd, DBus), and supported features (rootless, WebAssembly workloads, cgroup managers).

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Cargo Workspace
  subgraph "Cargo Workspace"
    direction TB
    subgraph "CLI Layer"
      direction TB
      YO["youki CLI Binary"]:::cli
      CM["youki CLI Commands"]:::cli
      OC["OCI-Spec CLI Parser (liboci-cli)"]:::cli
      OBS["Observability & Logging"]:::cli
      CR["Configuration & Paths Helper"]:::cli
    end
    subgraph "Core Libraries"
      direction TB
      LC["Core Container Library (libcontainer)"]:::core
      CG["Cgroup Subsystem (libcgroups)"]:::core
    end
  end

  %% libcontainer internal modules
  subgraph "libcontainer Components"
    direction TB
    NB["Namespace Builder"]:::sub
    RM["Rootfs Management"]:::sub
    CP["Capability Management"]:::sub
    HM["Hook Manager"]:::sub
    SC["Seccomp Support"]:::sub
    SY["Syscall Interface"]:::sub
    WE["Workload Executors"]:::sub
  end

  %% External and kernel
  K["Linux Kernel"]:::kernel
  subgraph "External Services"
    direction TB
    SD["systemd/DBus"]:::ext
    FS["Cgroup FS"]:::ext
    DO["Docker/Containerd"]:::ext
  end

  %% Tests and docs
  subgraph "Testing & CI"
    direction TB
    TF["Test Framework Library"]:::test
    OCIT["OCI-runtime-tests Integration"]:::test
    CI["CI Workflows & Config"]:::doc
    SCR["Automation Scripts & Build Helpers"]:::doc
    DOC["User/Dev Documentation"]:::doc
  end

  %% Connections
  YO -->|"parses args"| OC
  YO -->|"invokes commands"| CM
  CM -->|"calls APIs"| LC
  OC -->|"provides spec JSON"| CM
  LC -->|"uses cgroup lib"| CG
  LC -->|"invokes seccomp"| SC
  LC -->|"uses namespace builder"| NB
  LC -->|"manages rootfs"| RM
  LC -->|"manages capabilities"| CP
  LC -->|"runs hooks"| HM
  LC -->|"syscall layer"| SY
  YO -->|"executes workload"| WE

  SY -->|"syscalls (fork, clone, mount)"| K
  SC -->|"seccomp filters"| K
  CG -->|"direct FS"| FS
  CG -->|"via DBus"| SD
  WE -->|"user process"| K

  TF -->|"tests CLI"| YO
  OCIT -->|"conformance tests"| YO

  CI -->|"CI harness"| TF
  SCR -->|"build scripts"| YO
  DOC -->|"architecture SVG"| DOC

  %% Click Events
  click YO "https://github.com/youki-dev/youki/blob/main/crates/youki/src/main.rs"
  click CM "https://github.com/youki-dev/youki/tree/main/crates/youki/src/commands"
  click OC "https://github.com/youki-dev/youki/tree/main/crates/liboci-cli"
  click CG "https://github.com/youki-dev/youki/tree/main/crates/libcgroups"
  click LC "https://github.com/youki-dev/youki/tree/main/crates/libcontainer"
  click WE "https://github.com/youki-dev/youki/blob/main/crates/youki/src/workload/{executor.rs, wasmedge.rs, wasmer.rs, wasmtime.rs}"
  click SC "https://github.com/youki-dev/youki/tree/main/crates/libcontainer/src/seccomp"
  click NB "https://github.com/youki-dev/youki/blob/main/crates/libcontainer/src/namespaces.rs"
  click RM "https://github.com/youki-dev/youki/tree/main/crates/libcontainer/src/rootfs"
  click CP "https://github.com/youki-dev/youki/blob/main/crates/libcontainer/src/capabilities.rs"
  click HM "https://github.com/youki-dev/youki/blob/main/crates/libcontainer/src/hooks.rs"
  click SY "https://github.com/youki-dev/youki/tree/main/crates/libcontainer/src/syscall"
  click OBS "https://github.com/youki-dev/youki/blob/main/crates/youki/src/observability.rs"
  click CR "https://github.com/youki-dev/youki/blob/main/crates/youki/src/rootpath.rs"
  click TF "https://github.com/youki-dev/youki/tree/main/tests/contest/test_framework"
  click OCIT "https://github.com/youki-dev/youki/tree/main/tests/oci-runtime-tests"
  click DOC "https://github.com/youki-dev/youki/tree/main/docs/"
  click SCR "https://github.com/youki-dev/youki/tree/main/scripts/"
  click CI "https://github.com/youki-dev/youki/tree/main/.github/workflows/"

  %% Styles
  classDef cli fill:#ffcccc,stroke:#cc0000,color:#330000;
  classDef core fill:#ccffcc,stroke:#006600,color:#003300;
  classDef sub fill:#cceeff,stroke:#0044cc,color:#001133;
  classDef kernel fill:#ffebcc,stroke:#cc9900,color:#663300;
  classDef ext fill:#e0e0e0,stroke:#666666,color:#333333;
  classDef test fill:#f0d0ff,stroke:#9900cc,color:#330033;
  classDef doc fill:#ffffcc,stroke:#cccc00,color:#333300;
```
