# xiisuma/tinyvmos architecture

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

- Interactive diagram: https://gitdiagram.com/xiisuma/tinyvmos
- Repository: https://github.com/xiisuma/tinyvmos

## Overview

TinyVMOS turns a physical computer into a host for isolated, single-purpose micro-VMs, managed through a central control plane. The documented flow is host installation and hardware detection, then Go control-plane management through a replaceable Firecracker VMM, with service images running in micro-VMs. CLI, web, and mobile interfaces are documented product surfaces. The tree and README establish these capabilities, but no implementation excerpts were available, so uncertain call wiring is omitted.

Main entry points: [`controlplane/api`](https://github.com/xiisuma/tinyvmos/tree/main/controlplane/api) (REST and WebSocket API), [`controlplane`](https://github.com/xiisuma/tinyvmos/tree/main/controlplane) (Go control plane), [`os/installer`](https://github.com/xiisuma/tinyvmos/tree/main/os/installer) (Host installer), [`os`](https://github.com/xiisuma/tinyvmos/tree/main/os) (Buildroot host OS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host platform"]
  node_detect["Hardware detection"]
  node_installer["Host installer"]
  node_hostos["Buildroot host OS"]
  node_kvm["Linux KVM"]
  node_network["Zone networking"]
end

subgraph group_management["Control plane"]
  node_daemon["Go control plane"]
  node_api["REST and WebSocket API"]
  node_vmm["VMM interface"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI client"]
  node_web["Web interface"]
  node_mobile["Mobile app"]
end

subgraph group_workloads["VM workloads"]
  node_catalog["Service image catalog"]
  node_apache["Apache guest image"]
  node_microvm["Service micro-VMs"]
end

node_operator(("Operator"))
node_hardware["Physical computer"]
node_firecracker["Firecracker"]

node_operator -->|"installs host"| node_installer
node_hardware -->|"detects hardware"| node_detect
node_installer -->|"installs"| node_hostos
node_operator -->|"manages via"| node_cli
node_operator -->|"manages via"| node_web
node_operator -->|"manages via"| node_mobile
node_cli -->|"uses API"| node_api
node_web -->|"uses API"| node_api
node_mobile -->|"uses API"| node_api
node_daemon -->|"provides API"| node_api
node_daemon -->|"manages VMs"| node_vmm
node_vmm -->|"controls"| node_firecracker
node_hostos -->|"provides"| node_kvm
node_firecracker -->|"uses"| node_kvm
node_catalog -->|"includes image"| node_apache
node_apache -->|"provides guest image"| node_microvm
node_firecracker -->|"runs"| node_microvm
node_network -->|"connects zones"| node_microvm

click node_detect "https://github.com/xiisuma/tinyvmos/tree/main/os/hardware-detect"
click node_installer "https://github.com/xiisuma/tinyvmos/tree/main/os/installer"
click node_hostos "https://github.com/xiisuma/tinyvmos/tree/main/os"
click node_network "https://github.com/xiisuma/tinyvmos/tree/main/os"
click node_cli "https://github.com/xiisuma/tinyvmos/tree/main/cli"
click node_web "https://github.com/xiisuma/tinyvmos/tree/main/web"
click node_mobile "https://github.com/xiisuma/tinyvmos/tree/main/mobile"
click node_daemon "https://github.com/xiisuma/tinyvmos/tree/main/controlplane"
click node_api "https://github.com/xiisuma/tinyvmos/tree/main/controlplane/api"
click node_vmm "https://github.com/xiisuma/tinyvmos/tree/main/controlplane"
click node_catalog "https://github.com/xiisuma/tinyvmos/tree/main/images"
click node_apache "https://github.com/xiisuma/tinyvmos/tree/main/images/web-apache"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_detect,node_installer,node_hostos,node_kvm,node_network toneBlue
class node_daemon,node_api,node_vmm toneAmber
class node_cli,node_web,node_mobile toneMint
class node_catalog,node_apache,node_microvm toneRose
class node_operator,node_hardware,node_firecracker toneIndigo
```

## Components

### Host platform

- [Hardware detection](https://github.com/xiisuma/tinyvmos/tree/main/os/hardware-detect): `os/hardware-detect`
- [Host installer](https://github.com/xiisuma/tinyvmos/tree/main/os/installer): `os/installer`
- [Buildroot host OS](https://github.com/xiisuma/tinyvmos/tree/main/os): `os`
- **Linux KVM**
- [Zone networking](https://github.com/xiisuma/tinyvmos/tree/main/os): `os`

### Control plane

- [Go control plane](https://github.com/xiisuma/tinyvmos/tree/main/controlplane): `controlplane`
- [REST and WebSocket API](https://github.com/xiisuma/tinyvmos/tree/main/controlplane/api): `controlplane/api`
- [VMM interface](https://github.com/xiisuma/tinyvmos/tree/main/controlplane): `controlplane`

### User interfaces

- [CLI client](https://github.com/xiisuma/tinyvmos/tree/main/cli): `cli`
- [Web interface](https://github.com/xiisuma/tinyvmos/tree/main/web): `web`
- [Mobile app](https://github.com/xiisuma/tinyvmos/tree/main/mobile): `mobile`

### VM workloads

- [Service image catalog](https://github.com/xiisuma/tinyvmos/tree/main/images): `images`
- [Apache guest image](https://github.com/xiisuma/tinyvmos/tree/main/images/web-apache): `images/web-apache`
- **Service micro-VMs**

### Other components

- **Operator**
- **Physical computer**
- **Firecracker**

## Connections

- Operator → Host installer: installs host
- Physical computer → Hardware detection: detects hardware
- Host installer → Buildroot host OS: installs
- Operator → CLI client: manages via
- Operator → Web interface: manages via
- Operator → Mobile app: manages via
- CLI client → REST and WebSocket API: uses API
- Web interface → REST and WebSocket API: uses API
- Mobile app → REST and WebSocket API: uses API
- Go control plane → REST and WebSocket API: provides API
- Go control plane → VMM interface: manages VMs
- VMM interface → Firecracker: controls
- Buildroot host OS → Linux KVM: provides
- Firecracker → Linux KVM: uses
- Service image catalog → Apache guest image: includes image
- Apache guest image → Service micro-VMs: provides guest image
- Firecracker → Service micro-VMs: runs
- Zone networking → Service micro-VMs: connects zones