# igr1s-red/spinup architecture

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

- Interactive diagram: https://gitdiagram.com/igr1s-red/spinup
- Repository: https://github.com/igr1s-red/spinup

## Overview

##### Project Type and Purpose
- This is a standalone CLI tool written in Go for "spinning up" Linux virtual machines using QEMU.
- It provides end‐user commands (run, exec, ssh, start, stop, remove, etc.) to automate VM lifecycle: creating disk images, generating cloud-init config, invoking QEMU, and managing SSH access.

##### Main Components
A. CLI Layer (cmd package)
- All user‐facing commands live under `cmd/*.go` (run, exec, ssh, list, remove, etc.).
- Parses flags, validates arguments, and dispatches to the Engine API.
B. Engine Core (engine package)
- Central business logic in `engine/engine.go`: orchestration of VM creation, state management, image handling.
- Error definitions, path management, VM struct definitions.
C. CloudInit Generator (cloudinit package)
- `cloudinit/cloudinit.go` produces the ISO or user-data config for QEMU to inject SSH keys and initial provisioning.
D. QEMU Wrapper (qemu package)
- `qemu/qemu.go` builds the `exec.Command` invocation for `qemu-system-<arch>` and `qemu-img`.
- Encapsulates external binary calls and argument construction.
E. External Binaries
- `qemu-img`, `qemu-system-aarch64` or `qemu-system-x86_64` on the host.
F. Virtual Machine Instance
- The running guest, reached by SSH over a forwarded port.

##### Component Interactions and Data Flow
- User types `spinup run …` → CLI Layer parses it → calls Engine.Run()
- Engine:
1. Generates SSH key pair (if needed)
2. Calls CloudInit to render a seed ISO with user-data
3. Uses QEMU Wrapper to:
- Create or resize disk image via `qemu-img`
- Launch `qemu-system` with CPU, memory, disk, CD-ROM (cloud-init) and port-forward options
- QEMU binary boots the VM, reads cloud-init ISO for provisioning
- User can then run `spinup ssh` or `spinup exec`, which again goes CLI → Engine → QEMU wrapper (with `-serial` or `ssh` commands)

##### Architectural Patterns and Principles
- Layered Modularization:
- CLI layer strictly handles parsing and help text.
- Engine layer exposes a clean Go API for VM lifecycle.
- CloudInit and QEMU packages isolate external concerns.
- Single Responsibility: each package has one clear focus.
- Dependency Inversion: Engine depends on abstracted QEMU/CloudInit interfaces, making it easy to mock for tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entrypoint
    Main["main.go"]:::internal
    click Main "https://github.com/igr1s-red/spinup/blob/main/main.go"

    subgraph "Go CLI Application"
        direction TB

        CLI["CLI Layer\n(cmd package)"]:::internal
        click CLI "https://github.com/igr1s-red/spinup/tree/main/cmd/"

        Engine["Engine Core\n(engine package)"]:::internal
        click Engine "https://github.com/igr1s-red/spinup/tree/main/engine/"

        CloudInit["CloudInit Generator\n(cloudinit package)"]:::internal
        click CloudInit "https://github.com/igr1s-red/spinup/blob/main/cloudinit/cloudinit.go"

        QEMUWrapper["QEMU Wrapper\n(qemu package)"]:::internal
        click QEMUWrapper "https://github.com/igr1s-red/spinup/blob/main/qemu/qemu.go"
    end

    %% External and Runtime
    HostBinaries["Host QEMU Binaries\n(qemu-img,\nqemu-system-ARCH)"]:::external
    GuestVM["Guest VM\n(runtime)"]:::runtime
    ISO["Cloud-init ISO\n(user-data)"]:::data

    %% Data Flow and Calls
    Main -->|"invokes CLI"| CLI
    CLI -->|"calls Run/Exec/etc"| Engine
    Engine -->|"generate user-data"| CloudInit
    CloudInit -->|"produces ISO"| ISO
    Engine -->|"use ISO and disk"| QEMUWrapper
    QEMUWrapper -->|"executes"| HostBinaries
    HostBinaries -->|"boots with ISO"| GuestVM
    GuestVM -.->|"SSH port-forward"| CLI

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef external fill:#DFFFE0,stroke:#22863A,color:#22863A;
    classDef runtime fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef data fill:#FFF5B1,stroke:#F0C419,color:#F0C419;
```
