# azure/aztfexport architecture

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

- Interactive diagram: https://gitdiagram.com/azure/aztfexport
- Repository: https://github.com/azure/aztfexport

## Overview

##### Main Components
- CLI/User Interface Layer: This repository has an interactive “config” command interface (internal/ui and related subpackages) that handles user inputs and shows progress, e.g., via spinner or progress bars.
- Configuration Management: This is handled in packages such as internal/config and pkg/config where either interactive or noninteractive configuration is set up, including reading and writing to the configuration file at $HOME/.aztfexport/config.json.
- Azure Resource Discovery and Client: The client subpackage (internal/client, internal/ui/aztfexportclient) is dedicated to interfacing with Azure services, retrieving resource identifiers, and working with external Azure authentication (e.g., auth_oidc.go).
- Mapping and Meta Processing: The “meta” packages (internal/meta and pkg/meta) along with resource mapping (internal/resmap and internal/resourceset) handle the translation of Azure resource IDs into Terraform resource types and generate metadata required for import.
- Terraform Integration: The tool interacts with Terraform by running commands like “terraform import” and then using external tools (tfadd) to generate valid HCL code. This can be depicted as an integration point after the Azure resource data is processed.
- Telemetry and Logging: With packages such as pkg/telemetry and internal/log, telemetry data (including the “installation_id” used to track configuration changes) and log outputs are managed.
- Testing and Validation: The extensive testing directory (internal/test with subdirectories for cases, queries, resource group tests, etc.) ensures that the resource extraction and Terraform state import work correctly.
- Packaging and Deployment: The presence of Docker, GitHub workflows, azure-pipelines, and packaging scripts (in the scripts folder) indicates how the app is containerized, built, and released through CI/CD pipelines.

##### Relationships and Data Flow
- User triggers the tool through a command-line interface which routes commands to the UI layer.
- The UI and configuration components read the necessary settings (like telemetry and installation IDs) from the config files.
- The client component then interacts with Azure, retrieving the list of resources to be managed.
- The meta and resource mapping components then take over to correlate the Azure resource IDs with a Terraform resource type (leveraging external libraries like aztft and tfadd).
- Once mapping is done, the tool issues “terraform import” commands to establish the resource state and then generates the corresponding HCL configuration.
- Telemetry and logging modules collect runtime data and log outputs during processing.
- Testing and internal utilities validate the processes, ensuring consistency between the remote state and generated configuration.

##### Architectural Patterns and Design Principles
- Modularity: The project clearly separates core functionalities into discrete internal packages (e.g., config, client, meta, ui) increasing maintainability.
- Separation of Concerns: Different layers (UI, business logic, integrations) are kept in separate packages.
- Extensibility: Creating and updating different resource types is simplified through the meta and resource mapping layers.
- CI/CD Integration: The inclusion of Docker and GitHub workflow configuration highlights an emphasis on automated testing and deployments.

##### Technologies and Frameworks Highlighted
- Go: The entire codebase is written in Go and uses its module system (go.mod) for dependency management.
- Terraform: The tool both calls Terraform and generates Terraform configurations.
- Azure Integration: The tool leverages external tools for identifying and managing Azure resources.
- External Tools: It interacts with “aztft” and “tfadd” – libraries designed for identifying correct Terraform resource types and generating HCL configurations.

