# ipdxco/github-as-code architecture

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

- Interactive diagram: https://gitdiagram.com/ipdxco/github-as-code
- Repository: https://github.com/ipdxco/github-as-code

## Overview

##### Project type and purpose
- This is an open-source “GitHub Management as Code” template, designed to manage GitHub organization settings (repos, teams, labels, branch protections, etc.) via declarative configuration files and CI/CD.
- The README and docs emphasize it’s a framework that uses pull requests, GitHub Actions, Terraform, and custom TypeScript scripts to enforce and sync org-wide policies.

##### File structure
- Top-level:
- .github/ – pull-request and workflow definitions
- docs/ – markdown guides (ABOUT, SETUP, HOWTOS)
- files/ – example files
- github/ – schema and organization config YAML templates
- scripts/ – CLI code in TypeScript (actions/, resources/, terraform/, yaml/) with tests
- terraform/ – Terraform modules and state files for bootstrapping
- Key patterns:
- CI/CD pipelines in .github/workflows invoke scripts and Terraform.
- “scripts” directory follows a resource-action pattern (CRUD on GitHub entities).
- Terraform is used both natively (terraform/) and via autogenerated TS (scripts/src/terraform).

##### README for additional insights
- The system’s core is merging config PRs to update multiple orgs.
- It relies on GitHub Actions for orchestration, TypeScript for API logic, and Terraform for stateful bootstrap.

