# sativarsainath-26/runq architecture

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

- Interactive diagram: https://gitdiagram.com/sativarsainath-26/runq
- Repository: https://github.com/sativarsainath-26/runq

## Overview

##### Main Components Identification
- Host-side Components:
- Docker CLI, Docker daemon, and docker-containerd-shim that trigger containers.
- runq “proxy” (cmd/proxy) that is the entry point in the container. This component starts Qemu, configures network ports, mounts storage, and manages signals. Display it as the bridge between Docker and the VM guest.
- runq-exec (cmd/runq-exec) used for executing commands in running containers.
- nsenter (cmd/nsenter) for entering namespaces.
- External dependencies such as TLS certificates, the vhost_vsock module, and device configurations.
- Qemu binary and related configuration files in the “qemu” and “initrd” directories. These are set up under /var/lib/runq/qemu.
- VM Guest Components:
- The runq “init” process (cmd/init) that is the first process (PID 1) in the VM guest.
- The guest kernel booted by Qemu.
- The actual application container that runs inside the VM guest.
- Devices and storage components (devices such as block, virtio-blk, 9pfs-mounted filesystems, and network interfaces) that are attached inside the VM.
- Supporting and Shared Libraries:
- Utility packages and core packages (internal/ and pkg/vm) that provide configuration, loopback, kernel modules, etc.
- Build scripts and Makefiles spread across the project that streamline the development and integration.

##### Relationships and Interactions
- Docker client invoking the Docker daemon that passes the container specification to the runq runtime.
- From the Docker daemon, illustrate two execution paths:
a) Traditional runc container (for coexistence) and
b) The runq container where the proxy initiates a VM “guest”.
- Within the VM guest, illustrate how the “init” process sets up networking (creating namespaces, mounting disks, etc.) and finally launches the application. Show how runq-exec later interacts with the running guest via Vsock and TLS.
- Role of Qemu in providing the virtual hardware (network, disk, and CPU emulation) and show that the Qemu binaries and container kernel images come from the “qemu” directory. Also note that the “initrd” prepares the boot image.
- Relationships for storage management (volumes, rootdisk, and devices) and network configuration (macvtap, virtio, and even possibility for macvlan).

##### Architectural Patterns and Design Principles
- Separation between host and guest execution environments.
- That runq adheres to a minimalistic design where it integrates with Docker without modifying existing Docker tools.
- How multiple commands and configuration files (like TLS setup and seccomp profiles) contribute to security and isolation.

##### Relevant Technologies and Frameworks
- Docker integration (runc, containerd, Docker API).
- Linux KVM, Qemu, and virtio components.
- TLS security for runq-exec client authentication.
- Network bridging through macvtap and DNS proxying when needed.
- The use of bind mounts for loader modules into the VM.
- Libseccomp usage for sandboxing.

##### Instructing the Principal Software Engineer
[Docker CLI] → [Docker daemon/containerd shim] → [runq proxy (cmd/proxy)]
│
▼
[Qemu (with custom configurations)]
│
▼
[VM Guest: runq init (cmd/init) → Application]
Additionally, show the side processes:
- nsenter (for namespace entry)
- Qemu’s use of separate volumes and configuration directories.
- Clear labels for each component.
- Adding annotations that reference specific assembly points based on directory names (for instance, the qemu, initrd, internal, and pkg directories) to underline where the components originate.
- Every component’s purpose—for instance, that the “proxy” is effectively an enhanced Docker entry point that triggers Qemu, and “init” is the VM’s startup process.
- Host components vs. guest components.
- Core runtime binaries (cmd/* components) vs. supporting libraries (internal/* and pkg/*).
- External integrations (Docker, TLS, network interfaces, storage attachments).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Environment
    subgraph "Host Environment"
        CLI["Docker CLI"]:::host
        DAEMON["Docker daemon/containerd shim"]:::host
        RUNC["Traditional runc Container"]:::host
        PROXY["runq proxy (cmd/proxy)"]:::host
        EX["runq-exec (cmd/runq-exec)"]:::host
        NS["nsenter (cmd/nsenter)"]:::host
        subgraph "Supporting Libraries"
            INTERNAL["Internal (internal)"]:::lib
            VMPKG["VM Packages (pkg/vm)"]:::lib
        end
        %% Qemu Setup subgraph
        subgraph "Qemu Setup"
            QEMU["Qemu Binary (qemu)"]:::host
            INITRD["initrd Boot Image (initrd)"]:::host
        end
    end

    %% VM Guest Environment
    subgraph "VM Guest Environment"
        INITPROC["runq init (cmd/init)"]:::guest
        APP["Application Container"]:::guest
    end

    %% External Dependencies
    EXT["TLS & Vsock Security"]:::external

    %% Relationships in Host Environment
    CLI -->|"triggers"| DAEMON
    DAEMON -->|"executes"| RUNC
    DAEMON -->|"selects runtime"| PROXY
    INTERNAL --> PROXY
    VMPKG --> PROXY
    PROXY -->|"launches"| QEMU
    QEMU -->|"uses"| INITRD
    NS --- PROXY

    %% Transition from Host to VM Guest
    INITRD -->|"boots"| INITPROC
    INITPROC -->|"starts"| APP

    %% runq-exec communication with VM Guest (secured)
    EX <-->|"TLS/Vsock"| INITPROC

    %% Legend (for clarity)
    subgraph "Legend"
        L1["Host Component"]:::hostLegend
        L2["Guest Component"]:::guestLegend
        L3["Supporting Library"]:::libLegend
        L4["External Dependency"]:::externalLegend
    end

    %% Click Events
    click PROXY "https://github.com/sativarsainath-26/runq/tree/master/cmd/proxy"
    click EX "https://github.com/sativarsainath-26/runq/tree/master/cmd/runq-exec"
    click NS "https://github.com/sativarsainath-26/runq/tree/master/cmd/nsenter"
    click QEMU "https://github.com/sativarsainath-26/runq/tree/master/qemu"
    click INITRD "https://github.com/sativarsainath-26/runq/tree/master/initrd"
    click INITPROC "https://github.com/sativarsainath-26/runq/tree/master/cmd/init"
    click INTERNAL "https://github.com/sativarsainath-26/runq/tree/master/internal"
    click VMPKG "https://github.com/sativarsainath-26/runq/tree/master/pkg/vm"

    %% Styles
    classDef host fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef guest fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef lib fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef hostLegend fill:#cce5ff,stroke:#004085,stroke-width:1px,font-size:10px;
    classDef guestLegend fill:#d4edda,stroke:#155724,stroke-width:1px,font-size:10px;
    classDef libLegend fill:#fff3cd,stroke:#856404,stroke-width:1px,font-size:10px;
    classDef externalLegend fill:#f8d7da,stroke:#721c24,stroke-width:1px,font-size:10px;
```
