# netbsdfr/smolbsd architecture

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

- Interactive diagram: https://gitdiagram.com/netbsdfr/smolbsd
- Repository: https://github.com/netbsdfr/smolbsd

## Overview

##### Project Type and Purpose
- This project is a specialized, minimalistic operating system image builder that creates a microVM based on NetBSD. Its primary goal is to generate a bootable NetBSD virtual machine that starts a designated service (such as a rescue shell, bozohttpd, nginx, etc.) in under a second. It supports building images on both NetBSD and GNU/Linux hosts and targets different architectures (amd64, i386, aarch64, etc.).
- There is also a simple Python/Flask-based frontend in the app/ directory that provides basic virtual machine management, and some Kubernetes (k8s) resources for containerized use cases.

##### File Structure and Key Components
- Top-level directories like .github indicate CI/CD integration, while the k8s folder shows that there is support for containerized deployment.
- The “app” directory contains a Flask application for a basic virtual machine manager, which exposes a web GUI.
- The “bios” folder holds binary firmware images used to boot the microVM.
- The “etc” folder provides various preconfigured configuration files (live.conf, rescue.conf, etc) needed by the VM.
- The “service” directory is the heart of the service configuration. Here, each service (e.g., rescue, bozohttpd, nbakery, runbsd, systembsd, etc.) has its own folder structure:
- Each service provides its own /etc/rc scripts to specify what to start on boot (executed inside the microVM).
- Some services also include “postinst” scripts, executed on the build host to perform final image customization.
- There’s also a “common” subdirectory that contains scripts (like basicrc) meant to be bundled into the final image.
- Scripts like "mkimg.sh" and "startnb.sh" are the build and boot scripts respectively:
- mkimg.sh is used to create the root filesystem image by combining the selected sets (e.g., rescue.tgz, base.tgz) with service-specific configuration.
- startnb.sh is used to boot the microVM via QEMU (or compatible hypervisors) with the given kernel and image.
- Other utility files include the Makefile that simplifies the build process (e.g., make rescue, make base) and additional support scripts.