- At the top level, place “User/CLI” as the start point.
- A split from CLI into “Configuration Management” and “Command Dispatcher.”
- Next, direct flow to “Resource Mapping & Meta Processing” which invokes external libraries (“aztft” and “tfadd”).
- Side connections should indicate “Telemetry / Logging” collecting data from each step.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserCLI("User/CLI"):::user

    subgraph "User Interface Layer"
        CLIUI("CLI/UI - internal/ui"):::ui
        CLIProgress("Progress - internal/ui/progress/progress.go"):::ui
    end

    subgraph "Configuration Management"
        ConfigInteractive("Config Interactive - internal/config/config_interactive.go"):::config
        ConfigNonInteractive("Config NonInteractive - internal/config/config_noninteractive.go"):::config
        ConfigPkg("Config Package - pkg/config/config.go"):::config
    end

    subgraph "Azure Resource Discovery and Client"
        AzureClient("Azure Client - internal/client/client.go"):::azure
        AzureAuth("Azure Auth - auth_oidc.go"):::azure
        AzureClientUI("Azure Client UI - internal/ui/aztfexportclient/client.go"):::azure
    end

    subgraph "Resource Mapping & Meta Processing"
        MetaMap("Meta Map - internal/meta/meta_map.go"):::mapping
        ImportList("Import List - internal/meta/importlist.go"):::mapping
        Resmap("Resource Mapping - internal/resmap/resmap.go"):::mapping
        ResourceSet("Resource Set - internal/resourceset/azure_resource_set.go"):::mapping
    end

    subgraph "Terraform Integration"
        TfAddr("Terraform Addr - internal/tfaddr/tf_addr.go"):::terraform
        Main("Main Process - main.go"):::terraform
    end

    subgraph "Telemetry and Logging"
        Telemetry("Telemetry - pkg/telemetry/telemetry.go"):::telemetry
        Log("Logging - internal/log/log.go"):::telemetry
    end

    subgraph "Testing & Validation"
        Testing("Testing Module - internal/test"):::testing
    end

    subgraph "Packaging & Deployment"
        Packaging("Packaging Scripts - scripts/package"):::packaging
        GitHubWorkflows1("GitHub Workflow CodeQL - .github/workflows/codeql.yml"):::packaging
        GitHubWorkflows2("GitHub Workflow PR - .github/workflows/pr.yaml"):::packaging
        AzurePipeline("Azure Pipelines - azure-pipelines-ci.yml"):::packaging
        Devcontainer("Dev Container - .devcontainer"):::packaging
    end

    %% Main Flow
    UserCLI -->|"triggers"| CLIUI
    CLIUI -->|"readsConfig"| ConfigInteractive
    ConfigInteractive -->|"providesSettings"| AzureClient
    AzureClient -->|"fetchesResources"| MetaMap
    MetaMap -->|"mapsResources"| TfAddr
    TfAddr -- "feedback" --> MetaMap
    TfAddr -->|"executesImport"| Main

    %% Telemetry connections
    CLIUI --> Telemetry
    ConfigInteractive --> Telemetry
    AzureClient --> Telemetry
    MetaMap --> Telemetry
    TfAddr --> Telemetry

    %% Testing connections (dashed lines)
    CLIUI -.-> Testing
    ConfigInteractive -.-> Testing
    AzureClient -.-> Testing
    MetaMap -.-> Testing
    TfAddr -.-> Testing

    %% Packaging connections (dashed lines)
    Packaging -.-> Main
    GitHubWorkflows1 -.-> Main
    GitHubWorkflows2 -.-> Main
    AzurePipeline -.-> Main
    Devcontainer -.-> Main

    %% Click Events
    click CLIUI "https://github.com/azure/aztfexport/tree/main/internal/ui"
    click CLIProgress "https://github.com/azure/aztfexport/blob/main/internal/ui/progress/progress.go"
    click ConfigInteractive "https://github.com/azure/aztfexport/blob/main/internal/config/config_interactive.go"
    click ConfigNonInteractive "https://github.com/azure/aztfexport/blob/main/internal/config/config_noninteractive.go"
    click ConfigPkg "https://github.com/azure/aztfexport/blob/main/pkg/config/config.go"
    click AzureClient "https://github.com/azure/aztfexport/blob/main/internal/client/client.go"
    click AzureAuth "https://github.com/azure/aztfexport/blob/main/auth_oidc.go"
    click AzureClientUI "https://github.com/azure/aztfexport/blob/main/internal/ui/aztfexportclient/client.go"
    click MetaMap "https://github.com/azure/aztfexport/blob/main/internal/meta/meta_map.go"
    click ImportList "https://github.com/azure/aztfexport/blob/main/internal/meta/importlist.go"
    click Resmap "https://github.com/azure/aztfexport/blob/main/internal/resmap/resmap.go"
    click ResourceSet "https://github.com/azure/aztfexport/blob/main/internal/resourceset/azure_resource_set.go"
    click TfAddr "https://github.com/azure/aztfexport/blob/main/internal/tfaddr/tf_addr.go"
    click Main "https://github.com/azure/aztfexport/blob/main/main.go"
    click Telemetry "https://github.com/azure/aztfexport/blob/main/pkg/telemetry/telemetry.go"
    click Log "https://github.com/azure/aztfexport/blob/main/internal/log/log.go"
    click Testing "https://github.com/azure/aztfexport/tree/main/internal/test"
    click Packaging "https://github.com/azure/aztfexport/tree/main/scripts/package"
    click GitHubWorkflows1 "https://github.com/azure/aztfexport/blob/main/.github/workflows/codeql.yml"
    click GitHubWorkflows2 "https://github.com/azure/aztfexport/blob/main/.github/workflows/pr.yaml"
    click AzurePipeline "https://github.com/azure/aztfexport/blob/main/azure-pipelines-ci.yml"
    click Devcontainer "https://github.com/azure/aztfexport/blob/main/.devcontainer"

    %% Styles
    classDef ui fill:#f4a261,stroke:#000,stroke-width:2px;
    classDef config fill:#e9c46a,stroke:#000,stroke-width:2px;
    classDef azure fill:#2a9d8f,stroke:#000,stroke-width:2px;
    classDef mapping fill:#e76f51,stroke:#000,stroke-width:2px;
    classDef terraform fill:#264653,stroke:#fff,stroke-width:2px;
    classDef telemetry fill:#8ab17d,stroke:#000,stroke-width:2px;
    classDef testing fill:#a8dadc,stroke:#000,stroke-width:2px;
    classDef packaging fill:#bababa,stroke:#000,stroke-width:2px;
    classDef user fill:#FF8C00,stroke:#000,stroke-width:2px;

    class UserCLI user;
```
