# badsectorlabs/ludus architecture

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

- Interactive diagram: https://gitdiagram.com/badsectorlabs/ludus
- Repository: https://github.com/badsectorlabs/ludus

## Overview

#### Purpose and Top-Level Entry Points
Ludus provisions multi-user cyber ranges: VM networks and automation built on Proxmox. The principal operational path is server bootstrap → API/control plane → Proxmox/Ansible execution. Key binaries are the installer/controller in `ludus-server/main.go`, the user CLI in `ludus-client/main.go`, and the API service centered in `ludus-api/routers.go`. `dynamic-inventory/main.go` supplies generated Ansible inventory.

#### Server Bootstrap and Host Lifecycle
`ludus-server` converts a clean Debian host into a Ludus/Proxmox host, managing installation state, configuration, subprocesses, permissions, and upgrades. Its install workflow invokes staged Ansible provisioning, notably `ludus-server/ansible/proxmox-install/main.yml` and `ludus-server/ansible/proxmox-install/stage-1.yml`. This is the boundary from a local bootstrap executable to a persistent virtualization host with system services, networking, DNS, and WireGuard.

#### API Control Plane and Persistence
The Go API exposes management domains for ranges, VMs, templates, snapshots, users/groups, blueprints, sources, diagnostics, and power state through handlers such as `ludus-api/api_range_management.go`, `ludus-api/api_vm_management.go`, and `ludus-api/api_blueprint_management.go`. Routing/middleware form the HTTP boundary in `ludus-api/routers.go` and `ludus-api/middleware.go`. PocketBase is the embedded persistence/authentication backend, initialized through `ludus-api/pocketbase.go`; schema and access-control evolution are maintained in `ludus-api/migrations/`.

#### Range Configuration, Authorization, and Scheduling
Range definitions are validated, normalized, stored, and written through `ludus-api/range_config.go`, `ludus-api/range_config_write.go`, and `ludus-api/yaml_validate.go`. The API enforces tenant/group access and capacity boundaries in `ludus-api/range_access.go` and `ludus-api/quota.go`. Background timing behavior, including lifecycle work such as automatic shutdown, is centralized in `ludus-api/scheduler/scheduler.go`.

#### Provisioning Execution Boundary
API operations delegate long-running host work to Ansible and command execution rather than directly configuring every VM. `ludus-api/ansible.go` and `ludus-api/commandmanager/commandmanager.go` bridge request handling to commands/playbooks. The primary range orchestration playbook is `ludus-server/ansible/range-management/ludus.yml`; VM deployment and state transitions occur under `ludus-server/ansible/range-management/tasks/proxmox/deploy-vm.yml` and `ludus-server/ansible/range-management/tasks/proxmox/set-vm-state.yml`. This decouples durable API state from asynchronous infrastructure reconciliation.

#### Network, Access, and Virtualization Integration
Proxmox is the VM/storage hypervisor integration, represented by `ludus-api/proxmox.go`; SDN/network composition is handled by `ludus-api/network.go` and `ludus-api/sdn.go`. Per-range router, VLAN, DNS, and firewall setup is realized by Ansible in `ludus-server/ansible/range-management/tasks/router/configure-router.yml` and `ludus-server/ansible/range-management/tasks/firewall/firewall-management.yml`. WireGuard provides user connectivity via `ludus-api/wireguard.go`; access artifacts are produced by `ludus-server/ansible/user-management/add-user.yml`.

#### Templates, Blueprints, and Extensible Content
Packer builds reusable OS VM templates from HCL definitions, e.g. `ludus-server/packer/debian12/debian12.pkr.hcl` and `ludus-server/packer/win2022-server-x64/win2022-server-x64.pkr.hcl`. Blueprints compose range configurations and dependencies through `ludus-api/blueprint_resolver.go`. Source installation/synchronization supplies externally sourced blueprints and Ansible roles through `ludus-api/source_install.go` and `ludus-api/source_sync.go`, forming a controlled content-ingestion boundary.

#### Client and Embedded Interfaces
The Go CLI maps commands to API operations, with command registration in `ludus-client/cmd/root.go`, REST communication in `ludus-client/rest/restapi.go`, and domain commands such as `ludus-client/cmd/range.go`. The API can serve embedded Web UI and documentation via `ludus-api/embedded_webui.go` and `ludus-api/embedded_docs.go`. Documentation itself is a separate Docusaurus/Node site under `docs/`.

