# bjakobson/webboot architecture

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

- Interactive diagram: https://gitdiagram.com/bjakobson/webboot
- Repository: https://github.com/bjakobson/webboot

## Overview

##### Main Components
- Bootloader Command Modules: Represent the multiple commands under the cmds directory (for example, cmds/cli, cmds/webboot, and cmds/wifiDebug). Highlight that webboot is the central CLI tool to trigger the boot process.
- ISO Processing and Boot Infrastructure: Show the pkg modules (e.g., pkg/bootiso handles mounting, extracting kernels/initrds; pkg/menu helps with UI/menu logic; pkg/dhclient, pkg/wifi, pkg/wpa provide networking and wireless support).
- Cache/Local File Storage: Include a component for managing cached ISO files (the README describes saving downloaded ISOs to local caches like a USB stick).
- External Dependencies & u-root Integration: Emphasize that the project bootstraps a u-root initramfs with webboot’s binary and other files. Indicate integration with u-root and additional configuration (e.g., build image tools, integration tests).

##### Relationships and Interactions
- Data Flow from User/Console → CLI Module: Illustrate that when a user runs the “webboot” command, the CLI first fetches an ISO from the web.
- ISO Mounting and Kernel Extraction: From the ISO module, show a branch to “ISO Parsing & Extraction” (parts of pkg/bootiso and integration tests) that deals with mounting the ISO, extracting the kernel and initrd, and processing kernel parameters.
- Networking and Wireless Support: Represent modules for handling network configuration (pkg/dhclient, pkg/wifi, pkg/wpa) which the boot process relies on, particularly when booting in environments where a network must be set up.
- Final Boot via kexec: Illustrate how the extracted kernel and initrd are passed to a “Kernel Loader” component that uses kexec to boot the operating system.
- UI Integration: Include a component for the terminal UI (via termui) that sits on top of the CLI and gives a visual interface for selecting and booting distros.

##### Architectural Patterns and Design Principles
- Modular Structure: Emphasize how the code is organized in separate modules (e.g., cmds, pkg) to decouple the boot process steps.
- Command/Controller Pattern: The “cmds” directory is a good indicator of a command pattern where each subcommand encapsulates a particular function.
- Plugin-like Extensibility: Note how supported distros are added via a mapping (the “supportedDistros” map in cmds/webboot/types.go) and how configurations can be overridden, suggesting an extensible architecture.
- Integration with External Tools: The design shows clear separation between the build/initramfs process (via u-root) and the boot logic.

##### Relevant Technologies
- Go Language as the primary implementation.
- Several Go packages for booting (u-root), network management, ISO processing.
- Use of termui for the CLI interface.
- CI/CD pipelines and GitHub Actions for workflow.
- Syslinux for USB booting as described in the README.

##### Final Touches
- Components have clear labels.
- How the integration tests (integration/ directory and pkg test files) verify these modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U["User/Console"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI_TermUI["CLI/TermUI"]:::frontend
        UI_Menu["UI/Menu Infrastructure"]:::frontend
    end

    %% Backend Boot Process
    subgraph "Backend Boot Process"
        ISO_Downloader["ISO Downloader & Cache Manager"]:::backend
        ISO_Parser["ISO Parser & Extraction"]:::backend
        Networking["Networking & Wireless Configuration"]:::backend
        Kernel_Loader["Kernel Loader (kexec)"]:::backend
    end

    %% Infrastructure & External Integration
    subgraph "External & Infrastructure"
        uRoot["u-root Integration & Build System"]:::infrastructure
        CI_CD["CI/CD Pipeline"]:::infrastructure
        Integration["Integration & Testing"]:::infrastructure
    end

    %% Boot Outcome
    Boot_OS["Boot Live OS"]:::backend

    %% Flow Connections
    U -->|"provides input"| CLI_TermUI
    CLI_TermUI -->|"triggers ISO download"| ISO_Downloader
    ISO_Downloader -->|"mounts and caches ISO"| ISO_Parser
    ISO_Parser -->|"extracts kernel/initrd"| Networking
    Networking --> Kernel_Loader
    Kernel_Loader -->|"loads via kexec"| Boot_OS

    %% UI/Menu association with CLI
    CLI_TermUI ---|"manages visual selection"| UI_Menu

    %% External Integration Connections
    uRoot ---|"bootstraps initramfs"| CLI_TermUI
    CI_CD ---|"builds and deploys"| uRoot
    Integration ---|"verifies components"| CLI_TermUI
    Integration --- Networking
    Integration --- ISO_Downloader

    %% Click Events for Frontend
    click CLI_TermUI "https://github.com/bjakobson/webboot/blob/master/cmds/webboot/webboot.go"
    click CLI_TermUI "https://github.com/bjakobson/webboot/blob/master/cmds/webboot/types.go"
    click CLI_TermUI "https://github.com/bjakobson/webboot/blob/master/cmds/cli/main.go"
    click CLI_TermUI "https://github.com/bjakobson/webboot/blob/master/cmds/cli/types.go"
    click UI_Menu "https://github.com/bjakobson/webboot/blob/master/pkg/menu/menu.go"

    %% Click Events for Backend
    click ISO_Downloader "https://github.com/bjakobson/webboot/blob/master/pkg/bootiso/bootiso.go"
    click ISO_Downloader "https://github.com/bjakobson/webboot/tree/master/pkg/bootiso"
    click Networking "https://github.com/bjakobson/webboot/blob/master/pkg/dhclient/dhclient.go"
    click Networking "https://github.com/bjakobson/webboot/tree/master/pkg/wifi"
    click Networking "https://github.com/bjakobson/webboot/blob/master/pkg/wpa/passphrase/passphrase.go"

    %% Click Events for Integration & Testing
    click Integration "https://github.com/bjakobson/webboot/blob/master/integration/basic_test.go"
    click Integration "https://github.com/bjakobson/webboot/blob/master/cmds/webboot/webboot_test.go"
    click Integration "https://github.com/bjakobson/webboot/blob/master/pkg/bootiso/bootiso_test.go"
    click Integration "https://github.com/bjakobson/webboot/blob/master/pkg/menu/menu_test.go"
    click Integration "https://github.com/bjakobson/webboot/blob/master/pkg/wpa/passphrase/passphrase_test.go"
    
    %% Click Events for External Dependencies & u-root Integration
    click uRoot "https://github.com/bjakobson/webboot/blob/master/README.md"
    click uRoot "https://github.com/bjakobson/webboot/blob/master/webboot.go"

    %% Click Events for CI/CD
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/.github/workflows/ci.yml"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/.github/workflows/nightly.yml"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/ci.sh"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/nightly.sh"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/Gopkg.toml"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/Gopkg.lock"
    click CI_CD "https://github.com/bjakobson/webboot/blob/master/makeusb.sh"

    %% Styles
    classDef user fill:#EEE8AA,stroke:#333,stroke-width:2px;
    classDef frontend fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ADD8E6,stroke:#333,stroke-width:2px;
```
