# priya00300/iza-container architecture

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

- Interactive diagram: https://gitdiagram.com/priya00300/iza-container
- Repository: https://github.com/priya00300/iza-container

## Overview

#### Purpose and Entry Point
Iza is a privileged, single-binary Linux container runtime. It manages image root filesystems and launches isolated processes using kernel primitives rather than a daemon or OCI engine. The executable entry point and likely implementation boundary are in `main.cpp`; `Makefile` builds the `iza` binary.

#### Command Dispatcher
The CLI exposes image operations (`pull`, `images`), execution (`run`), and lifecycle operations (`ps`, `stop`, `rm`). `run` accepts resource limits, environment variables, hostname overrides, volume mappings, an image reference, and an optional command. Command parsing and orchestration are centralized in `main.cpp`.

#### Image Acquisition and Local Image Store
Image management downloads minimal Alpine or Ubuntu rootfs archives from remote HTTP sources, then unpacks them into a local image cache. This stage depends on libcurl for retrieval and libarchive for archive extraction. Images are expected beneath `/var/lib/iza/images/<image>/rootfs`, including manually imported rootfs trees. Implementation: `main.cpp`.

#### Container Filesystem Construction
For each run, the runtime creates container-specific writable workspace and combines it with an image rootfs using OverlayFS. The resulting merged filesystem becomes the process root via `chroot` or `pivot_root`; a recursive-copy fallback supports environments where OverlayFS cannot mount. Host volumes cross the isolation boundary as bind mounts into this new mount namespace. Implementation: `main.cpp`.

#### Isolated Process Launch
The runtime creates the container child with raw Linux `clone`, isolating process, mount, network, UTS/hostname, and IPC namespaces. In the child, it prepares the root filesystem, applies hostname and environment settings, mounts requested volumes, then executes the requested command through `execvp`. This is Linux-only and requires root privileges. Implementation: `main.cpp`.

#### Resource Enforcement
Before or during launch, a cgroups v2 manager creates/configures a cgroup under `/sys/fs/cgroup/` and assigns the container process to it. CLI memory and CPU options translate into kernel-enforced limits. The host must expose cgroups v2 controllers; this is a hard infrastructure dependency. Implementation: `main.cpp`.

#### Lifecycle State and Cleanup
The runtime persists container IDs, image references, commands, host PIDs, and status in JSON files under `/var/lib/iza/state/`. `ps` reads this metadata, `stop` resolves an ID or prefix and terminates the tracked process, and `rm` removes state plus OverlayFS mounts and workspace trees. JSON persistence uses jsoncpp. Implementation: `main.cpp`.