##### Main Components & Interactions
a. Host Build Environment:
- Build Host Tools (GNU/Linux/NetBSD): Contains build scripts (mkimg.sh, Makefile) and configuration files (etc/*, service/*).
- Post-Installation Scripts: Represent the postinst processes for each service.
b. MicroVM Image & Boot Components:
- Filesystem Sets: "sets" directory or provided tgz sets that become part of the root image.
- Boot Scripts inside the image: The service “etc/rc” files that trigger service startup on boot.
- Firmware/Bios: Items in the bios/ directory, loaded to boot the microVM.
c. Service Modules:
- Individual Service Configs: Service definitions for rescue, bozohttpd, nbakery, etc., each containing service-specific startup and configuration files.
- Common Scripts: Scripts from service/common (e.g., basicrc) that are included in all services to standardize configuration.
d. Virtual Machine Manager:
- The Python/Flask application (app/app.py) that provides a web UI for managing and launching microVMs.
e. Deployment/Orchestration:
- Kubernetes integration: Components in the k8s/ directory (Dockerfile, YAML files) that can be used for container orchestration/deployment.
f. External Tools/Dependencies:
- QEMU and other VM technology for direct booting.
- Network configuration (ifconfig scripts, routing configuration in basicrc).

##### Architectural Patterns & Design Principles
- Separation of Build-Time and Runtime Responsibilities:
- Post-install scripts (executed on the build host) vs. runtime initialization scripts (executed inside the microVM).
- Modular Service Design:
- Each service is self-contained with its configuration and boot scripts, making it easier to swap or extend services.
- Minimalism & Performance Optimization:
- Focused on creating a minimal image with fast boot times through optimizations like direct kernel booting using PVH.
- Extensibility:
- Using common directories (like service/common) and a clear directory structure for adding new services or modifying existing ones.
- Multi-Architecture Support:

##### Instructing the Principal Software Engineer
- Rectangles for scripts and modules.
- Annotations noting significant design patterns, such as “Build-time vs Runtime Concerns”, “Modular Service Architecture”, or “Direct Kernel Boot via PVH”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build Host Environment"
        mkimg("mkimg.sh"):::build
        makefile("Makefile"):::build
        etcConfig("Configuration (etc/*)"):::build
    end

    subgraph "Post-install Scripts"
        basePost("service/base/postinst"):::post
        bozoPost("service/bozohttpd/postinst"):::post
        imgbuilderPost("service/imgbuilder/postinst"):::post
        runbsdPost("service/runbsd/postinst"):::post
        systembsdPost("service/systembsd/postinst"):::post
    end

    subgraph "MicroVM Boot Components"
        subgraph "Firmware/Bios"
            bios1("bios/bios-microvm.bin"):::firmware
            bios2("bios/pvh.bin"):::firmware
        end
        startnb("VM Boot Execution (startnb.sh)"):::boot
    end

    subgraph "Service Modules"
        subgraph "Service Runtime Configurations"
            baseRc("service/base/etc/rc"):::service
            bozoRc("service/bozohttpd/etc/rc"):::service
            nbakeryRc("service/nbakery/etc/rc"):::service
            rescueRc("service/rescue/etc/rc"):::service
            runbsdRc("service/runbsd/etc/rc"):::service
            systembsdRc("service/systembsd/etc/rc"):::service
        end
        subgraph "Common Service Scripts"
            common("Common Scripts (basicrc, pkgin, shutdown)"):::service
        end
    end

    manager("Flask App (app/app.py)"):::manager
    k8sResource("k8s Resources"):::k8s

    %% Interconnections
    %% Build Host Environment triggers image creation
    mkimg -->|"builds image"| startnb
    makefile -->|"orchestrates"| mkimg
    etcConfig -->|"provides configs"| mkimg

    %% Build Host also runs post-install scripts during image build
    mkimg -->|"executes"| basePost
    mkimg -->|"executes"| bozoPost
    mkimg -->|"executes"| imgbuilderPost
    mkimg -->|"executes"| runbsdPost
    mkimg -->|"executes"| systembsdPost

    %% Firmware/Bios are required for boot execution
    bios1 -->|"supplies firmware"| startnb
    bios2 -->|"supplies firmware"| startnb

    %% Boot process initiates service runtime configurations inside the image
    startnb -->|"boots and triggers"| baseRc
    startnb -->|"boots and triggers"| bozoRc
    startnb -->|"boots and triggers"| nbakeryRc
    startnb -->|"boots and triggers"| rescueRc
    startnb -->|"boots and triggers"| runbsdRc
    startnb -->|"boots and triggers"| systembsdRc
    startnb -->|"includes"| common

    %% External control via Virtual Machine Manager and Kubernetes
    manager -->|"launches VM"| startnb
    k8sResource -->|"orchestrates VM"| startnb

    %% Styling definitions
    classDef build fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef post fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef firmware fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef boot fill:#ccf2f4,stroke:#333,stroke-width:2px;
    classDef service fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef manager fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef k8s fill:#f5c6cb,stroke:#333,stroke-width:2px;

    %% Click Events
    click mkimg "https://github.com/netbsdfr/smolbsd/blob/main/mkimg.sh"
    click makefile "https://github.com/netbsdfr/smolbsd/tree/main/Makefile"
    click etcConfig "https://github.com/netbsdfr/smolbsd/tree/main/etc/"
    click basePost "https://github.com/netbsdfr/smolbsd/tree/main/service/base/postinst"
    click bozoPost "https://github.com/netbsdfr/smolbsd/tree/main/service/bozohttpd/postinst"
    click imgbuilderPost "https://github.com/netbsdfr/smolbsd/tree/main/service/imgbuilder/postinst"
    click runbsdPost "https://github.com/netbsdfr/smolbsd/tree/main/service/runbsd/postinst"
    click systembsdPost "https://github.com/netbsdfr/smolbsd/tree/main/service/systembsd/postinst"
    click bios1 "https://github.com/netbsdfr/smolbsd/blob/main/bios/bios-microvm.bin"
    click bios2 "https://github.com/netbsdfr/smolbsd/blob/main/bios/pvh.bin"
    click startnb "https://github.com/netbsdfr/smolbsd/blob/main/startnb.sh"
    click baseRc "https://github.com/netbsdfr/smolbsd/tree/main/service/base/etc/rc"
    click bozoRc "https://github.com/netbsdfr/smolbsd/tree/main/service/bozohttpd/etc/rc"
    click nbakeryRc "https://github.com/netbsdfr/smolbsd/tree/main/service/nbakery/etc/rc"
    click rescueRc "https://github.com/netbsdfr/smolbsd/tree/main/service/rescue/etc/rc"
    click runbsdRc "https://github.com/netbsdfr/smolbsd/tree/main/service/runbsd/etc/rc"
    click systembsdRc "https://github.com/netbsdfr/smolbsd/tree/main/service/systembsd/etc/rc"
    click common "https://github.com/netbsdfr/smolbsd/tree/main/service/common"
    click manager "https://github.com/netbsdfr/smolbsd/blob/main/app/app.py"
    click k8sResource "https://github.com/netbsdfr/smolbsd/tree/main/k8s"
```
