# terraform-google-modules/terraform-google-project-factory architecture

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

- Interactive diagram: https://gitdiagram.com/terraform-google-modules/terraform-google-project-factory
- Repository: https://github.com/terraform-google-modules/terraform-google-project-factory

## Overview

##### Project Type and Purpose
- This is an open-source Terraform module (“Google Cloud Project Factory”) that codifies best practices for provisioning Google Cloud Platform (GCP) projects.
- It exposes reusable submodules (e.g., app_engine, budget, shared_vpc_access) and helper scripts to automate project creation, API enablement, IAM roles, billing, Shared VPC attachments, service accounts, budgets, and optional G Suite integration.

##### File Structure Analysis
- Top-level directories:
- modules/ – each subdirectory is a self-contained Terraform submodule implementing one aspect of project configuration
- examples/ – full sample configurations consuming the module in different scenarios (App Engine, budgets, Shared VPC, etc.)
- helpers/ – shell, Python, and Terraform-wrapping scripts for precondition checks, service account setup, version migration, release automation
- test/ – fixture Terraform configs, Go and Ruby/Inspec integration tests, precondition test scripts
- docs/ – user documentation, FAQs, upgrade guides, troubleshooting
- build/, .github/workflows – CI/CD pipelines for linting, testing, and release automation
- main.tf, variables.tf, outputs.tf, versions.tf – the entry point Terraform configuration that ties submodules together
- Configuration files:
- .pre-commit-config.yaml, Makefile – local linting and build commands
- build/*.cloudbuild.yaml – Cloud Build definitions
- .github/workflows/*.yaml – GitHub Actions for CI and stale-branch pruning

##### README Insights
- Articulates the module’s purpose: create a new GCP project, configure network/IAM/APIs, optionally create buckets and budgets, integrate with Shared VPC and G Suite.
- Lists required APIs, Terraform versions, provider plugins, usage examples, inputs/outputs, dependencies, and helper-script usage.

a. Main Components
1. Core Terraform Module (main.tf + submodules)
2. Submodules (modules/app_engine, modules/budget, modules/shared_vpc_access, etc.)
3. Examples (examples/*) demonstrating module consumption
4. Helpers (scripts under helpers/)
5. CI/CD Pipelines (.github/workflows + build/)
6. Test Harness (test/fixtures, test/integration)
7. Documentation (docs/)
8. External Systems: Terraform CLI, Google Cloud APIs (Resource Manager, Billing, IAM, etc.), GitHub

b. Relationships & Interactions
- The **Terraform CLI** invokes **main.tf**, which calls into multiple **submodules**.
- **Submodules** communicate with **Google Cloud APIs** via the **google** and **google-beta** providers.
- **Examples/** directories import the root module as a remote module and drive real-world configurations.
- **Helpers** (e.g., preconditions.py, setup-sa.sh) validate environment and bootstrap service accounts.
- The **CI/CD pipelines** trigger:
- Linting (terraform fmt, terraform validate, shellcheck, pre-commit)
- Unit tests (terraform-docs generation)
- Integration tests (Kitchen + InSpec, Go tests)
- Release automation (release-please, renovate)
- **Test fixtures** feed Terraform configs into the test harness; **integration tests** assert real or emulated behavior against GCP.

c. Architectural Patterns & Principles
- Modular design: each Terraform concern is isolated in its own submodule
- Infrastructure as Code: declarative definitions, versioned modules, automated testing
- Separation of concerns: provisioning logic (modules), examples, docs, scripts, and CI kept in dedicated directories
- CI pipeline as code: Cloud Build and GitHub Actions definitions versioned alongside code
- Extensibility: clients can override variables, extend via examples or custom modules

d. Key Technologies & Frameworks
- Terraform (core language)
- Terraform providers: google, google-beta, terraform-provider-gsuite
- CI/CD: GitHub Actions, Google Cloud Build
- Testing: InSpec (Ruby), Kitchen-Terraform, Go (test files), pre-commit hooks
- Scripting: Bash, Python (preconditions, migrations), Makefile
- Documentation: Markdown under docs/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GitHub["GitHub"]:::external
    GCPAPIs["Google Cloud APIs"]:::external
    TerraformCLI["Terraform CLI"]:::external

    %% Core Module
    CoreModule["Core Terraform Module"]:::terraform

    %% Submodules
    subgraph "Terraform Submodules"
        direction TB
        AE["app_engine"]:::terraform
        BD["budget"]:::terraform
        SVA["shared_vpc_access"]:::terraform
        CPF["core_project_factory"]:::terraform
        EC["essential_contacts"]:::terraform
        FP["fabric-project"]:::terraform
        GE["gsuite_enabled"]:::terraform
        GG["gsuite_group"]:::terraform
        PS["project_services"]:::terraform
        QM["quota_manager"]:::terraform
        SS["svpc_service_project"]:::terraform
    end

    %% Examples
    subgraph "Examples" 
        direction TB
        EX1["examples/app_engine"]:::example
        EX2["examples/budget_project"]:::example
        EX3["examples/essential_contacts"]:::example
        EX4["examples/fabric_project"]:::example
        EX5["examples/gke_shared_vpc"]:::example
        EX6["examples/group_project"]:::example
        EX7["examples/project-hierarchy"]:::example
        EX8["examples/project_services"]:::example
        EX9["examples/quota_project"]:::example
        EX10["examples/shared_vpc"]:::example
        EX11["examples/simple_project"]:::example
        EX12["examples/tags_project"]:::example
    end

    %% Helpers
    subgraph "Helper Scripts" 
        direction TB
        HS1["helpers/init_centos.sh"]:::script
        HS2["helpers/init_debian.sh"]:::script
        HS3["helpers/migrate.py"]:::script
        HS4["helpers/migrate4.py"]:::script
        HS5["helpers/preconditions/preconditions.py"]:::script
        HS6["helpers/setup-sa.sh"]:::script
        HS7["helpers/release-new-version.sh"]:::script
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        GH_Lint[".github/workflows/lint.yaml"]:::ci
        GH_Stale[".github/workflows/stale.yaml"]:::ci
        CB_Lint["build/lint.cloudbuild.yaml"]:::ci
        CB_Int["build/int.cloudbuild.yaml"]:::ci
        RP[".github/release-please.yml"]:::ci
        Renovate[".github/renovate.json"]:::ci
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        TF_Fixtures["test/fixtures/*"]:::test
        InSpec["test/integration/**/*.inspec.yml"]:::test
        GoTests["test/integration/*.go"]:::test
        TestMigrate["test/helpers/test_migrate.py"]:::test
        TestPreconds["test/scripts/preconditions/test_preconditions.py"]:::test
        SetupTF["test/setup/*.tf"]:::test
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocsDir["docs/"]:::docs
        Readme["README.md"]:::docs
        Contrib["CONTRIBUTING.md"]:::docs
        Changelog["CHANGELOG.md"]:::docs
        Codeowners["CODEOWNERS"]:::docs
    end

    %% Relationships
    TerraformCLI -->|invokes| CoreModule
    CoreModule -->|uses| AE
    CoreModule -->|uses| BD
    CoreModule -->|uses| SVA
    CoreModule -->|uses| CPF
    CoreModule -->|uses| EC
    CoreModule -->|uses| FP
    CoreModule -->|uses| GE
    CoreModule -->|uses| GG
    CoreModule -->|uses| PS
    CoreModule -->|uses| QM
    CoreModule -->|uses| SS

    AE -->|calls APIs| GCPAPIs
    BD -->|calls APIs| GCPAPIs
    SVA -->|calls APIs| GCPAPIs

    TerraformCLI -->|applies| EX1
    TerraformCLI -->|applies| EX2
    TerraformCLI -->|applies| EX3
    TerraformCLI -->|applies| EX4
    TerraformCLI -->|applies| EX5
    TerraformCLI -->|applies| EX6
    TerraformCLI -->|applies| EX7
    TerraformCLI -->|applies| EX8
    TerraformCLI -->|applies| EX9
    TerraformCLI -->|applies| EX10
    TerraformCLI -->|applies| EX11
    TerraformCLI -->|applies| EX12

    HS5 -->|validates| TerraformCLI
    HS6 -->|bootstraps| TerraformCLI

    GitHub -->|triggers| GH_Lint
    GitHub -->|triggers| GH_Stale
    GitHub -->|triggers| RP
    GitHub -->|triggers| Renovate

    CB_Lint -->|runs lint| TerraformCLI
    CB_Int -->|runs tests| TerraformCLI

    GH_Lint -->|reports| TerraformCLI
    TF_Fixtures -->|feed| CB_Int
    InSpec -->|runs| CB_Int
    GoTests -->|runs| CB_Int

    %% Click Events
    click CoreModule "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/main.tf"
    click CoreModule "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/variables.tf"
    click CoreModule "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/outputs.tf"
    click CoreModule "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/versions.tf"
    click AE "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/app_engine/main.tf"
    click BD "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/budget/main.tf"
    click SVA "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/shared_vpc_access/main.tf"
    click CPF "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/core_project_factory/main.tf"
    click EC "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/essential_contacts/main.tf"
    click FP "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/fabric-project/main.tf"
    click GE "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/gsuite_enabled/main.tf"
    click GG "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/gsuite_group/main.tf"
    click PS "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/project_services/main.tf"
    click QM "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/quota_manager/main.tf"
    click SS "https://github.com/terraform-google-modules/terraform-google-project-factory/blob/main/modules/svpc_service_project/main.tf"

    %% Styles
    classDef terraform fill:#E2E8F0,stroke:#2B6CB0,stroke-width:2px;
    classDef external fill:#F7FAFC,stroke:#4A5568,stroke-width:2px,stroke-dasharray: 5 5;
    classDef example fill:#EDF2F7,stroke:#2C5282,stroke-width:2px;
    classDef script fill:#FFF5F7,stroke:#C53030,stroke-width:2px;
    classDef ci fill:#F0FFF4,stroke:#38A169,stroke-width:2px;
    classDef test fill:#FFFFF0,stroke:#D69E2E,stroke-width:2px;
    classDef docs fill:#F0F4F8,stroke:#2D3748,stroke-width:2px;
```