Main entry points: [`main.cpp`](https://github.com/priya00300/iza-container/blob/main/main.cpp) (Command dispatcher), [`Makefile`](https://github.com/priya00300/iza-container/blob/main/Makefile) (iza binary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI &amp; lifecycle"]
  node_binary["iza binary<br/>Linux executable"]
  node_dispatcher["Command dispatcher<br/>CLI orchestration<br/>[main.cpp]"]
  node_lifecycle["Lifecycle manager<br/>state operations<br/>[main.cpp]"]
end

subgraph group_images["Image management"]
  node_image_manager["Image manager<br/>image acquisition<br/>[main.cpp]"]
  node_remote_rootfs["Remote rootfs archives<br/>HTTP source"]
  node_image_cache[("Local image cache<br/>rootfs store")]
end

subgraph group_launch["Container launch"]
  node_container_builder["Filesystem builder<br/>rootfs assembly<br/>[main.cpp]"]
  node_volume_mounts["Volume mounts<br/>bind mounts<br/>[main.cpp]"]
  node_container_child["Container child<br/>isolated process<br/>[main.cpp]"]
  node_cgroup_manager["cgroups v2 manager<br/>resource enforcement<br/>[main.cpp]"]
  node_exec(("Workload command<br/>executed process<br/>[main.cpp]"))
end

subgraph group_host["Host kernel &amp; storage"]
  node_state_store[("Container state<br/>JSON metadata store")]
  node_overlayfs["OverlayFS workspace<br/>mount layer"]
  node_linux_namespaces{{"Linux namespaces<br/>kernel isolation"}}
  node_cgroupfs{{"cgroups v2 hierarchy<br/>kernel controller"}}
  node_kernel_root["Container process root<br/>root switch"]
end

node_binary -->|"starts"| node_dispatcher
node_dispatcher -->|"pull / images"| node_image_manager
node_dispatcher -->|"run"| node_container_builder
node_dispatcher -->|"ps / stop / rm"| node_lifecycle
node_image_manager -->|"downloads"| node_remote_rootfs
node_image_manager -->|"extracts rootfs"| node_image_cache
node_container_builder -->|"uses image rootfs"| node_image_cache
node_container_builder -->|"creates merged root"| node_overlayfs
node_container_builder -->|"applies mappings"| node_volume_mounts
node_container_builder -->|"prepares child"| node_container_child
node_container_child -->|"clone isolation"| node_linux_namespaces
node_container_child -->|"chroot / pivot_root"| node_kernel_root
node_volume_mounts -->|"mounts into root"| node_kernel_root
node_kernel_root -->|"execvp"| node_exec
node_dispatcher -->|"resource options"| node_cgroup_manager
node_cgroup_manager -->|"configures limits"| node_cgroupfs
node_cgroup_manager -->|"assigns PID"| node_container_child
node_dispatcher -->|"records container"| node_state_store
node_lifecycle -->|"reads and deletes"| node_state_store
node_lifecycle -->|"terminates tracked PID"| node_container_child
node_lifecycle -->|"unmounts and removes"| node_overlayfs

click node_binary "https://github.com/priya00300/iza-container/blob/main/Makefile"
click node_dispatcher "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_lifecycle "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_image_manager "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_container_builder "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_volume_mounts "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_container_child "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_cgroup_manager "https://github.com/priya00300/iza-container/blob/main/main.cpp"
click node_exec "https://github.com/priya00300/iza-container/blob/main/main.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_binary,node_dispatcher,node_lifecycle toneBlue
class node_image_manager,node_remote_rootfs,node_image_cache toneAmber
class node_container_builder,node_volume_mounts,node_container_child,node_cgroup_manager,node_exec toneMint
class node_state_store,node_overlayfs,node_linux_namespaces,node_cgroupfs,node_kernel_root toneRose
```

## Components

### CLI & lifecycle

- [iza binary](https://github.com/priya00300/iza-container/blob/main/Makefile): Linux executable · Privileged single-binary runtime. · `Makefile`
- [Command dispatcher](https://github.com/priya00300/iza-container/blob/main/main.cpp): CLI orchestration · Handles pull, images, run, ps, stop, and rm. · `main.cpp`
- [Lifecycle manager](https://github.com/priya00300/iza-container/blob/main/main.cpp): state operations · Lists, stops, and removes tracked containers. · `main.cpp`

### Image management

- [Image manager](https://github.com/priya00300/iza-container/blob/main/main.cpp): image acquisition · Downloads and imports rootfs archives. · `main.cpp`
- **Remote rootfs archives**: HTTP source · Minimal Alpine or Ubuntu filesystem archives.
- **Local image cache**: rootfs store · Images reside under /var/lib/iza/images/<image>/rootfs.

### Container launch

- [Filesystem builder](https://github.com/priya00300/iza-container/blob/main/main.cpp): rootfs assembly · Creates writable workspaces and merged container roots. · `main.cpp`
- [Volume mounts](https://github.com/priya00300/iza-container/blob/main/main.cpp): bind mounts · Maps host volumes into the container mount namespace. · `main.cpp`
- [Container child](https://github.com/priya00300/iza-container/blob/main/main.cpp): isolated process · Configures isolation and executes the requested command. · `main.cpp`
- [cgroups v2 manager](https://github.com/priya00300/iza-container/blob/main/main.cpp): resource enforcement · Applies CPU and memory limits and assigns the child PID. · `main.cpp`
- [Workload command](https://github.com/priya00300/iza-container/blob/main/main.cpp): executed process · Command launched through execvp. · `main.cpp`

### Host kernel & storage

- **Container state**: JSON metadata store · Persists IDs, image, command, PID, and status under /var/lib/iza/state/.
- **OverlayFS workspace**: mount layer · Merged rootfs with recursive-copy fallback.
- **Linux namespaces**: kernel isolation · PID, mount, network, UTS, and IPC namespaces via clone.
- **cgroups v2 hierarchy**: kernel controller · Host /sys/fs/cgroup/ controllers.
- **Container process root**: root switch · chroot or pivot_root into the merged filesystem.

## Connections

- iza binary → Command dispatcher: starts
- Command dispatcher → Image manager: pull / images
- Command dispatcher → Filesystem builder: run
- Command dispatcher → Lifecycle manager: ps / stop / rm
- Image manager → Remote rootfs archives: downloads
- Image manager → Local image cache: extracts rootfs
- Filesystem builder → Local image cache: uses image rootfs
- Filesystem builder → OverlayFS workspace: creates merged root
- Filesystem builder → Volume mounts: applies mappings
- Filesystem builder → Container child: prepares child
- Container child → Linux namespaces: clone isolation
- Container child → Container process root: chroot / pivot_root
- Volume mounts → Container process root: mounts into root
- Container process root → Workload command: execvp
- Command dispatcher → cgroups v2 manager: resource options
- cgroups v2 manager → cgroups v2 hierarchy: configures limits
- cgroups v2 manager → Container child: assigns PID
- Command dispatcher → Container state: records container
- Lifecycle manager → Container state: reads and deletes
- Lifecycle manager → Container child: terminates tracked PID
- Lifecycle manager → OverlayFS workspace: unmounts and removes