# vpatel95/topology-deployer architecture

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

- Interactive diagram: https://gitdiagram.com/vpatel95/topology-deployer
- Repository: https://github.com/vpatel95/topology-deployer

## Overview

##### Project Type and Purpose
- topology-deployer is a Python-based CLI tool for provisioning network topologies (networks and VMs) on an Ubuntu host.
- It reads a JSON config (from topologies/*.json or user‐supplied) and, via libvirt/QEMU (invoked through shell commands), creates or deletes networks and virtual machines.

##### Key Architectural Components
a. CLI & Entry Point
- `deployer/deployer.py`: parses command-line arguments, handles “create” vs “delete” operations, dispatches to network and VM flows.
- Packaging files (`setup.py`, `pyproject.toml`, `requirements.txt`, `scripts/install`) wrap the tool as a pip‐installable command (`topology-deployer`).
b. Topology Parser
- `deployer/topology.py`: loads and validates the JSON config (version, networks array, vms array).
c. Network Provisioner
- `deployer/network.py`: core routines to define and apply networks (management, NAT, isolated).
- `deployer/nat_utils.py`: handles NAT-specific setup (iptables rules, forwarding).
- Interacts with the Linux host networking stack (bridges, subnets).
d. VM Provisioner
- `deployer/virtual_machine.py`: defines and launches VMs using libvirt/QEMU command invocations.
- Configures flavors, vCPUs, RAM, disk, VNC ports, and attaches networks.
e. Shared Utilities & Globals
- `deployer/utils.py`, `deployer/globals.py`: logging setup, common constants, error handling.
f. Sample Configs & Topologies
- `topologies/*.json`: reference JSON network/VM definitions.
g. CI/CD & Testing
- `.github/workflows/python-app.yml`: test suite run on push/PR.
- `.github/workflows/python-publish.yml`: package publish pipeline.
- `deployer/tests/`: unit tests for deployer, network, VM modules.

##### Relationships & Data Flow
1. User invokes `topology-deployer` with flags and a JSON config.
2. CLI (deployer.py) calls Topology Parser → produces in-memory model.
3. For “create” operation:
a. Network Provisioner reads each network object → uses nat_utils for NAT networks → executes shell commands to create Linux bridges and network namespaces.
b. VM Provisioner reads each VM object → invokes QEMU/libvirt commands (via subprocess) to create disk images, define VMs, attach them to the previously created networks.
4. For “delete” operation: reverses the above steps.
5. Logging/verbosity flags control output; `--dry-run` prints commands instead of executing.

##### Architectural Patterns & Principles
- Modular design: clear separation between configuration parsing, network management, VM management, and utilities.
- Single Responsibility: each module handles one domain (networks vs VMs).
- Dependency injection via JSON: the entire topology is input-driven, making the tool data-centric and extensible.
- CLI–Library split: command parsing in `deployer.py` delegates to pure-python library code.
- Testing isolation: unit tests mock or simulate libvirt/network calls.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Flow
    JSONConfig["JSON Config\n(topologies/*.json)"]:::config
    CLI["CLI Entry Point\n(deployer/deployer.py)\nFlags: --dry-run, etc."]:::internal
    TopParser["Topology Parser\n(deployer/topology.py)"]:::internal
    NetworkProv["Network Provisioner\n(deployer/network.py)"]:::internal
    NATUtils["NAT Utilities\n(deployer/nat_utils.py)"]:::internal
    VMProv["VM Provisioner\n(deployer/virtual_machine.py)"]:::internal
    UtilsGlobals["Shared Utils & Globals\n(deployer/utils.py, globals.py)"]:::internal
    LinuxStack["Linux Host Networking Stack\n(bridges, iptables)"]:::external
    Hypervisor["libvirt/QEMU Hypervisor"]:::external

    %% Packaging
    subgraph "Packaging & Install" 
        SetupPy["setup.py"]:::config
        Pyproject["pyproject.toml"]:::config
        Requirements["requirements.txt"]:::config
        InstallScript["scripts/install"]:::config
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        CIApp[".github/workflows/python-app.yml"]:::config
        CIPub[".github/workflows/python-publish.yml"]:::config
        TestDeployer["deployer/tests/test_deployer.py"]:::config
        TestNetwork["deployer/tests/test_network.py"]:::config
        TestVM["deployer/tests/test_virtual_machines.py"]:::config
        ValidNW["deployer/tests/valid_nw.json"]:::config
    end

    %% Sample Config Diagrams
    SampleConfigs["Sample Topologies\n(topologies/*.json, *.drawio)"]:::config

    %% Data Flows
    JSONConfig -->|input| CLI
    CLI -->|parses args| TopParser
    TopParser -->|networks array| NetworkProv
    TopParser -->|vms array| VMProv
    NetworkProv -->|uses| NATUtils
    NetworkProv -->|subprocess shell commands| LinuxStack
    VMProv -->|subprocess shell commands| Hypervisor

    %% Module Dependencies
    UtilsGlobals -.-> CLI
    UtilsGlobals -.-> TopParser
    UtilsGlobals -.-> NetworkProv
    UtilsGlobals -.-> VMProv

    %% Packaging & CI connections
    SetupPy -->|defines CLI| CLI
    Pyproject -->|defines package| CLI
    Requirements -->|deps for| CLI
    InstallScript -->|installs CLI| CLI
    CIApp -->|tests on push| CLI
    CIPub -->|publishes on tag| Packaging
    TestDeployer -->|tests| CLI
    TestNetwork -->|tests| NetworkProv
    TestVM -->|tests| VMProv
    ValidNW -->|sample JSON| TestNetwork

    SampleConfigs -->|reference| TopParser
    SampleConfigs -->|reference| NetworkProv
    SampleConfigs -->|reference| VMProv

    %% Legend
    subgraph Legend
        A[Internal Modules]:::internal
        B[External Systems]:::external
        C[Config & Scripts]:::config
    end

    %% Click Events
    click CLI "https://github.com/vpatel95/topology-deployer/blob/main/deployer/deployer.py"
    click TopParser "https://github.com/vpatel95/topology-deployer/blob/main/deployer/topology.py"
    click NetworkProv "https://github.com/vpatel95/topology-deployer/blob/main/deployer/network.py"
    click NATUtils "https://github.com/vpatel95/topology-deployer/blob/main/deployer/nat_utils.py"
    click VMProv "https://github.com/vpatel95/topology-deployer/blob/main/deployer/virtual_machine.py"
    click UtilsGlobals "https://github.com/vpatel95/topology-deployer/blob/main/deployer/utils.py"
    click SetupPy "https://github.com/vpatel95/topology-deployer/blob/main/setup.py"
    click Pyproject "https://github.com/vpatel95/topology-deployer/blob/main/pyproject.toml"
    click Requirements "https://github.com/vpatel95/topology-deployer/blob/main/requirements.txt"
    click InstallScript "https://github.com/vpatel95/topology-deployer/tree/main/scripts/install"
    click CIApp "https://github.com/vpatel95/topology-deployer/blob/main/.github/workflows/python-app.yml"
    click CIPub "https://github.com/vpatel95/topology-deployer/blob/main/.github/workflows/python-publish.yml"
    click TestDeployer "https://github.com/vpatel95/topology-deployer/blob/main/deployer/tests/test_deployer.py"
    click TestNetwork "https://github.com/vpatel95/topology-deployer/blob/main/deployer/tests/test_network.py"
    click TestVM "https://github.com/vpatel95/topology-deployer/blob/main/deployer/tests/test_virtual_machines.py"
    click ValidNW "https://github.com/vpatel95/topology-deployer/blob/main/deployer/tests/valid_nw.json"
    click SampleConfigs "https://github.com/vpatel95/topology-deployer/tree/main/topologies"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
```
