# newrelic-experimental/deployer architecture

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

- Interactive diagram: https://gitdiagram.com/newrelic-experimental/deployer
- Repository: https://github.com/newrelic-experimental/deployer

## Overview

##### Project Type and Purpose
- This is an open-source, multi-cloud deployment and orchestration CLI tool (Ruby) that manages configuration, validation, templating, provisioning, deployment, instrumentation, installation, teardown, and summary across AWS, Azure, and GCP.
- The core value is a pluggable, provider-agnostic orchestration engine with built-in validators and template generators.

##### Main Architectural Components
A. CLI Layer
- main.rb, batch.rb, Rakefile
- Command-line parser & dispatcher (`src/command_line`, `src/batch/command_line`)
B. Configuration Layer
- User config loader & validator (`src/user_config`)
- Application config loader & validator (`src/app_config`)
- Static templates & credentials (`configs/`)
C. Core Orchestrator
- `src/orchestrator.rb`, `src/configuration_orchestrator.rb`
- Dispatches execution to each domain orchestrator
D. Domain Modules (each with: orchestrator, provider interface, validators)
1. services (`src/services`)
2. deployment (`src/deployment`)
3. infrastructure (`src/infrastructure`)
4. install (`src/install`)
5. instrumentation (`src/instrumentation`)
6. provision (`src/provision`)
7. teardown (`src/teardown`)
8. summary (`src/summary`)
9. tags (`src/tags`)
E. Common Utilities
- Logging, I/O, YAML/JSON parsing (`src/common`)
- Template merging engine (`src/common/template_merger`)
- Ansible integration (`src/common/ansible`)
F. Cloud Provider Adapters
- AWS, Azure, GCP implementations under each domain module
- Template builders & contexts (`src/provision/templates`)
G. External Services
- Cloud APIs (AWS SDK, Azure SDK, GCP SDK)
- Git (repo cloning, versioning)
- Ansible (playbooks via `common/ansible`)
H. Tests & Documentation
- Comprehensive unit/integration tests (`tests/`, `user_acceptance_tests/`)
- On-repo documentation (`documentation/`)

##### Interactions & Data Flow
2. Parser → Core Orchestrator → Configuration Orchestrator (blue)
a. services → defines service metadata
b. deployment → validates and transforms deployment settings
c. infrastructure → generates resource definitions
d. install → builds instrumentation/install definitions
e. instrumentation → injects instrumentor metadata
f. provision → uses Template Engine to generate cloud-specific templates
g. teardown → similar flow removing resources
h. summary/tags → composes output JSON or logs
5. Throughout, Common Utilities (purple) provide I/O, logging, YAML/JSON, Git, Ansible calls.

