# maxbirkner/terraform-provider-awx architecture

> Architecture diagram of the GitHub repository maxbirkner/terraform-provider-awx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxbirkner/terraform-provider-awx
- Repository: https://github.com/maxbirkner/terraform-provider-awx

## Overview

##### Project Type and Purpose
- This is a Terraform Provider plugin (written in Go) for AWX (Ansible Tower).
- It integrates with Terraform Core to allow users to define AWX resources (organizations, inventories, job templates, etc.) and data-sources in HCL, and reconcile them with an AWX server via its HTTP API.

##### File Structure Analysis
- Top‐level files & folders:
- main.go, go.mod/go.sum, internal/, tools/, examples/, docs/, develop/, test/, Makefile, README.md
- internal/awx/ – Terraform provider implementation: schema, resources, data-sources
- tools/goawx/ – SDK that wraps AWX’s REST API, used by internal/awx
- examples/ – HCL examples for both data-sources and resources
- docs/ – Generated provider documentation
- develop/ – Local development infra (Docker Compose, Terraform, scripts)
- test/ – Acceptance tests against a live AWX instance
- Patterns & config:
- Terraform plugin architecture (provider.go, resource_*.go, data_source_*.go)
- use of Go modules (go.mod), goreleaser for binary distribution

a. Terraform Core and CLI
- The “terraform” binary and core engine that reads HCL, builds plans, invokes providers.
b. AWX Provider Plugin (Go binary)
- main.go: plugin entrypoint
- internal/awx/provider.go: provider schema (hostname, token, insecure)
- internal/awx/resource_*.go & data_source_*.go: CRUD or Read logic
c. goawx SDK (tools/goawx)
- HTTP client library for AWX API endpoints
- Models, request/response types, helpers for pagination, error handling
d. AWX Server (external service)
- Receives REST calls from the provider plugin
e. Development Infrastructure (develop/)
- Local AWX via Docker Compose, Terraform to provision it, scripts for env setup
f. Examples & Docs
- Usage and generate Terraform Registry docs
g. Tests
- test/terraform_minimal_acc_test.go: acceptance tests that drive Terraform against AWX

##### Relationships & Data Flow
- User writes HCL → Terraform CLI
- Terraform Core loads Provider plugin via RPC
- Provider plugin initializes (reads hostname/token), then handles resource/data-source lifecycle calls
- Provider calls goawx SDK methods (HTTP requests) → AWX API
- AWX responds with JSON → goawx → provider code → Terraform Core → State updates
- develop/infra and test harness orchestrate a throw-away AWX instance for development and CI

##### Architectural Patterns & Principles
- Provider Plugin Pattern (RPC‐based plugin interface)
- Separation of Concerns:
- Provider schema & Terraform SDK bits (internal/awx/provider.go)
- Resource/Data-source logic (internal/awx/resource_*.go)
- API client (tools/goawx)
- Reuse: goawx SDK is leveraged rather than hand‐rolling HTTP code
- Infrastructure‐as‐Code (examples/) and Documentation (docs/) aligned with Terraform Registry requirements

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    HCL["HCL Configuration File"]:::user
    click HCL "https://github.com/maxbirkner/terraform-provider-awx/blob/main/examples/provider/provider.tf"

    %% Terraform Core
    TerraformCore["Terraform Core & CLI"]:::user

    %% Provider Plugin
    subgraph "AWX Provider Plugin"  
        direction TB
        Main["main.go"]:::plugin
        ProviderSchema["provider.go\n(schema config)"]:::plugin
        Resources["resource_*.go\n(Resource implementations)"]:::plugin
        DataSources["data_source_*.go\n(Data-source implementations)"]:::plugin
    end
    click Main "https://github.com/maxbirkner/terraform-provider-awx/blob/main/main.go"
    click ProviderSchema "https://github.com/maxbirkner/terraform-provider-awx/blob/main/internal/awx/provider.go"
    click Resources "https://github.com/maxbirkner/terraform-provider-awx/blob/main/internal/awx/resource_*.go"
    click DataSources "https://github.com/maxbirkner/terraform-provider-awx/blob/main/internal/awx/data_source_*.go"

    %% goawx SDK
    subgraph "goawx SDK (API Client)"  
        direction TB
        RequestLib["request.go"]:::sdk
        Types["types.go"]:::sdk
        Models["models & endpoints\n(*.go)"]:::sdk
    end
    click RequestLib "https://github.com/maxbirkner/terraform-provider-awx/blob/main/tools/goawx/request.go"
    click Types "https://github.com/maxbirkner/terraform-provider-awx/blob/main/tools/goawx/types.go"
    click Models "https://github.com/maxbirkner/terraform-provider-awx/tree/main/tools/goawx/"

    %% AWX Server
    AWXServer["AWX Server\n(External HTTP API)"]:::external

    %% Development Infrastructure
    subgraph "Develop Infrastructure"  
        direction TB
        DC["docker-compose.yml"]:::infra
        TFDev["main.tf"]:::infra
        Dockerfile["Dockerfile"]:::infra
    end
    click DC "https://github.com/maxbirkner/terraform-provider-awx/blob/main/develop/docker-compose.yml"
    click TFDev "https://github.com/maxbirkner/terraform-provider-awx/blob/main/develop/main.tf"
    click Dockerfile "https://github.com/maxbirkner/terraform-provider-awx/tree/main/develop/Dockerfile"

    %% Examples & Docs
    subgraph "Examples"  
        direction TB
        ExamplesRes["examples/resources/..."]:::infra
        ExamplesDS["examples/data-sources/..."]:::infra
    end
    click ExamplesRes "https://github.com/maxbirkner/terraform-provider-awx/tree/main/examples/resources/"
    click ExamplesDS "https://github.com/maxbirkner/terraform-provider-awx/tree/main/examples/data-sources/"

    subgraph "Documentation"  
        direction TB
        DocsRes["docs/resources/..."]:::infra
        DocsDS["docs/data-sources/..."]:::infra
    end
    click DocsRes "https://github.com/maxbirkner/terraform-provider-awx/tree/main/docs/resources/"
    click DocsDS "https://github.com/maxbirkner/terraform-provider-awx/tree/main/docs/data-sources/"

    %% Test Suite
    Tests["Acceptance Tests\nterraform_minimal_acc_test.go"]:::infra
    click Tests "https://github.com/maxbirkner/terraform-provider-awx/blob/main/test/terraform_minimal_acc_test.go"

    %% Data Flow
    HCL -->|"reads HCL"| TerraformCore
    TerraformCore -->|"gRPC/Plugin Protocol"| Main
    Main --> ProviderSchema
    ProviderSchema --> Resources
    ProviderSchema --> DataSources
    Resources --> goawxCall[/"Invokes goawx SDK"/]:::plugin
    DataSources --> goawxCall
    goawxCall --> RequestLib
    RequestLib --> Types
    Types --> Models
    Models -->|"HTTP Request"| AWXServer
    AWXServer -->|"HTTP Response JSON"| Models
    Models --> Types
    Types --> RequestLib
    RequestLib --> goawxCall
    goawxCall --> Resources
    goawxCall --> DataSources
    Resources --> TerraformCore
    DataSources --> TerraformCore

    %% Test flow
    Tests -->|"drives"| TerraformCore
    DC --> AWXServer
    TFDev --> AWXServer

    %% Styling
    classDef user fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef plugin fill:#bbdefb,stroke:#1565c0,color:#1565c0
    classDef sdk fill:#bbdefb,stroke:#1565c0,color:#1565c0
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef infra fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