Main entry points: [`ludus-api/api_range_management.go`](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/api_range_management.go) (Range and VM management), [`ludus-server/ansible/range-management/ludus.yml`](https://github.com/badsectorlabs/ludus/blob/main/ludus-server/ansible/range-management/ludus.yml) (Range orchestration), [`ludus-api/proxmox.go`](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/proxmox.go) (Proxmox host), [`ludus-api/routers.go`](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/routers.go) (Ludus API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["User CLI<br/>Go CLI<br/>[main.go]"]
  node_cli_commands["CLI commands<br/>command layer<br/>[root.go]"]
  node_webui_docs["Embedded web UI and docs<br/>embedded interface<br/>[embedded_webui.go]"]
end

subgraph group_control["Control Plane"]
  node_api["Ludus API<br/>Go service<br/>[routers.go]"]
  node_middleware["HTTP middleware<br/>HTTP boundary<br/>[middleware.go]"]
  node_management["Range and VM management<br/>API handlers"]
  node_range_config["Range configuration<br/>config domain<br/>[range_config.go]"]
  node_access_quota["Access and quotas<br/>authorization<br/>[range_access.go]"]
  node_pocketbase[("PocketBase<br/>persistence and auth<br/>[pocketbase.go]")]
  node_scheduler["Lifecycle scheduler<br/>background worker<br/>[scheduler.go]"]
  node_blueprints["Blueprint resolver<br/>content composition"]
  node_sources["Source sync<br/>content ingestion<br/>[source_sync.go]"]
end

subgraph group_execution["Provisioning"]
  node_command_manager["Command manager<br/>async execution<br/>[commandmanager.go]"]
  node_range_playbook["Range orchestration<br/>Ansible playbook<br/>[ludus.yml]"]
  node_networking["Network and SDN<br/>network integration<br/>[network.go]"]
  node_wireguard["WireGuard access<br/>connectivity<br/>[wireguard.go]"]
end

subgraph group_platform["Host Platform"]
  node_server["Server bootstrap<br/>Go installer<br/>[main.go]"]
  node_host_playbooks["Host install playbooks<br/>Ansible<br/>[main.yml]"]
  node_proxmox{{"Proxmox host<br/>hypervisor<br/>[proxmox.go]"}}
  node_templates["Packer templates<br/>image builds<br/>[debian12.pkr.hcl]"]
end

node_server -->|"runs"| node_host_playbooks
node_host_playbooks -->|"provisions"| node_proxmox
node_cli -->|"registers"| node_cli_commands
node_cli_commands -->|"calls REST API"| node_api
node_api -->|"uses"| node_middleware
node_middleware -->|"routes authorized requests"| node_management
node_management -->|"manages"| node_range_config
node_management -->|"checks"| node_access_quota
node_range_config -->|"stores state"| node_pocketbase
node_scheduler -.->|"triggers lifecycle work"| node_management
node_management -->|"delegates long-running work"| node_command_manager
node_command_manager -->|"runs"| node_range_playbook
node_range_playbook -->|"deploys and changes VM state"| node_proxmox
node_networking -->|"composes SDN"| node_proxmox
node_range_playbook -->|"configures ranges"| node_networking
node_wireguard -->|"provisions user access"| node_range_playbook
node_blueprints -->|"composes definitions"| node_range_config
node_sources -->|"supplies content"| node_blueprints
node_templates -->|"publishes VM images"| node_proxmox
node_api -->|"serves"| node_webui_docs

click node_server "https://github.com/badsectorlabs/ludus/blob/main/ludus-server/main.go"
click node_host_playbooks "https://github.com/badsectorlabs/ludus/blob/main/ludus-server/ansible/proxmox-install/main.yml"
click node_proxmox "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/proxmox.go"
click node_cli "https://github.com/badsectorlabs/ludus/blob/main/ludus-client/main.go"
click node_cli_commands "https://github.com/badsectorlabs/ludus/blob/main/ludus-client/cmd/root.go"
click node_api "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/routers.go"
click node_middleware "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/middleware.go"
click node_management "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/api_range_management.go"
click node_range_config "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/range_config.go"
click node_access_quota "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/range_access.go"
click node_pocketbase "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/pocketbase.go"
click node_scheduler "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/scheduler/scheduler.go"
click node_blueprints "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/blueprint_resolver.go"
click node_sources "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/source_sync.go"
click node_command_manager "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/commandmanager/commandmanager.go"
click node_range_playbook "https://github.com/badsectorlabs/ludus/blob/main/ludus-server/ansible/range-management/ludus.yml"
click node_networking "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/network.go"
click node_wireguard "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/wireguard.go"
click node_templates "https://github.com/badsectorlabs/ludus/blob/main/ludus-server/packer/debian12/debian12.pkr.hcl"
click node_webui_docs "https://github.com/badsectorlabs/ludus/blob/main/ludus-api/embedded_webui.go"

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_cli,node_cli_commands,node_webui_docs toneBlue
class node_api,node_middleware,node_management,node_range_config,node_access_quota,node_pocketbase,node_scheduler,node_blueprints,node_sources toneAmber
class node_command_manager,node_range_playbook,node_networking,node_wireguard toneMint
class node_server,node_host_playbooks,node_proxmox,node_templates toneRose
```

## Components

### Interfaces

- [User CLI](https://github.com/badsectorlabs/ludus/blob/main/ludus-client/main.go): Go CLI · `ludus-client/main.go`
- [CLI commands](https://github.com/badsectorlabs/ludus/blob/main/ludus-client/cmd/root.go): command layer · `ludus-client/cmd/root.go`
- [Embedded web UI and docs](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/embedded_webui.go): embedded interface · `ludus-api/embedded_webui.go`

### Control Plane

- [Ludus API](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/routers.go): Go service · Management control plane for ranges and infrastructure. · `ludus-api/routers.go`
- [HTTP middleware](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/middleware.go): HTTP boundary · `ludus-api/middleware.go`
- [Range and VM management](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/api_range_management.go): API handlers · `ludus-api/api_range_management.go`
- [Range configuration](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/range_config.go): config domain · Validates, normalizes, persists, and writes range definitions. · `ludus-api/range_config.go`
- [Access and quotas](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/range_access.go): authorization · Enforces tenant, group, and capacity limits. · `ludus-api/range_access.go`
- [PocketBase](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/pocketbase.go): persistence and auth · `ludus-api/pocketbase.go`
- [Lifecycle scheduler](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/scheduler/scheduler.go): background worker · `ludus-api/scheduler/scheduler.go`
- [Blueprint resolver](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/blueprint_resolver.go): content composition · `ludus-api/blueprint_resolver.go`
- [Source sync](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/source_sync.go): content ingestion · Installs and synchronizes external blueprints and roles. · `ludus-api/source_sync.go`

### Provisioning

- [Command manager](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/commandmanager/commandmanager.go): async execution · Bridges API work to host commands and playbooks. · `ludus-api/commandmanager/commandmanager.go`
- [Range orchestration](https://github.com/badsectorlabs/ludus/blob/main/ludus-server/ansible/range-management/ludus.yml): Ansible playbook · Reconciles range infrastructure and VM lifecycle. · `ludus-server/ansible/range-management/ludus.yml`
- [Network and SDN](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/network.go): network integration · `ludus-api/network.go`
- [WireGuard access](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/wireguard.go): connectivity · `ludus-api/wireguard.go`

### Host Platform

- [Server bootstrap](https://github.com/badsectorlabs/ludus/blob/main/ludus-server/main.go): Go installer · Installs and upgrades the Ludus host. · `ludus-server/main.go`
- [Host install playbooks](https://github.com/badsectorlabs/ludus/blob/main/ludus-server/ansible/proxmox-install/main.yml): Ansible · Staged Debian-to-Proxmox provisioning. · `ludus-server/ansible/proxmox-install/main.yml`
- [Proxmox host](https://github.com/badsectorlabs/ludus/blob/main/ludus-api/proxmox.go): hypervisor · Persistent VM, storage, and network platform. · `ludus-api/proxmox.go`
- [Packer templates](https://github.com/badsectorlabs/ludus/blob/main/ludus-server/packer/debian12/debian12.pkr.hcl): image builds · Builds reusable OS VM templates. · `ludus-server/packer/debian12/debian12.pkr.hcl`

## Connections

- Server bootstrap → Host install playbooks: runs
- Host install playbooks → Proxmox host: provisions
- User CLI → CLI commands: registers
- CLI commands → Ludus API: calls REST API
- Ludus API → HTTP middleware: uses
- HTTP middleware → Range and VM management: routes authorized requests
- Range and VM management → Range configuration: manages
- Range and VM management → Access and quotas: checks
- Range configuration → PocketBase: stores state
- Lifecycle scheduler → Range and VM management: triggers lifecycle work
- Range and VM management → Command manager: delegates long-running work
- Command manager → Range orchestration: runs
- Range orchestration → Proxmox host: deploys and changes VM state
- Network and SDN → Proxmox host: composes SDN
- Range orchestration → Network and SDN: configures ranges
- WireGuard access → Range orchestration: provisions user access
- Blueprint resolver → Range configuration: composes definitions
- Source sync → Blueprint resolver: supplies content
- Packer templates → Proxmox host: publishes VM images
- Ludus API → Embedded web UI and docs: serves