##### Architectural Patterns & Design Principles
- Orchestrator Pattern: each domain has an orchestrator + sub-orchestrators
- Provider/Strategy Pattern: pluggable cloud-specific adapters implementing uniform interfaces
- Validator Chain: configurable validators per domain and provider
- Template-Driven Provisioning: ERB and Jinja2 templates, context builders
- Single Responsibility & Separation of Concerns: config, domain logic, templating, CLI, utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Main["main.rb"]:::cli
        click Main "https://github.com/newrelic-experimental/deployer/blob/main/./main.rb"
        Batch["batch.rb"]:::cli
        click Batch "https://github.com/newrelic-experimental/deployer/blob/main/./batch.rb"
        Rake["Rakefile"]:::cli
        click Rake "https://github.com/newrelic-experimental/deployer/tree/main/./Rakefile"
        CLIP["CommandLine Parser"]:::cli
        click CLIP "https://github.com/newrelic-experimental/deployer/blob/main/src/command_line/parser.rb"
        CLIO["CLI Orchestrator"]:::cli
        click CLIO "https://github.com/newrelic-experimental/deployer/blob/main/src/command_line/orchestrator.rb"
        CLIPR["CLI Provider"]:::cli
        click CLIPR "https://github.com/newrelic-experimental/deployer/blob/main/src/command_line/provider.rb"
        CLIV["CLI Validator"]:::cli
        click CLIV "https://github.com/newrelic-experimental/deployer/blob/main/src/command_line/validator.rb"
        subgraph "Batch CLI"
            direction TB
            BParser["Batch Parser"]:::cli
            click BParser "https://github.com/newrelic-experimental/deployer/blob/main/src/batch/command_line/parser.rb"
            BProv["Batch Provider"]:::cli
            click BProv "https://github.com/newrelic-experimental/deployer/blob/main/src/batch/command_line/provider.rb"
            BVal["Batch Validator"]:::cli
            click BVal "https://github.com/newrelic-experimental/deployer/blob/main/src/batch/command_line/validator.rb"
            BInt["Integer Validator"]:::cli
            click BInt "https://github.com/newrelic-experimental/deployer/blob/main/src/batch/command_line/is_integer_validator.rb"
            BMod["Mode Validator"]:::cli
            click BMod "https://github.com/newrelic-experimental/deployer/blob/main/src/batch/command_line/is_mode_validator.rb"
        end
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        UCOrch["UserConfig Orchestrator"]:::config
        click UCOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/user_config/orchestrator.rb"
        UCPars["UserConfig Parser"]:::config
        click UCPars "https://github.com/newrelic-experimental/deployer/blob/main/src/user_config/parser.rb"
        UCProv["UserConfig Provider"]:::config
        click UCProv "https://github.com/newrelic-experimental/deployer/blob/main/src/user_config/provider.rb"
        UCVld["UserConfig Validators"]:::config
        click UCVld "https://github.com/newrelic-experimental/deployer/tree/main/src/user_config/validators/"
        ACCOrch["AppConfig Orchestrator"]:::config
        click ACCOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/app_config/orchestrator.rb"
        ACMerge["AppConfig Merge"]:::config
        click ACMerge "https://github.com/newrelic-experimental/deployer/blob/main/src/app_config/merge_files.rb"
        ACProv["AppConfig Provider"]:::config
        click ACProv "https://github.com/newrelic-experimental/deployer/blob/main/src/app_config/provider.rb"
        ACVal["AppConfig Validator"]:::config
        click ACVal "https://github.com/newrelic-experimental/deployer/blob/main/src/app_config/validator.rb"
        Configs["Static Configs"]:::config
        click Configs "https://github.com/newrelic-experimental/deployer/tree/main/configs/"
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        direction TB
        CoreOrch["orchestrator.rb"]:::orch
        click CoreOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/orchestrator.rb"
        ConfigOrch["configuration_orchestrator.rb"]:::orch
        click ConfigOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/configuration_orchestrator.rb"
    end

    %% Data Model
    ConfigModel(["In-memory Config Model"]):::data

    %% Domain Modules
    subgraph "Domain Modules"
        direction TB
        subgraph Services
            direction TB
            SOrch["services/orchestrator.rb"]:::domain
            click SOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/services/orchestrator.rb"
            SProv["services/provider.rb"]:::domain
            click SProv "https://github.com/newrelic-experimental/deployer/blob/main/src/services/provider.rb"
        end
        subgraph Deployment
            direction TB
            DOrch["deployment/orchestrator.rb"]:::domain
            click DOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/deployment/orchestrator.rb"
            DProv["deployment/provider.rb"]:::domain
            click DProv "https://github.com/newrelic-experimental/deployer/blob/main/src/deployment/provider.rb"
        end
        subgraph Infrastructure
            direction TB
            IOrch["infrastructure/orchestrator.rb"]:::domain
            click IOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/infrastructure/orchestrator.rb"
            IProv["infrastructure/provider.rb"]:::domain
            click IProv "https://github.com/newrelic-experimental/deployer/blob/main/src/infrastructure/provider.rb"
        end
        subgraph Install
            direction TB
            InstOrch["install/orchestrator.rb"]:::domain
            click InstOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/install/orchestrator.rb"
            InstProv["install/provider.rb"]:::domain
            click InstProv "https://github.com/newrelic-experimental/deployer/blob/main/src/install/provider.rb"
        end
        subgraph Provision
            direction TB
            POrch["provision/orchestrator.rb"]:::domain
            click POrch "https://github.com/newrelic-experimental/deployer/blob/main/src/provision/orchestrator.rb"
            PProv["provision/provider.rb"]:::domain
            click PProv "https://github.com/newrelic-experimental/deployer/blob/main/src/provision/provider.rb"
        end
        subgraph Teardown
            direction TB
            TOrch["teardown/orchestrator.rb"]:::domain
            click TOrch "https://github.com/newrelic-experimental/deployer/blob/main/src/teardown/orchestrator.rb"
        end
        subgraph Summary
            direction TB
            SOrch2["summary/orchestrator.rb"]:::domain
            click SOrch2 "https://github.com/newrelic-experimental/deployer/blob/main/src/summary/orchestrator.rb"
        end
        subgraph Tags
            direction TB
            TOrch2["tags/orchestrator.rb"]:::domain
            click TOrch2 "https://github.com/newrelic-experimental/deployer/blob/main/src/tags/orchestrator.rb"
        end
    end

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        CU["src/common"]:::util
        click CU "https://github.com/newrelic-experimental/deployer/tree/main/src/common/"
        TM["template_merger.rb"]:::util
        click TM "https://github.com/newrelic-experimental/deployer/blob/main/src/common/template_merger.rb"
        ANS["ansible integration"]:::util
        click ANS "https://github.com/newrelic-experimental/deployer/tree/main/src/common/ansible/"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AWSCloud(["AWS SDK"]):::external
        AzureCloud(["Azure SDK"]):::external
        GCPCloud(["GCP SDK"]):::external
        Git(["Git"]):::external
    end

    %% Data Flows
    Main -->|"invoke"| CLIP
    CLIP -->|"dispatch"| CoreOrch
    CoreOrch -->|"config orchestrate"| ConfigOrch
    ConfigOrch -->|"load→validate→model"| Configs
    ConfigOrch --> ConfigModel
    ConfigModel --> Services
    ConfigModel --> Deployment
    ConfigModel --> Infrastructure
    ConfigModel --> Install
    ConfigModel --> Provision
    ConfigModel --> Teardown
    ConfigModel --> Summary
    ConfigModel --> Tags
    Provision -->|"generate template"| PProv
    PProv -->|"apply"| AWSCloud
    PProv --> AzureCloud
    PProv --> GCPCloud
    TOrch -->|"teardown resources"| AWSCloud
    TOrch --> AzureCloud
    TOrch --> GCPCloud
    Services --> CU
    Deployment --> CU
    Infrastructure --> CU
    Install --> CU
    Provision --> CU
    Teardown --> CU
    Summary --> CU
    Tags --> CU
    CU --> Git
    CU --> ANS

    %% Legend
    subgraph "Legend"
        CLI["CLI Layer"]:::cli
        Config["Configuration Layer"]:::config
        Orch["Orchestrators"]:::orch
        Data["Data Model"]:::data
        Domain["Domain Modules"]:::domain
        Util["Common Utilities"]:::util
        Ext["External Services"]:::external
    end

    %% Styles
    classDef cli fill:#D0E7FF,stroke:#0288D1,color:#000;
    classDef config fill:#E8F5E9,stroke:#43A047,color:#000;
    classDef orch fill:#BBDEFB,stroke:#1976D2,color:#000;
    classDef data fill:#C8E6C9,stroke:#388E3C,color:#000,shape:cylinder;
    classDef domain fill:#FFE0B2,stroke:#FB8C00,color:#000;
    classDef util fill:#E1BEE7,stroke:#8E24AA,color:#000;
    classDef external fill:#FFCDD2,stroke:#E53935,color:#000;
```
