# 3ware/workflows architecture

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

- Interactive diagram: https://gitdiagram.com/3ware/workflows
- Repository: https://github.com/3ware/workflows

## Overview

##### Project Type and Purpose
- This is an open‑source library of reusable GitHub Actions workflows.
- Its purpose is to package common CI/CD steps (dependency scanning, PR title checks, semantic releases, Terraform docs, etc.) into standalone workflows that other repositories can “call” via GitHub’s `workflow_call` feature.

##### File Structure
- Top‑level files (.editorconfig, .gitignore, CHANGELOG.md, LICENSE) are repository‑level metadata.
- `.github/workflows/` holds each reusable workflow as a separate YAML file:
- dependency-review.yaml
- get-terraform-dir.yaml
- get-workflow-token.yaml
- pr-title.yaml
- release.yaml (semantic‑release)
- scorecard.yaml
- terraform-docs.yaml
- wait-for-checks.yaml
- `.trunk/` contains linting policies (markdownlint, yamllint) enforced via Trunk CI.
- Configuration for semantic‑release, commitlint, Renovate, and Trunk ensure consistent formatting, versioning, and dependency updates.

##### README for Additional Insights
- Each workflow encapsulates a specific task, often invoking a third‑party Action (e.g., `actions/dependency-review-action`, `workflow-application-token-action`, `ossf-scorecard-action`, `tflint/terraform-docs-gh-actions`).
- Some workflows have multi‑step logic: e.g., get-workflow-token generates, encrypts, and outputs a GitHub App token via PGP and base64 to safely pass secrets between jobs.

##### Main Components and Interactions
a. Reusable Workflow Definitions (internal): each YAML file in `.github/workflows/`.
b. GitHub Actions Runner (platform): executes the steps defined by a reusable workflow when invoked.
c. External Actions & Services (external):
- Official Actions (e.g., `dependency-review-action`, `changed‑files`, `ossf-scorecard-action`, `terraform-docs-gh-actions`, `semantic-release`).
- GitHub API (for token generation, status checks, releases).
- GitHub App (installation access token).
- PGP encryption (GPG) for safe secret transport.
d. Consumer Repositories: other GitHub repos that call these workflows
via `uses: 3ware/workflows/.github/workflows/<name>@vX.Y.Z`.

Interactions:
1. A consumer repo’s workflow invokes one of these reusable workflows (`workflow_call`).
2. GitHub Actions runner loads the reusable workflow from this repo.
3. Runner executes each step:
– Calls external actions (e.g., `uses: actions/dependency-review-action`).
– For get-workflow-token: requests a token from the GitHub App, runs a shell step to encrypt it via GPG/base64, sets outputs.
4. Steps pass outputs (encrypted or plain) to subsequent jobs or back to the consumer.
5. Some workflows perform Git operations (e.g., commit updated Terraform docs) using tokens.

