# infraweave-io/actions architecture

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

- Interactive diagram: https://gitdiagram.com/infraweave-io/actions
- Repository: https://github.com/infraweave-io/actions

## Overview

##### Project Type and Purpose
- This is an open‐source GitHub Actions toolkit.
- It provides ready‐to‐use workflows (`test-module`, `publish-module`, `test-stack`, `publish-stack`) that integrate Terraform, TFLint, Python tests, and Terraform‐related publishing.
- The consumers are any Terraform module or stack repository that adopts these workflows by referencing them in their own `.github/workflows` folder.

##### Core Components
A. Consumer Repository
- Holds Terraform definitions under `src/` and tests under `tests/`.
- Defines workflow files in `.github/workflows/` (e.g. `test.yaml`, `publish-module.yaml`).
B. GitHub Actions Runner
- GitHub‐hosted runner that executes jobs on `ubuntu-latest`.
C. InfraWeave Actions Repository
- The upstream actions definitions hosted at `infraweave-io/actions/.github/workflows/...`
- Versioned by commit SHA (e.g. `@8ba76f33...`).
D. Terraform & TFLint
- `hashicorp/setup-terraform@v2` for Terraform CLI.
- TFLint installed via shell script.
E. Python Test Harness
- Finds and runs `tests/*.py` in parallel.
F. AWS Accounts & OIDC
- Uses GitHub’s OpenID Connect (id-token) to assume roles in Central and Workload accounts (via `central_account_id` and `workload_account_id`).
G. Artifact/Module Registry
- Terraform module registry (or custom registry) where modules/stacks are published.

##### Interactions and Data Flow
1. Developer pushes code (or manually dispatches) → triggers workflow in consumer repo.
2. Runner checks out code.
3. For testing modules:
- Runner sets up Terraform → runs TFLint → runs `terraform init/validate`.
- Then invokes the remote `test-module.yaml` action from InfraWeave.
- That action uses OIDC to get AWS credentials → runs Python tests.
4. For publishing modules or stacks:
- Runner dispatches remote `publish-module.yaml` or `publish-stack.yaml`.
- That action retrieves credentials via OIDC → packages & pushes artifacts to the registry.

##### Architectural Patterns & Design Principles
- Reusability: Core workflows are centralized in InfraWeave’s Actions repo and versioned.
- Separation of Concerns: Consumer repo only references workflows; all testing, linting, publishing logic lives upstream.
- Declarative Pipeline: Workflows define high-level jobs that call modular, parametrized actions.
- Secure Credentials via OIDC: No long‐lived secrets, just ephemeral AWS tokens.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and GitHub
    Developer(("Developer")):::actor
    GitHub["GitHub.com"]:::github
    Developer -->|"push / workflow_dispatch"| GitHub

    subgraph "Consumer Repository"
        direction TB
        TestModuleWF["test-module.yaml"]:::github
        PublishModuleWF["publish-module.yaml"]:::github
        TestStackWF["test-stack.yaml"]:::github
        PublishStackWF["publish-stack.yaml"]:::github
        VersionWF["version.yaml"]:::github
        README["README.md"]:::external
        LICENSE["LICENSE / NOTICE"]:::external
    end

    GitHub -->|"trigger workflow"| TestModuleWF
    GitHub -->|"trigger workflow"| PublishModuleWF
    GitHub -->|"trigger workflow"| TestStackWF
    GitHub -->|"trigger workflow"| PublishStackWF
    GitHub -->|"trigger workflow"| VersionWF

    click TestModuleWF "https://github.com/infraweave-io/actions/blob/main/.github/workflows/test-module.yaml"
    click PublishModuleWF "https://github.com/infraweave-io/actions/blob/main/.github/workflows/publish-module.yaml"
    click TestStackWF "https://github.com/infraweave-io/actions/blob/main/.github/workflows/test-stack.yaml"
    click PublishStackWF "https://github.com/infraweave-io/actions/blob/main/.github/workflows/publish-stack.yaml"
    click VersionWF "https://github.com/infraweave-io/actions/blob/main/.github/workflows/version.yaml"
    click README "https://github.com/infraweave-io/actions/blob/main/README.md"
    click LICENSE "https://github.com/infraweave-io/actions/tree/main/LICENSE"

    %% Runner and local steps
    subgraph "GitHub Actions Runner" 
        direction TB
        Runner["Runner<br/>(ubuntu-latest)"]:::github
        Checkout["Checkout Code"]:::process
        Terraform["Terraform CLI & TFLint"]:::terraform
        Runner --> Checkout
        Checkout --> Terraform
        Terraform -->|"terraform init/validate & lint"| Runner
    end

    %% Remote Actions and External Services
    subgraph "InfraWeave Actions Repo" 
        direction TB
        InfraRepo[".github/workflows/..."]:::external
    end

    %% AWS and OIDC
    subgraph AWS
        direction TB
        OIDC["GitHub OIDC Token"]:::aws
        STS["AWS STS / Assume-Role"]:::aws
    end

    PythonTests["Python Test Harness"]:::process
    Registry["Terraform Module Registry"]:::external

    %% Flows from Runner
    TestModuleWF --> Runner
    PublishModuleWF --> Runner
    TestStackWF --> Runner
    PublishStackWF --> Runner
    VersionWF --> Runner

    Runner -->|"uses: test-module.yaml@SHA"| InfraRepo
    Runner -->|"uses: publish-module.yaml@SHA"| InfraRepo
    Runner -->|"uses: test-stack.yaml@SHA"| InfraRepo
    Runner -->|"uses: publish-stack.yaml@SHA"| InfraRepo

    Runner -->|"assume-role via OIDC"| OIDC
    OIDC --> STS
    STS --> PythonTests
    Runner --> PythonTests

    Runner -->|"publish artifacts"| Registry

    %% Styles
    classDef actor fill:#E3F2FD,stroke:#90CAF9
    classDef github fill:#BBDEFB,stroke:#1E88E5
    classDef terraform fill:#C8E6C9,stroke:#43A047
    classDef aws fill:#FFE0B2,stroke:#FB8C00
    classDef external fill:#CFD8DC,stroke:#607D8B
    classDef process fill:#F5F5F5,stroke:#BDBDBD
```