##### Detail
- Versioning/state (Terraform lock file, state file)
- Schema validation phase and config directories

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and external
    Dev["Developer"]:::actor
    TargetOrgs["Target GitHub Orgs & Repos"]:::external

    %% Management Repository grouping
    subgraph "Management Repository (Code & Config)" 
        direction TB
        RepoRoot["/"]:::code

        subgraph "CI/CD Workflows" 
            direction TB
            Workflows[".github/workflows/*.yml"]:::ci
        end

        subgraph "Custom GitHub Actions"
            direction TB
            LocalActions[".github/actions/"]:::ci
        end

        Docs["docs/"]:::code
        Files["files/"]:::code

        subgraph "Config Templates & Schema"
            direction TB
            OrgTemplates["github/$ORGANIZATION_NAME.yml"]:::code
            JSONSchema["github/.schema.json"]:::code
        end

        subgraph "Scripts Source"
            direction TB
            subgraph "Entry & Env"
                MainTS["scripts/src/main.ts"]:::code
                EnvTS["scripts/src/env.ts"]:::code
                UtilsTS["scripts/src/utils.ts"]:::code
            end
            SyncTS["scripts/src/sync.ts"]:::code
            GitHubTS["scripts/src/github.ts"]:::code

            subgraph "YAML Parsing & Validation"
                SchemaTS["scripts/src/yaml/schema.ts"]:::code
                ConfigTS["scripts/src/yaml/config.ts"]:::code
            end

            subgraph "Resource Models & CRUD"
                direction TB
                memberTS["member.ts"]:::code
                repoTS["repository.ts"]:::code
                branchProtTS["repository-branch-protection-rule.ts"]:::code
                collabTS["repository-collaborator.ts"]:::code
                fileTS["repository-file.ts"]:::code
                labelTS["repository-label.ts"]:::code
                teamTS["repository-team.ts"]:::code
                teamMemberTS["team-member.ts"]:::code
                baseResourceTS["resource.ts"]:::code
            end

            subgraph "Action Modules"
                direction TB
                findShaTS["find-sha-for-plan.ts"]:::code
                fixYamlTS["fix-yaml-config.ts"]:::code
                formatYamlTS["format-yaml-config.ts"]:::code
                removeMembersTS["remove-inactive-members.ts"]:::code
                syncLabelsTS["sync-labels.ts"]:::code
                updatePRsTS["update-pull-requests.ts"]:::code
                SharedActions["shared/"]:::code
            end

            subgraph "Terraform Integration in CLI"
                direction TB
                LocalTS["scripts/src/terraform/locals.ts"]:::code
                SchemaTFTS["scripts/src/terraform/schema.ts"]:::code
                StateTFTS["scripts/src/terraform/state.ts"]:::code
            end
        end

        subgraph "Terraform Modules & Bootstrap"
            direction TB
            TFModules["terraform/"]:::infra
        end

        subgraph "Test Suite"
            direction TB
            TestsRoot["scripts/__tests__/"]:::code
        end
    end

    %% CI/CD Layer
    Dev -->|"opens PR"| RepoRoot
    RepoRoot -->|"triggers"| Workflows
    Workflows -->|"runs on"| LocalActions
    Workflows -->|"step: validate YAML"| SchemaTS
    SchemaTS -->|"uses"| ConfigTS
    Workflows -->|"step: terraform bootstrap"| TFModules
    TFModules -->|"state read/write"| StateTFTS
    Workflows -->|"step: sync"| MainTS
    MainTS -->|"invokes"| SyncTS
    SyncTS -->|"calls"| GitHubTS
    SyncTS -->|"uses"| LocalTS
    SyncTS -->|"uses"| SchemaTFTS
    SyncTS -->|"uses"| StateTFTS
    GitHubTS -->|"calls API"| TargetOrgs

    %% Test coverage
    TestsRoot ---|tests scripts| MainTS

    %% Click events
    click RepoRoot "https://github.com/ipdxco/github-as-code/tree/master//"
    click Workflows "https://github.com/ipdxco/github-as-code/blob/master/.github/workflows/*.yml"
    click LocalActions "https://github.com/ipdxco/github-as-code/tree/master/.github/actions/"
    click Docs "https://github.com/ipdxco/github-as-code/tree/master/docs/"
    click Files "https://github.com/ipdxco/github-as-code/tree/master/files/"
    click OrgTemplates "https://github.com/ipdxco/github-as-code/blob/master/github/$ORGANIZATION_NAME.yml"
    click JSONSchema "https://github.com/ipdxco/github-as-code/blob/master/github/.schema.json"
    click MainTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/main.ts"
    click EnvTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/env.ts"
    click UtilsTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/utils.ts"
    click SyncTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/sync.ts"
    click GitHubTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/github.ts"
    click SchemaTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/yaml/schema.ts"
    click ConfigTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/yaml/config.ts"
    click memberTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/member.ts"
    click repoTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository.ts"
    click branchProtTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository-branch-protection-rule.ts"
    click collabTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository-collaborator.ts"
    click fileTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository-file.ts"
    click labelTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository-label.ts"
    click teamTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/repository-team.ts"
    click teamMemberTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/team-member.ts"
    click baseResourceTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/resources/resource.ts"
    click findShaTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/find-sha-for-plan.ts"
    click fixYamlTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/fix-yaml-config.ts"
    click formatYamlTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/format-yaml-config.ts"
    click removeMembersTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/remove-inactive-members.ts"
    click syncLabelsTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/sync-labels.ts"
    click updatePRsTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/actions/update-pull-requests.ts"
    click SharedActions "https://github.com/ipdxco/github-as-code/tree/master/scripts/src/actions/shared/"
    click LocalTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/terraform/locals.ts"
    click SchemaTFTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/terraform/schema.ts"
    click StateTFTS "https://github.com/ipdxco/github-as-code/blob/master/scripts/src/terraform/state.ts"
    click TFModules "https://github.com/ipdxco/github-as-code/tree/master/terraform/"
    click TestsRoot "https://github.com/ipdxco/github-as-code/tree/master/scripts/__tests__/"

    %% Styles
    classDef code fill:#cce5ff,stroke:#66a3ff,color:#003366;
    classDef ci fill:#d4f7d4,stroke:#29a329,color:#006600;
    classDef infra fill:#e6e6e6,stroke:#999999,color:#333333;
    classDef external fill:#ffe6cc,stroke:#ff9933,color:#663300;
    classDef actor fill:#f2f2f2,stroke:#666666,color:#333333;
```