##### Architectural Patterns & Design Principles
- Modularization: each CI function lives in its own workflow file.
- “workflow_call” Interface: standardized I/O via inputs/outputs for easy reuse.
- Secrets Handling: encrypt/decrypt secret outputs to avoid leaking.
- Infrastructure as Code: workflows defined declaratively; CI linted via Trunk.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers
    subgraph "Consumer Repositories"
        Consumer["Consumer Repository"]:::consumer
    end

    %% Internal Reusable Workflows
    subgraph "Reusable Workflow Definitions" 
        DR["Dependency Review Workflow"]:::internal
        TDIR["Terraform Directory Resolver Workflow"]:::internal
        TOKEN["Workflow Token Generator"]:::internal
        PRT["Pull Request Title Checker"]:::internal
        REL["Semantic Release Workflow"]:::internal
        SCR["Security Scorecard Workflow"]:::internal
        TDOC["Terraform Docs Generator Workflow"]:::internal
        WAIT["Wait-for-Checks Workflow"]:::internal
        IAC["IAC Deploy Workflow"]:::internal
        PRC["Pull Request Checks Workflow"]:::internal
        CLEAN["Workflow Cleanup"]:::internal
        TRUNK_UP["Trunk CI Upgrade Trigger"]:::internal
    end

    %% Platform
    Runner["GitHub Actions Runner"]:::platform

    %% External Actions & Services
    subgraph "External Actions & Services"
        EA1["actions/dependency-review-action"]:::external
        EA2["changed-files"]:::external
        EA3["ossf-scorecard-action"]:::external
        EA4["terraform-docs-gh-actions"]:::external
        EA5["semantic-release"]:::external
        GitAPI["GitHub API"]:::external
        GPG["PGP Encryption (GPG) & Base64"]:::security
    end

    %% CI Lint & Policy
    subgraph "CI Lint & Policy (Trunk CI)"
        TROOT[".trunk/trunk.yaml"]:::config
        MDL[".trunk/configs/.markdownlint.yaml"]:::config
        YA[".trunk/configs/.yamllint.yaml"]:::config
        TIG[".trunk/.gitignore"]:::config
    end

    %% Repository-wide Configurations
    subgraph "Repository-wide Configurations"
        CML[".commitlintrc.json"]:::config
        RELC[".releaserc.json"]:::config
        REN[".renovaterc.json5"]:::config
        EDIT[".editorconfig"]:::config
        GITI[".gitignore"]:::config
        CODEOWN[".github/CODEOWNERS"]:::config
        README[".github/README.md"]:::config
        CHANGELOG["CHANGELOG.md"]:::config
        LICENSE["LICENSE"]:::config
    end

    %% Interactions
    Consumer -->|"workflow_call"| DR
    Consumer -->|"workflow_call"| TDIR
    Consumer -->|"workflow_call"| TOKEN
    Consumer -->|"workflow_call"| PRT
    Consumer -->|"workflow_call"| REL
    Consumer -->|"workflow_call"| SCR
    Consumer -->|"workflow_call"| TDOC
    Consumer -->|"workflow_call"| WAIT
    Consumer -->|"workflow_call"| IAC
    Consumer -->|"workflow_call"| PRC
    Consumer -->|"workflow_call"| CLEAN
    Consumer -->|"workflow_call"| TRUNK_UP

    DR -->|"executes steps"| Runner
    TDIR -->|"executes steps"| Runner
    TOKEN -->|"executes steps"| Runner
    PRT -->|"executes steps"| Runner
    REL -->|"executes steps"| Runner
    SCR -->|"executes steps"| Runner
    TDOC -->|"executes steps"| Runner
    WAIT -->|"executes steps"| Runner
    IAC -->|"executes steps"| Runner
    PRC -->|"executes steps"| Runner
    CLEAN -->|"executes steps"| Runner
    TRUNK_UP -->|"executes steps"| Runner

    Runner -->|"uses"| EA1
    Runner -->|"uses"| EA2
    Runner -->|"uses"| EA3
    Runner -->|"uses"| EA4
    Runner -->|"uses"| EA5
    Runner -->|"calls API"| GitAPI

    %% Secret subflow for TOKEN
    TOKEN -->|"request token"| GitAPI
    GitAPI -->|"returns token"| TOKEN
    TOKEN -->|"encrypt token"| GPG
    GPG -->|"encrypted output"| Runner

    Runner -->|"outputs results"| Consumer

    %% Click Events Internal Workflows
    click DR "https://github.com/3ware/workflows/blob/main/.github/workflows/dependency-review.yaml"
    click TDIR "https://github.com/3ware/workflows/blob/main/.github/workflows/get-terraform-dir.yaml"
    click TOKEN "https://github.com/3ware/workflows/blob/main/.github/workflows/get-workflow-token.yaml"
    click PRT "https://github.com/3ware/workflows/blob/main/.github/workflows/pr-title.yaml"
    click REL "https://github.com/3ware/workflows/blob/main/.github/workflows/release.yaml"
    click SCR "https://github.com/3ware/workflows/blob/main/.github/workflows/scorecard.yaml"
    click TDOC "https://github.com/3ware/workflows/blob/main/.github/workflows/terraform-docs.yaml"
    click WAIT "https://github.com/3ware/workflows/blob/main/.github/workflows/wait-for-checks.yaml"
    click IAC "https://github.com/3ware/workflows/blob/main/.github/workflows/iac-deploy.yaml"
    click PRC "https://github.com/3ware/workflows/blob/main/.github/workflows/pr-check.yaml"
    click CLEAN "https://github.com/3ware/workflows/blob/main/.github/workflows/delete-workflow-run.yaml"
    click TRUNK_UP "https://github.com/3ware/workflows/blob/main/.github/workflows/trunk-upgrade.yaml"

    %% Click Events Trunk CI
    click TROOT "https://github.com/3ware/workflows/blob/main/.trunk/trunk.yaml"
    click MDL "https://github.com/3ware/workflows/blob/main/.trunk/configs/.markdownlint.yaml"
    click YA "https://github.com/3ware/workflows/blob/main/.trunk/configs/.yamllint.yaml"
    click TIG "https://github.com/3ware/workflows/blob/main/.trunk/.gitignore"

    %% Click Events Repo Config
    click CML "https://github.com/3ware/workflows/blob/main/.commitlintrc.json"
    click RELC "https://github.com/3ware/workflows/blob/main/.releaserc.json"
    click REN "https://github.com/3ware/workflows/blob/main/.renovaterc.json5"
    click EDIT "https://github.com/3ware/workflows/blob/main/.editorconfig"
    click GITI "https://github.com/3ware/workflows/blob/main/.gitignore"
    click CODEOWN "https://github.com/3ware/workflows/tree/main/.github/CODEOWNERS"
    click README "https://github.com/3ware/workflows/blob/main/.github/README.md"
    click CHANGELOG "https://github.com/3ware/workflows/blob/main/CHANGELOG.md"
    click LICENSE "https://github.com/3ware/workflows/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#3498DB
    classDef platform fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#FAD7A0,stroke:#E67E22
    classDef security fill:#E8DAEF,stroke:#8E44AD,stroke-dasharray: 5 5
    classDef config fill:#F2F3F4,stroke:#95A5A6
    classDef consumer fill:#F4F6F6,stroke:#7F8C8D,stroke-dasharray: 2 2
```
