# mfernd/cloudlet architecture

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

- Interactive diagram: https://gitdiagram.com/mfernd/cloudlet
- Repository: https://github.com/mfernd/cloudlet

## Overview

##### Project Type and Purpose
- Cloudlet is a lightweight FaaS (Function-as-a-Service) orchestration system written in Rust.
- It comprises several Rust crates (workloads):
- CLI (user-facing client)
- API (HTTP server)
- VMM (virtual machine manager using gRPC)
- Agent (runs inside the VM, also gRPC)
- FS-gen (initramfs and image builder)
- shared-models and proto definitions (gRPC schemas)
- The system let users submit code (Rust, Python, Node), spins up a VM, builds and runs it inside the VM’s Agent, and streams back results.

##### High-Level File Structure Analysis
- Top-level Cargo workspace: Cargo.toml, Justfile, proto/, assets/, tools/
- src/agent/: code builder & runner inside the VM
- src/api/: HTTP→gRPC façade for clients
- src/cli/: command-line interface for end users
- src/fs-gen/: kernel/initramfs/image generation tooling
- src/vmm/: hypervisor orchestration, gRPC server & client
- src/shared-models and proto/: shared message definitions

##### Key Architecture Insights from README
- Flow: CLI → HTTP to API → gRPC to VMM → VM boot → Agent gRPC → code build & run → response streams back
- Components communicate over HTTP (CLI↔API) and gRPC (API↔VMM, VMM↔Agent)
- Tools/ contains shell scripts to build Linux kernel & rootfs for the VM

##### Components
a. External Client
- CLI binary (src/cli/)
b. API Service
- HTTP server (src/api/)
c. VMM Service
- gRPC server (src/vmm/)
- Hypervisor module (VM creation, networking, epoll)
d. Agent inside VM
- Agent gRPC server (src/agent/)
- Workload builder & runner
e. Image Generation Tool
- FS-gen (kernel/initramfs builder)
f. Shared Models & Proto
- Shared message definitions (proto/, src/shared-models/)
g. Underlying Infrastructure
- Host OS capabilities (cap_net_admin, iptables)
- Virtual networking (tuntap, virtio)

##### Interactions and Data Flow
- HTTP request from CLI → API
- API translates HTTP to gRPC → VMM
- VMM invokes host hypervisor APIs to create VM
- VMM loads kernel + initramfs (built by FS-gen) into VM
- VM boots into Agent binary
- VMM calls Agent gRPC endpoint to send workload config & source path
- Agent compiles & runs code inside VM, streams stdout/stderr back via gRPC
- VMM relays gRPC stream → API → HTTP response → CLI

##### Architectural Patterns & Principles
- Microservice-style Rust crates communicating over defined interfaces (HTTP, gRPC)
- Clear separation of concerns:
- CLI only handles user I/O
- API handles external HTTP endpoints and authentication/validation
- VMM handles VM lifecycle & networking
- Agent handles in-VM build/run isolation
- FS-gen decouples image creation
- Shared Protobuf definitions ensure consistency across service boundaries
- Use of capabilities (capsh, iptables) for secure VM networking

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Layers
    subgraph "User Interface"
        direction TB
        CLI["CLI\n(src/cli)"]:::frontend
    end

    subgraph "Control Plane"
        direction TB
        API["API Service\n(src/api)"]:::api
        VMM["VMM Service\n(src/vmm)"]:::grpc
        FS["FS-gen Tool\n(src/fs-gen)"]:::image
        Shared["Shared Models & Proto\n(proto/, src/shared-models)"]:::model
        Tools["Infra Scripts\n(tools/)"]:::infra
    end

    subgraph "VM Instance"
        direction TB
        Kernel["Kernel Image"]:::artifact
        Initramfs["Initramfs Image"]:::artifact
        Agent["Agent Service\n(src/agent)"]:::grpc
    end

    %% Data Flows
    CLI -->|"HTTP"| API
    API -->|"gRPC"| VMM
    VMM -->|"load Kernel"| Kernel
    VMM -->|"load Initramfs"| Initramfs
    FS -->|"image build"| VMM
    Tools -->|"build scripts"| FS
    Shared -->|"proto definitions"| API
    Shared -->|"proto definitions"| VMM
    Shared -->|"proto definitions"| Agent
    VMM -->|"gRPC"| Agent
    Agent -->|"gRPC stream"| VMM
    VMM -->|"gRPC"| API
    API -->|"HTTP"| CLI

    %% Legend
    subgraph "Legend"
        direction TB
        L1["HTTP"]:::httpLine
        L2["gRPC"]:::grpcLine
        L3["VM Ops"]:::vmLine
        L4["Frontend Service"]:::frontend
        L5["API Service"]:::api
        L6["gRPC Service"]:::grpc
        L7["Image Builder"]:::image
        L8["Model Definitions"]:::model
        L9["Infrastructure"]:::infra
        L10["Artifact"]:::artifact
    end

    %% Click Events
    click CLI "https://github.com/mfernd/cloudlet/tree/main/src/cli/"
    click API "https://github.com/mfernd/cloudlet/tree/main/src/api/"
    click VMM "https://github.com/mfernd/cloudlet/tree/main/src/vmm/"
    click FS "https://github.com/mfernd/cloudlet/tree/main/src/fs-gen/"
    click Shared "https://github.com/mfernd/cloudlet/tree/main/src/shared-models/"
    click Shared "https://github.com/mfernd/cloudlet/tree/main/proto/"
    click Agent "https://github.com/mfernd/cloudlet/tree/main/src/agent/"
    click Tools "https://github.com/mfernd/cloudlet/tree/main/tools/"

    %% Styles
    classDef frontend fill:#E8EAF6,stroke:#1A237E,color:#1A237E,stroke-width:1px;
    classDef api fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1,stroke-width:1px;
    classDef grpc fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20,stroke-width:1px;
    classDef image fill:#FFF3E0,stroke:#E65100,color:#E65100,stroke-width:1px;
    classDef model fill:#F3E5F5,stroke:#4A148C,color:#4A148C,stroke-width:1px;
    classDef infra fill:#ECEFF1,stroke:#37474F,color:#37474F,stroke-width:1px;
    classDef artifact fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C,stroke-width:1px;

    classDef httpLine stroke:#1E88E5,stroke-width:2px,stroke-dasharray: 5 5;
    classDef grpcLine stroke:#43A047,stroke-width:2px,stroke-dasharray: 2 2;
    classDef vmLine stroke:#FB8C00,stroke-width:2px,stroke-dasharray: 3 3;

    class CLI,API,L1 httpLine;
    class API,VMM,L2 grpcLine;
    class VMM,Kernel,Initramfs,L3 vmLine;
```
