# isaeken/vpc-provisioner architecture

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

- Interactive diagram: https://gitdiagram.com/isaeken/vpc-provisioner
- Repository: https://github.com/isaeken/vpc-provisioner

## Overview

##### Project Type and Purpose
- This is a Node.js package aimed at simplifying VM provisioning tasks on a hypervisor. The README clearly states that it automates VM creation (including ISO image creation using cloud configs) and provides some basic management features like starting, stopping, and rebooting VMs. It is designed to work with KVM (with plans to add other hypervisor support in the roadmap).

##### File Structure
- Directory Structure:
– At the top level, along with common configuration files (.editorconfig, .env.example, tsconfig.json), you have logs, mocks, and package.json. This indicates that the project involves configuration management and a logging system, plus built-in mocks for testing or simulation purposes (e.g., Ubuntu 22.04 configuration files).
– The src directory is the core of the package:
▸ The “hypervisors” folder contains the abstraction for hypervisor operations (hypervisor.ts) and its implementations (such as kvm-hypervisor.ts). This implies an architectural pattern that supports multiple hypervisor types via polymorphism or interface-based design.
▸ The “services” folder holds components like the iso-builder (which likely deals with generating cloud config ISO images).
▸ The “types” folder defines TypeScript type definitions for configuration and hypervisor-related interfaces, establishing clear contracts between components.
▸ The “utils” folder provides helper functions such as hash and network utilities.
– The entry-point (src/index.ts) likely coordinates all these components.

##### Key Components and Their Relationships
- Main Components:
– Entry Point: Initializes and orchestrates the provisioning process.
– Hypervisor Module:
▸ An abstraction layer (hypervisor.ts) that defines common hypervisor operations.
▸ Specific implementations like kvm-hypervisor.ts which handle KVM-specific logic.
– ISO Builder Service (services/iso-builder.ts):
▸ Responsible for creating ISO images based on cloud configuration data.
– Logger (src/logger.ts): Provides logging throughout the system.
– Utility Functions (src/utils): Supports various supporting tasks such as network operations or hash functions.
– Type Definitions (src/types): Used across the system to ensure type safety and enforce contracts.
– Mocks (mocks/ubuntu-22.04): Represent sample data (metadata, network, user data) that mimics what might be used in a live environment.
- Interactions and Data Flow:
– The entry point (src/index.ts) acts as the coordinator, reading configurations (.env.example) and calling services.
– When a VM provisioning request is received, it likely triggers the ISO builder service to generate an ISO image and then delegates actions such as start, stop, and network configuration to the hypervisor module.
– The hypervisor module abstracts the specific hypervisor operations; currently, the KVM implementation (kvm-hypervisor.ts) is in use.
– Logs are recorded via the logging component to track operations.
– Utility modules and type definitions are used by both the hypervisor and iso-builder service to ensure consistency and reliability.

##### Architectural Patterns & Design Principles
- Modular Design: The separation into hypervisors, services, types, and utilities suggests a modular approach for better maintainability and potential extensibility.
- Abstraction & Interface Implementation: The hypervisor abstraction allows for future support of additional hypervisors (like VMware, OpenStack, Proxmox), as mentioned in the roadmap.
- Configuration Driven: Use of .env and config drive types indicates an emphasis on external configuration and flexibility.
- Testability: The presence of a mocks directory shows that the design likely facilitates testing with simulated environments.

a. Main Components:
– Entry Point / Orchestrator: Represented by src/index.ts.
– Logger & Utilities: Group these supporting components (logger, hash, net) in a common “Utilities” section.
– Config & Mocks: Outside the core processing, include external configuration (from .env.example) and the mocks folder which provides virtual machine data configurations.
b. Relationships and Interactions:
c. Important architectural patterns:
– Mark the modular and extensible nature of the hypervisor abstraction.
– Emphasize the separation between the “control logic” (entry point/orchestration) and the “action implementations” (hypervisor and service modules).
d. Label Technologies and Frameworks:
– Note that it’s written in Node.js/TypeScript, marking areas where type definitions and module systems play crucial roles.
– Indicate use of libraries or frameworks if known (for example, express any library patterns if used by logger or utilities).

- External dependencies (like configuration inputs and mocks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration"
        entryPoint["Entry Point (src/index.ts)"]
        logger["Logger (src/logger.ts)"]
    end

    %% Hypervisor Modules
    subgraph "Hypervisor Modules"
        hypervisorAbs["Hypervisor Abstraction (src/hypervisors/hypervisor.ts)"]
        kvmImpl["KVM Implementation (src/hypervisors/kvm-hypervisor.ts)"]
    end

    %% Services
    subgraph "Services"
        isoBuilder["ISO Builder Service (src/services/iso-builder.ts)"]
    end

    %% Support Modules
    subgraph "Support Modules"
        utilities["Utility Functions (src/utils)"]
        typeDefs["Type Definitions (src/types)"]
    end

    %% External Configurations
    subgraph "External Configurations"
        config["Configuration Input (.env.example)"]
        mocks["Mocks (mocks/ubuntu-22.04)"]
    end

    %% Relationships
    config -->|"loads"| entryPoint
    mocks -->|"provides_sample_data"| entryPoint
    entryPoint -->|"calls"| isoBuilder
    entryPoint -->|"delegates_to"| hypervisorAbs
    entryPoint -->|"logs_to"| logger
    hypervisorAbs -->|"implements_by"| kvmImpl
    isoBuilder -->|"uses"| utilities
    isoBuilder -->|"uses"| typeDefs
    hypervisorAbs -->|"uses"| utilities
    hypervisorAbs -->|"uses"| typeDefs

    %% Click Events
    click entryPoint "https://github.com/isaeken/vpc-provisioner/blob/main/src/index.ts"
    click logger "https://github.com/isaeken/vpc-provisioner/blob/main/src/logger.ts"
    click hypervisorAbs "https://github.com/isaeken/vpc-provisioner/blob/main/src/hypervisors/hypervisor.ts"
    click kvmImpl "https://github.com/isaeken/vpc-provisioner/blob/main/src/hypervisors/kvm-hypervisor.ts"
    click isoBuilder "https://github.com/isaeken/vpc-provisioner/blob/main/src/services/iso-builder.ts"
    click utilities "https://github.com/isaeken/vpc-provisioner/tree/main/src/utils"
    click typeDefs "https://github.com/isaeken/vpc-provisioner/tree/main/src/types"
    click config "https://github.com/isaeken/vpc-provisioner/blob/main/.env.example"
    click mocks "https://github.com/isaeken/vpc-provisioner/blob/main/mocks/ubuntu-22.04"

    %% Styles
    classDef orchestration fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef hypervisor fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef services fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef support fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class entryPoint,logger orchestration;
    class hypervisorAbs,kvmImpl hypervisor;
    class isoBuilder services;
    class utilities,typeDefs support;
    class config,mocks external;
```
