# nshaibu/qbox architecture

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

- Interactive diagram: https://gitdiagram.com/nshaibu/qbox
- Repository: https://github.com/nshaibu/qbox

## Overview

QBox is a shell-based QEMU VM launcher and manager. Its apparent user workflow starts at the QBox command-line entry point, presents menu-driven VM actions, and hands booting to scripts that invoke QEMU. The tree also shows networking, guest information, and logging support. README documentation is brief and the sampled source does not include the shell entry point or dialogs, so links among those components are based on their names and roles; the PHP/socket path is shown separately.

Main entry points: [`QBox/dialog_ui/qbox_main_menu.sh`](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_main_menu.sh) (Main menu), [`QBox/bash_s/qemu-im-box.sh`](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qemu-im-box.sh) (QEMU launcher), [`QBox/dialog_ui/qbox_create_vm.sh`](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_create_vm.sh) (Create VM), [`QBox/QBox`](https://github.com/nshaibu/qbox/blob/master/QBox/QBox) (QBox command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_qbox["QBox command"]
  node_mainmenu["Main menu<br/>[qbox_main_menu.sh]"]
  node_newmenu["New VM menu"]
  node_create["Create VM<br/>[qbox_create_vm.sh]"]
  node_bootmenu["Boot device menu"]
  node_othermenu["Other menu<br/>[qbox_other_menu.sh]"]
end

subgraph group_vm["VM lifecycle"]
  node_qemulaunch["QEMU launcher<br/>[qemu-im-box.sh]"]
  node_directboot["Direct Linux boot"]
  node_bootgen["Bootfile generator"]
  node_bootawk["Bootfile rules"]
  node_reconfig["VM reconfiguration"]
  node_osinfo["OS information"]
  node_vminfo["VM information"]
end

subgraph group_host["Host integration"]
  node_networkmenu["Network config menu"]
  node_tapservice["Tap service<br/>[qemu-tap-box.sh]"]
  node_iface["Interface detection<br/>[netiface_deter.py]"]
end

subgraph group_aux["Auxiliary services"]
  node_logs["QBox logs<br/>[qboxlogs.sh]"]
  node_logger["Log helper<br/>[qemubox_logger.cpp]"]
  node_webclient["PHP client<br/>[qbox_client.php]"]
  node_server["TCP server<br/>[Server.cpp]"]
end

node_user(("User"))
node_qemu["QEMU"]

node_user -->|"runs"| node_qbox
node_qbox -->|"opens menu"| node_mainmenu
node_mainmenu -->|"starts creation"| node_newmenu
node_newmenu -->|"opens form"| node_create
node_mainmenu -->|"selects boot"| node_bootmenu
node_mainmenu -->|"opens options"| node_othermenu
node_create -->|"configures launch"| node_qemulaunch
node_bootmenu -->|"selects boot"| node_qemulaunch
node_qemulaunch -->|"launches"| node_qemu
node_directboot -->|"launches"| node_qemu
node_bootgen -->|"runs rules"| node_bootawk
node_reconfig -->|"reconfigures"| node_qemulaunch
node_networkmenu -->|"configures networking"| node_tapservice
node_iface -.->|"provides addresses"| node_networkmenu
node_osinfo -.->|"supports selection"| node_create
node_vminfo -->|"displays status"| node_user
node_logs -.->|"uses helper"| node_logger
node_webclient -->|"connects to"| node_server

click node_qbox "https://github.com/nshaibu/qbox/blob/master/QBox/QBox"
click node_mainmenu "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_main_menu.sh"
click node_newmenu "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_new_vm_menu.sh"
click node_create "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_create_vm.sh"
click node_bootmenu "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_boot_device.sh"
click node_othermenu "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_other_menu.sh"
click node_qemulaunch "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qemu-im-box.sh"
click node_directboot "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/direct_linux_boot.sh"
click node_bootgen "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qemu-bootfile-generator.sh"
click node_bootawk "https://github.com/nshaibu/qbox/blob/master/QBox/awk/qemu-bootfile-generator.awk"
click node_reconfig "https://github.com/nshaibu/qbox/blob/master/qbox_reconfig_vm.sh"
click node_networkmenu "https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_network_config.sh"
click node_tapservice "https://github.com/nshaibu/qbox/blob/master/QBox/service/qemu-tap-box.sh"
click node_iface "https://github.com/nshaibu/qbox/blob/master/QBox/python3/netiface_deter.py"
click node_osinfo "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qbox_ostype_info.sh"
click node_vminfo "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qbox_display_vm_info.sh"
click node_logs "https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qboxlogs.sh"
click node_logger "https://github.com/nshaibu/qbox/blob/master/QBox/bin/sources/qemubox_logger.cpp"
click node_webclient "https://github.com/nshaibu/qbox/blob/master/QBox/www/qbox_client.php"
click node_server "https://github.com/nshaibu/qbox/blob/master/QBox/bin/sources/Server.cpp"

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_qbox,node_mainmenu,node_newmenu,node_create,node_bootmenu,node_othermenu,node_user toneBlue
class node_qemulaunch,node_directboot,node_bootgen,node_bootawk,node_reconfig,node_osinfo,node_vminfo toneAmber
class node_networkmenu,node_tapservice,node_iface toneMint
class node_logs,node_logger,node_webclient,node_server toneRose
class node_qemu toneIndigo
```

## Components

### User interface

- [QBox command](https://github.com/nshaibu/qbox/blob/master/QBox/QBox): `QBox/QBox`
- [Main menu](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_main_menu.sh): `QBox/dialog_ui/qbox_main_menu.sh`
- [New VM menu](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_new_vm_menu.sh): `QBox/dialog_ui/qbox_new_vm_menu.sh`
- [Create VM](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_create_vm.sh): `QBox/dialog_ui/qbox_create_vm.sh`
- [Boot device menu](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_boot_device.sh): `QBox/dialog_ui/qbox_boot_device.sh`
- [Other menu](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_other_menu.sh): `QBox/dialog_ui/qbox_other_menu.sh`

### VM lifecycle

- [QEMU launcher](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qemu-im-box.sh): `QBox/bash_s/qemu-im-box.sh`
- [Direct Linux boot](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/direct_linux_boot.sh): `QBox/bash_s/direct_linux_boot.sh`
- [Bootfile generator](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qemu-bootfile-generator.sh): `QBox/bash_s/qemu-bootfile-generator.sh`
- [Bootfile rules](https://github.com/nshaibu/qbox/blob/master/QBox/awk/qemu-bootfile-generator.awk): `QBox/awk/qemu-bootfile-generator.awk`
- [VM reconfiguration](https://github.com/nshaibu/qbox/blob/master/qbox_reconfig_vm.sh): `qbox_reconfig_vm.sh`
- [OS information](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qbox_ostype_info.sh): `QBox/bash_s/qbox_ostype_info.sh`
- [VM information](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qbox_display_vm_info.sh): `QBox/bash_s/qbox_display_vm_info.sh`

### Host integration

- [Network config menu](https://github.com/nshaibu/qbox/blob/master/QBox/dialog_ui/qbox_network_config.sh): `QBox/dialog_ui/qbox_network_config.sh`
- [Tap service](https://github.com/nshaibu/qbox/blob/master/QBox/service/qemu-tap-box.sh): `QBox/service/qemu-tap-box.sh`
- [Interface detection](https://github.com/nshaibu/qbox/blob/master/QBox/python3/netiface_deter.py): `QBox/python3/netiface_deter.py`

### Auxiliary services

- [QBox logs](https://github.com/nshaibu/qbox/blob/master/QBox/bash_s/qboxlogs.sh): `QBox/bash_s/qboxlogs.sh`
- [Log helper](https://github.com/nshaibu/qbox/blob/master/QBox/bin/sources/qemubox_logger.cpp): `QBox/bin/sources/qemubox_logger.cpp`
- [PHP client](https://github.com/nshaibu/qbox/blob/master/QBox/www/qbox_client.php): `QBox/www/qbox_client.php`
- [TCP server](https://github.com/nshaibu/qbox/blob/master/QBox/bin/sources/Server.cpp): `QBox/bin/sources/Server.cpp`

### Other components

- **User**
- **QEMU**

## Connections

- User → QBox command: runs
- QBox command → Main menu: opens menu
- Main menu → New VM menu: starts creation
- New VM menu → Create VM: opens form
- Main menu → Boot device menu: selects boot
- Main menu → Other menu: opens options
- Create VM → QEMU launcher: configures launch
- Boot device menu → QEMU launcher: selects boot
- QEMU launcher → QEMU: launches
- Direct Linux boot → QEMU: launches
- Bootfile generator → Bootfile rules: runs rules
- VM reconfiguration → QEMU launcher: reconfigures
- Network config menu → Tap service: configures networking
- Interface detection → Network config menu: provides addresses
- OS information → Create VM: supports selection
- VM information → User: displays status
- QBox logs → Log helper: uses helper
- PHP client → TCP server: connects to