# kundan0302200-cloud/boxforge architecture

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

- Interactive diagram: https://gitdiagram.com/kundan0302200-cloud/boxforge
- Repository: https://github.com/kundan0302200-cloud/boxforge

## Overview

BoxForge is an educational Linux container runtime. A user invokes `run` directly or through its interactive shell; the CLI builds container configuration and calls the runtime, which clones a namespaced child. The child configures namespaces and an isolated root filesystem, initializes lifecycle handling, then executes the requested command. The parent applies cgroup limits, waits for the child, and removes the cgroup. The README also identifies a BusyBox rootfs helper. Advanced features such as `exec` and OverlayFS are planned, not current runtime components. Edges follow shown calls or README statements; unsampled behavior is not inferred.

Main entry points: [`src/container.c`](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/container.c) (Container Runner), [`src/filesystem.c`](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/filesystem.c) (Root Filesystem Setup), [`src/cgroup.c`](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/cgroup.c) (Resource Limits), [`src/lifecycle.c`](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/lifecycle.c) (Lifecycle Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command Interface"]
  node_cli["Run CLI<br/>[main.c]"]
end

subgraph group_isolation["Container Isolation"]
  node_container["Container Runner<br/>[container.c]"]
  node_namespaces["Namespace Setup<br/>[namespaces.c]"]
  node_filesystem["Root Filesystem Setup<br/>[filesystem.c]"]
end

subgraph group_runtime["Runtime Resources"]
  node_lifecycle["Lifecycle Handling<br/>[lifecycle.c]"]
  node_cgroups["Resource Limits<br/>[cgroup.c]"]
  node_utils["Limit Parsing<br/>[utils.c]"]
end

subgraph group_guest["Guest Environment"]
  node_rootfs["BusyBox Rootfs"]
end

node_user(("Operator"))
node_kernel["Linux Kernel"]
node_workload["Container Command"]

node_user -->|"invokes"| node_cli
node_cli -->|"starts run"| node_container
node_container -->|"sets up"| node_namespaces
node_container -->|"sets up"| node_filesystem
node_container -->|"initializes"| node_lifecycle
node_container -->|"executes"| node_workload
node_container -->|"creates and removes"| node_cgroups
node_container -->|"waits for child"| node_lifecycle
node_cgroups -->|"parses limits"| node_utils
node_namespaces -->|"configures namespaces"| node_kernel
node_filesystem -->|"pivots into"| node_rootfs
node_filesystem -->|"mounts proc"| node_kernel
node_cgroups -->|"writes limits"| node_kernel
node_lifecycle -->|"waits for child"| node_kernel

click node_cli "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/main.c"
click node_container "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/container.c"
click node_namespaces "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/namespaces.c"
click node_filesystem "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/filesystem.c"
click node_lifecycle "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/lifecycle.c"
click node_cgroups "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/cgroup.c"
click node_utils "https://github.com/kundan0302200-cloud/boxforge/blob/main/src/utils.c"
click node_rootfs "https://github.com/kundan0302200-cloud/boxforge/tree/main/rootfs/busybox"

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_cli toneBlue
class node_container,node_namespaces,node_filesystem toneAmber
class node_lifecycle,node_cgroups,node_utils toneMint
class node_rootfs toneRose
class node_user,node_kernel,node_workload toneIndigo
```

## Components

### Command Interface

- [Run CLI](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/main.c): `src/main.c`

### Container Isolation

- [Container Runner](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/container.c): `src/container.c`
- [Namespace Setup](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/namespaces.c): `src/namespaces.c`
- [Root Filesystem Setup](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/filesystem.c): `src/filesystem.c`

### Runtime Resources

- [Lifecycle Handling](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/lifecycle.c): `src/lifecycle.c`
- [Resource Limits](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/cgroup.c): `src/cgroup.c`
- [Limit Parsing](https://github.com/kundan0302200-cloud/boxforge/blob/main/src/utils.c): `src/utils.c`

### Guest Environment

- [BusyBox Rootfs](https://github.com/kundan0302200-cloud/boxforge/tree/main/rootfs/busybox): `rootfs/busybox`

### Other components

- **Operator**
- **Linux Kernel**
- **Container Command**

## Connections

- Operator → Run CLI: invokes (evidence: `README.md`)
- Run CLI → Container Runner: starts run (evidence: `src/main.c`)
- Container Runner → Namespace Setup: sets up (evidence: `src/container.c`)
- Container Runner → Root Filesystem Setup: sets up (evidence: `src/container.c`)
- Container Runner → Lifecycle Handling: initializes (evidence: `src/container.c`)
- Container Runner → Container Command: executes (evidence: `src/container.c`)
- Container Runner → Resource Limits: creates and removes (evidence: `src/container.c`)
- Container Runner → Lifecycle Handling: waits for child (evidence: `src/container.c`)
- Resource Limits → Limit Parsing: parses limits (evidence: `src/cgroup.c`)
- Namespace Setup → Linux Kernel: configures namespaces (evidence: `src/namespaces.c`)
- Root Filesystem Setup → BusyBox Rootfs: pivots into (evidence: `src/filesystem.c`)
- Root Filesystem Setup → Linux Kernel: mounts proc (evidence: `src/filesystem.c`)
- Resource Limits → Linux Kernel: writes limits (evidence: `src/cgroup.c`)
- Lifecycle Handling → Linux Kernel: waits for child (evidence: `src/lifecycle.c`)
