# mstovenour/virt-compose architecture

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

- Interactive diagram: https://gitdiagram.com/mstovenour/virt-compose
- Repository: https://github.com/mstovenour/virt-compose

## Overview

##### Project type and purpose
- This is a CLI‐driven, config‐driven orchestration tool for KVM virtual machines (“virt-compose”), analogous to Docker Compose but for VMs.
- It provides lifecycle management (install, start, shutdown, undefine) and USB passthrough via udev/systemd integration.

##### Main components
a. Configuration store
- Global config: virt-compose.yaml
- Per-VM definitions: /etc/virt-compose/vm/{vm_name}/{vm_name}.yaml
b. CLI entry point
- virt-compose.sh (invoked by user or systemd)
- Parses YAML via yq, invokes libvirt/qemu utilities
c. External tools & hypervisor
- yq (YAML parsing)
- virt-install, virsh, qemu-utils, xorriso
- libvirt daemon / qemu-kvm
d. Systemd services
- virt-compose.service (host boot/shutdown → start-all/shutdown-all)
- virt-compose-{vm}@.service (triggered by udev on USB add/remove → attach/detach)
e. udev rules
- Watches USB host device events → invokes systemd unit for attach/detach

##### Relationships & data flows
- User or systemd invokes “virt-compose [action]” → CLI reads YAML →
- install: builds cloud-init ISO, writes systemd-@ service unit
- start/shutdown: generates udev rules, calls virsh attach/start or shutdown/detach
- On host boot, systemd: virt-compose.service → virt-compose start-all → virsh start + udev rule generation
- On USB event, udev → systemd-@ service → virt-compose attach/device → virsh attach-device
- Hypervisor (libvirt/qemu) manages actual VM lifecycle & USB devices

##### Architectural patterns & design principles
- Configuration-driven orchestration
- Event-driven integration: udev → systemd → CLI
- Modular CLI commands mapped 1:1 to lifecycle operations
- Separation of concerns:
- config parsing (yq)
- VM provisioning (virt-install)
- runtime operations (virsh attach/start/shutdown)
- service management (systemd units)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Store
    subgraph "Configuration Store"
        direction TB
        GlobalConfig[(virt-compose.yaml)]:::config
        click GlobalConfig "https://github.com/mstovenour/virt-compose/blob/main/virt-compose.yaml"
        subgraph "Per-VM Definitions"
            direction TB
            VM1Config[(example_vm1.yaml)]:::config
            click VM1Config "https://github.com/mstovenour/virt-compose/blob/main/vm/example_vm1/example_vm1.yaml"
            VM1Meta[(meta-data)]:::config
            click VM1Meta "https://github.com/mstovenour/virt-compose/tree/main/vm/example_vm1/cloud-init/meta-data"
            VM1User[(user-data)]:::config
            click VM1User "https://github.com/mstovenour/virt-compose/tree/main/vm/example_vm1/cloud-init/user-data"
            VM2Config[(example_vm2.yaml)]:::config
            click VM2Config "https://github.com/mstovenour/virt-compose/blob/main/vm/example_vm2/example_vm2.yaml"
        end
    end

    %% CLI Layer
    subgraph "CLI & Scripts" 
        direction TB
        CLI["virt-compose.sh"]:::cli
        click CLI "https://github.com/mstovenour/virt-compose/blob/main/virt-compose.sh"
        InstallHelper["install.sh"]:::cli
        click InstallHelper "https://github.com/mstovenour/virt-compose/blob/main/install.sh"
        TestRunner["test-runner.sh"]:::cli
        click TestRunner "https://github.com/mstovenour/virt-compose/blob/main/test-runner.sh"
        TestConfig[(virt-compose-test.yaml)]:::config
        click TestConfig "https://github.com/mstovenour/virt-compose/blob/main/virt-compose-test.yaml"
        YQ["yq parser"]:::config
    end

    %% External Tools
    subgraph "External Tools & Hypervisor"
        direction TB
        Tools["virt-install, virsh, xorriso, qemu-utils"]:::external
        Hypervisor["libvirt/qemu-kvm"]:::external
    end

    %% VMs
    subgraph "Guest VMs"
        direction TB
        VM1["VM: example_vm1"]:::vm
        VM2["VM: example_vm2"]:::vm
    end

    %% System Services
    subgraph "System Services"
        direction TB
        Systemd["systemd manager"]:::service
        SCService["virt-compose.service"]:::service
        VMService["virt-compose-@.service"]:::service
    end

    %% udev
    subgraph "udev Subsystem"
        direction TB
        Udev["udev rules & events"]:::service
    end

    %% Flows
    GlobalConfig -->|"reads config"| CLI
    VM1Config --> CLI
    VM2Config --> CLI
    CLI -->|"parses YAML"| YQ
    CLI -->|"builds ISO"| InstallHelper
    CLI -->|"executes tests"| TestRunner
    CLI -->|"calls external tools"| Tools
    Tools -->|"provisions VMs"| Hypervisor
    Hypervisor -->|"runs"| VM1
    Hypervisor -->|"runs"| VM2
    Systemd -->|"on host-boot/shutdown"| SCService
    SCService -->|"start-all/shutdown-all"| CLI
    Udev -->|"USB add/remove"| VMService
    VMService -->|"attach/detach"| CLI
    CLI -->|"calls virsh start/shutdown/attach"| Tools

    %% Styles
    classDef config fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef cli fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef service fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef external fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef vm fill:#FFF9C4,stroke:#F57F17,color:#F57F17
```
