# peaspilaf/keksule architecture

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

- Interactive diagram: https://gitdiagram.com/peaspilaf/keksule
- Repository: https://github.com/peaspilaf/keksule

## Overview

##### Project type and purpose
- This is a command‐line, system‐level container manager written in C.
- It provides a small library (`libcapsule`) plus a `main.c` wrapper that uses Linux namespaces, cgroups, pivot_root, and mount syscalls to launch an isolated “container” process.
- There’s also an example shell script (`unshare_example.sh`) showing a manual namespace setup.

##### File structure
- Top‐level:
- control_group.md & namespaces.md – docs on cgroups & namespaces
- README.md – project overview & build/run instructions
- `/src`:
- `libcapsule/` – C API (`libcapsule.h`) and implementation (`libcapsule.c`) for container setup
- `main.c` – CLI entry point that calls into `libcapsule`
- `unshare_example.sh` – standalone shell demo using `unshare`

##### Key architectural insights from the README
- The system is a single executable + a library that wraps low‐level Linux features.
- No networked microservices or databases—everything lives on one host.
- Relies on kernel subsystems: namespaces, cgroups, pivot_root, devtmpfs, procfs.

##### Diagramming the architecture
a. Main components:
1. User (invokes CLI)
2. Capsule CLI binary (`main.c`)
3. `libcapsule` library:
- Namespace manager
- Cgroup manager
- Filesystem manager (pivot_root, mounts)
4. Linux kernel subsystems:
- Namespaces (PID, MNT, NET, IPC, UTS, USER)
- Cgroups (via cgroup filesystem)
- VFS (pivot_root, mount)
- devtmpfs, procfs
5. Containerized process (the target command + its children)
6. unshare_example.sh (side‐by‐side manual demo)

b. Relationships & interactions:
- User → invokes `capsule` binary
- CLI → calls into `libcapsule` API
- `libcapsule` → makes syscall wrappers to:
- unshare() → isolates namespaces
- mount()/pivot_root() → builds new root FS, mounts devtmpfs+proc
- write to cgroup fs → limit resources
- Kernel → applies isolation, returns a PID in new namespace
- Capsule (via `execve`) → launches final container process

c. Architectural patterns/design principles:
- Separation of concerns: CLI vs. library vs. kernel interface
- Layered design: User → User-space library → Kernel
- Single‐binary, minimal dependencies

d. Relevant technologies/frameworks:
- C standard library
- Linux syscalls: unshare, mount, pivot_root, setns, chroot (via pivot_root)
- cgroup v1/v2 interfaces in `/sys/fs/cgroup`
- devtmpfs, procfs mounts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (CLI invocation)"]:::user
    Capsule["Capsule Binary (main.c)"]:::user
    User -->|"invokes"| Capsule

    %% libcapsule Library Layer
    subgraph "libcapsule Library"
        Namespaces["Namespace Manager"]:::user
        Cgroups["Cgroup Manager"]:::user
        Filesystem["Filesystem Manager"]:::user
    end
    Capsule -->|"calls API"| Namespaces
    Capsule -->|"calls API"| Cgroups
    Capsule -->|"calls API"| Filesystem

    %% Kernel Layer
    subgraph "Linux Kernel"
        KS_NS["Namespaces (PID, MNT, NET, IPC, UTS, USER)"]:::kernel
        KS_CG["Cgroups (/sys/fs/cgroup)"]:::kernel
        KS_VFS["VFS (pivot_root, mount)"]:::kernel
        KS_DEV["devtmpfs, procfs"]:::kernel
    end
    Namespaces -->|"unshare(CLONE_NEW*)"| KS_NS
    Cgroups -->|"write /sys/fs/cgroup"| KS_CG
    Filesystem -->|"pivot_root+mount"| KS_VFS
    Filesystem -->|"mount devtmpfs+procfs"| KS_DEV

    %% Container Process
    Container["Container Process (execve target)"]:::container
    KS_NS --> Container
    KS_CG --> Container
    KS_VFS --> Container
    KS_DEV --> Container

    %% Manual Demo
    subgraph "Manual Demo"%% dashed
        direction TB
        Manual["unshare_example.sh"]:::manual
    end
    Manual -->|"unshare(CLONE_NEW*)"| KS_NS
    Manual -->|"mount commands"| KS_VFS

    %% Documentation
    subgraph "Documentation"
        DocCG["control_group.md"]:::user
        DocNS["namespaces.md"]:::user
        DocRD["README.md"]:::user
    end

    %% Click Events
    click Capsule "https://github.com/peaspilaf/keksule/blob/main/src/main.c"
    click Namespaces "https://github.com/peaspilaf/keksule/blob/main/src/libcapsule/libcapsule.c"
    click Cgroups "https://github.com/peaspilaf/keksule/blob/main/src/libcapsule/libcapsule.c"
    click Filesystem "https://github.com/peaspilaf/keksule/blob/main/src/libcapsule/libcapsule.c"
    click Manual "https://github.com/peaspilaf/keksule/blob/main/src/unshare_example.sh"
    click DocCG "https://github.com/peaspilaf/keksule/blob/main/control_group.md"
    click DocNS "https://github.com/peaspilaf/keksule/blob/main/namespaces.md"
    click DocRD "https://github.com/peaspilaf/keksule/blob/main/README.md"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#005B9F,color:#000;
    classDef kernel fill:#DFFFD0,stroke:#4F8F00,color:#000;
    classDef container fill:#E0E0E0,stroke:#666,color:#000;
    classDef manual stroke-dasharray: 5 5,fill:none,stroke:#005B9F,color:#005B9F;
```
