# mcspy-source/cobdiskless architecture

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

- Interactive diagram: https://gitdiagram.com/mcspy-source/cobdiskless
- Repository: https://github.com/mcspy-source/cobdiskless

## Overview

CobDiskless is a diskless network-boot platform: clients obtain DHCP leases, receive iPXE boot files, then mount per-client writable overlays over iSCSI. Image management prepares and registers golden images; storage supplies cached, copy-on-write block devices. The README also documents HTTP delivery, client/station management, and offline driver arming. Edges are limited to README-described flows and relationships visible in indexed excerpts; unsampled service wiring is not inferred.

Main entry points: [`src/CobDisklessCore/src/client/client_session.cpp`](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_session.cpp) (Client sessions), [`src/CobDisklessApp/admin_app.cpp`](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessApp/admin_app.cpp) (Admin interface), [`src/CobDisklessCore/src/image/image_manager.cpp`](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_manager.cpp) (Image lifecycle), [`src/CobDisklessCore/src/storage/cow_block_device.cpp`](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/cow_block_device.cpp) (Copy-on-write overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot networking"]
  node_dhcp["DHCP leasing<br/>[dhcp_server.cpp]"]
  node_tftp["TFTP boot files<br/>[tftp_server.cpp]"]
  node_ipxe["iPXE scripts<br/>[ipxe_script.hpp]"]
  node_http["HTTP assets/API<br/>[http_daemon.cpp]"]
  node_iscsi["iSCSI target<br/>[iscsi_target.cpp]"]
end

subgraph group_image["Image lifecycle"]
  node_image_manager["Image lifecycle<br/>[image_manager.cpp]"]
  node_golden_image["Golden image<br/>[golden_image.cpp]"]
  node_image_inspector["Image inspection"]
  node_image_registry[("Image registry<br/>[image_registry.cpp]")]
  node_driver_armer["Driver arming"]
  node_armer_cli["Armer CLI<br/>[cob_armer_main.cpp]"]
end

subgraph group_storage["Block storage"]
  node_cow["Copy-on-write overlay"]
  node_cache["Block cache<br/>[block_cache.cpp]"]
  node_writeback["Crash-safe writeback"]
  node_storage_manager["Storage roles"]
  node_backends["Image backends<br/>[block_device.hpp]"]
end

subgraph group_client["Client management"]
  node_session["Client sessions<br/>[client_session.cpp]"]
  node_client_manager["Client enrollment<br/>[client_manager.cpp]"]
  node_station_manager["Station tracking"]
  node_client_database[("Client records")]
end

subgraph group_core["Core services"]
  node_core["Subsystem orchestrator<br/>[core.cpp]"]
  node_config["Configuration<br/>[configuration.cpp]"]
  node_logger["Logging<br/>[logger.cpp]"]
  node_admin_app["Admin interface<br/>[admin_app.cpp]"]
end

node_pxe_client(("PXE client"))
node_admin(("Administrator"))

node_pxe_client -->|"requests lease"| node_dhcp
node_pxe_client -->|"fetches boot file"| node_tftp
node_tftp -.->|"serves scripts"| node_ipxe
node_pxe_client -->|"mounts target"| node_iscsi
node_iscsi -.->|"serves client disks"| node_session
node_session -->|"resolves image"| node_image_manager
node_session -->|"checks writeback role"| node_storage_manager
node_session -.->|"creates overlay"| node_cow
node_session -->|"checks image arming"| node_driver_armer
node_image_manager -->|"manages images"| node_golden_image
node_image_manager -->|"uses registry"| node_image_registry
node_image_manager -->|"prepares images"| node_driver_armer
node_golden_image -->|"inspects partitions"| node_image_inspector
node_golden_image -->|"uses block device"| node_backends
node_cow -->|"uses writeback"| node_writeback
node_cow -->|"wraps base device"| node_backends
node_cache -.->|"caches block I/O"| node_backends
node_iscsi -->|"exposes overlay"| node_cow
node_admin -->|"operates"| node_admin_app
node_admin_app -->|"manages images"| node_image_manager
node_admin_app -->|"manages sessions"| node_session
node_admin_app -->|"manages clients"| node_client_manager
node_admin_app -->|"manages stations"| node_station_manager
node_client_database -->|"uses machine store"| node_station_manager
node_armer_cli -->|"runs arming"| node_driver_armer
node_core -.->|"loads configuration"| node_config
node_core -.->|"logs lifecycle"| node_logger
node_http -.->|"delivers assets/API"| node_pxe_client

click node_dhcp "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/dhcp_server.cpp"
click node_tftp "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/tftp_server.cpp"
click node_ipxe "https://github.com/mcspy-source/cobdiskless/blob/main/include/CobDisklessCore/network/ipxe_script.hpp"
click node_http "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/http_daemon.cpp"
click node_iscsi "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/iscsi_target.cpp"
click node_image_manager "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_manager.cpp"
click node_golden_image "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/golden_image.cpp"
click node_image_inspector "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_inspector.cpp"
click node_image_registry "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_registry.cpp"
click node_driver_armer "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/pnp_driver_armer.cpp"
click node_session "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_session.cpp"
click node_client_manager "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_manager.cpp"
click node_station_manager "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/station_manager.cpp"
click node_client_database "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_database.cpp"
click node_cow "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/cow_block_device.cpp"
click node_cache "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/block_cache.cpp"
click node_writeback "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/writeback_context.cpp"
click node_storage_manager "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/storage_manager.cpp"
click node_backends "https://github.com/mcspy-source/cobdiskless/blob/main/include/CobDisklessCore/storage/block_device.hpp"
click node_core "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/core.cpp"
click node_config "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/config/configuration.cpp"
click node_logger "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/logging/logger.cpp"
click node_admin_app "https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessApp/admin_app.cpp"
click node_armer_cli "https://github.com/mcspy-source/cobdiskless/blob/main/src/tools/cob_armer_main.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_dhcp,node_tftp,node_ipxe,node_http,node_iscsi,node_pxe_client toneBlue
class node_image_manager,node_golden_image,node_image_inspector,node_image_registry,node_driver_armer,node_armer_cli toneAmber
class node_cow,node_cache,node_writeback,node_storage_manager,node_backends toneMint
class node_session,node_client_manager,node_station_manager,node_client_database toneRose
class node_core,node_config,node_logger,node_admin_app,node_admin toneIndigo
```

## Components

### Boot networking

- [DHCP leasing](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/dhcp_server.cpp): `src/CobDisklessCore/src/network/dhcp_server.cpp`
- [TFTP boot files](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/tftp_server.cpp): `src/CobDisklessCore/src/network/tftp_server.cpp`
- [iPXE scripts](https://github.com/mcspy-source/cobdiskless/blob/main/include/CobDisklessCore/network/ipxe_script.hpp): `include/CobDisklessCore/network/ipxe_script.hpp`
- [HTTP assets/API](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/http_daemon.cpp): `src/CobDisklessCore/src/network/http_daemon.cpp`
- [iSCSI target](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/network/iscsi_target.cpp): `src/CobDisklessCore/src/network/iscsi_target.cpp`

### Image lifecycle

- [Image lifecycle](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_manager.cpp): `src/CobDisklessCore/src/image/image_manager.cpp`
- [Golden image](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/golden_image.cpp): `src/CobDisklessCore/src/image/golden_image.cpp`
- [Image inspection](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_inspector.cpp): `src/CobDisklessCore/src/image/image_inspector.cpp`
- [Image registry](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/image_registry.cpp): `src/CobDisklessCore/src/image/image_registry.cpp`
- [Driver arming](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/image/pnp_driver_armer.cpp): `src/CobDisklessCore/src/image/pnp_driver_armer.cpp`
- [Armer CLI](https://github.com/mcspy-source/cobdiskless/blob/main/src/tools/cob_armer_main.cpp): `src/tools/cob_armer_main.cpp`

### Block storage

- [Copy-on-write overlay](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/cow_block_device.cpp): `src/CobDisklessCore/src/storage/cow_block_device.cpp`
- [Block cache](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/block_cache.cpp): `src/CobDisklessCore/src/storage/block_cache.cpp`
- [Crash-safe writeback](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/writeback_context.cpp): `src/CobDisklessCore/src/storage/writeback_context.cpp`
- [Storage roles](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/storage/storage_manager.cpp): `src/CobDisklessCore/src/storage/storage_manager.cpp`
- [Image backends](https://github.com/mcspy-source/cobdiskless/blob/main/include/CobDisklessCore/storage/block_device.hpp): `include/CobDisklessCore/storage/block_device.hpp`

### Client management

- [Client sessions](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_session.cpp): `src/CobDisklessCore/src/client/client_session.cpp`
- [Client enrollment](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_manager.cpp): `src/CobDisklessCore/src/client/client_manager.cpp`
- [Station tracking](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/station_manager.cpp): `src/CobDisklessCore/src/client/station_manager.cpp`
- [Client records](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/client/client_database.cpp): `src/CobDisklessCore/src/client/client_database.cpp`

### Core services

- [Subsystem orchestrator](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/core.cpp): `src/CobDisklessCore/src/core.cpp`
- [Configuration](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/config/configuration.cpp): `src/CobDisklessCore/src/config/configuration.cpp`
- [Logging](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessCore/src/logging/logger.cpp): `src/CobDisklessCore/src/logging/logger.cpp`
- [Admin interface](https://github.com/mcspy-source/cobdiskless/blob/main/src/CobDisklessApp/admin_app.cpp): `src/CobDisklessApp/admin_app.cpp`

### Other components

- **PXE client**
- **Administrator**

## Connections

- PXE client → DHCP leasing: requests lease (evidence: `README.md`)
- PXE client → TFTP boot files: fetches boot file (evidence: `README.md`)
- TFTP boot files → iPXE scripts: serves scripts (evidence: `README.md`)
- PXE client → iSCSI target: mounts target (evidence: `README.md`)
- iSCSI target → Client sessions: serves client disks (evidence: `README.md`)
- Client sessions → Image lifecycle: resolves image (evidence: `src/CobDisklessCore/src/client/client_session.cpp`)
- Client sessions → Storage roles: checks writeback role (evidence: `src/CobDisklessCore/src/client/client_session.cpp`)
- Client sessions → Copy-on-write overlay: creates overlay
- Client sessions → Driver arming: checks image arming (evidence: `src/CobDisklessCore/src/client/client_session.cpp`)
- Image lifecycle → Golden image: manages images
- Image lifecycle → Image registry: uses registry
- Image lifecycle → Driver arming: prepares images (evidence: `src/CobDisklessCore/src/image/image_manager.cpp`)
- Golden image → Image inspection: inspects partitions
- Golden image → Image backends: uses block device
- Copy-on-write overlay → Crash-safe writeback: uses writeback
- Copy-on-write overlay → Image backends: wraps base device
- Block cache → Image backends: caches block I/O
- iSCSI target → Copy-on-write overlay: exposes overlay (evidence: `README.md`)
- Administrator → Admin interface: operates
- Admin interface → Image lifecycle: manages images
- Admin interface → Client sessions: manages sessions
- Admin interface → Client enrollment: manages clients
- Admin interface → Station tracking: manages stations
- Client records → Station tracking: uses machine store
- Armer CLI → Driver arming: runs arming (evidence: `src/tools/cob_armer_main.cpp`)
- Subsystem orchestrator → Configuration: loads configuration
- Subsystem orchestrator → Logging: logs lifecycle
- HTTP assets/API → PXE client: delivers assets/API (evidence: `README.md`)