# koenighotze/koenighotze-gcp-base-setup architecture

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

- Interactive diagram: https://gitdiagram.com/koenighotze/koenighotze-gcp-base-setup
- Repository: https://github.com/koenighotze/koenighotze-gcp-base-setup

## Overview

##### Project Type and Purpose
- **Project Type:** Infrastructure as Code (IaC) setup using Terraform for Google Cloud Platform (GCP).
- **Purpose:** To establish a foundational infrastructure on GCP, managing seed projects, child projects, service accounts, billing, and Terraform state management. The setup leverages scripts and GitHub Actions for automation.

##### File Structure

- **Top-Level Directories and Files:**
- `.github/`: Contains GitHub workflows for automation (`apply.yml`, `bootstrap.yml`, `destroy.yml`, etc.).
- `bootstrap/`, `bodleian/`, `platform/`, `seed/`, `terraform-examples/`: Terraform configurations for different aspects of the infrastructure.
- `scripts/`: Shell scripts to automate project setup and management.
- Configuration and lock files: `.checkov.yaml`, `.talismanrc`, `.terraform.lock.hcl`, `main.tf`, `providers.tf`, etc.

- **Patterns and Architectural Choices:**
- **Modular Terraform Structure:** Separate directories (`bootstrap`, `platform`, `seed`, `terraform-examples`) indicate a modular approach, facilitating scalability and maintenance.
- **Automation with GitHub Actions:** Workflow files in `.github/workflows` automate tasks like planning, applying, and destroying infrastructure.
- **Service Accounts and IAM Management:** Multiple `.tf` files manage service accounts and IAM roles, emphasizing security and access control.
- **Scripts for Repetitive Tasks:** The `scripts/` directory contains scripts for creating and deleting projects, managing service accounts, and initializing Terraform, indicating a focus on automation and reducing manual intervention.

##### README for Additional Insights

- **Setup Steps:**
1. **Seed Project and Service Account:** Initializes the foundational GCP project, APIs, billing, and Terraform state bucket.
2. **Child Projects:** Creates downstream projects with billing enabled.
3. **Bootstrap Infrastructure:** Managed via GitHub Actions.
4. **Detailed Projects:** Also handled through GitHub Actions workflows.

- **Automation Overview:**
- CLI scripts create seed projects and service accounts.
- GitHub Actions handle Terraform operations, interacting with billing, service accounts, and project infrastructures.

##### a. Main Components
- **Seed Project:**
- Hosts the Terraform state bucket and seed service account (SeedSA).
- **Service Accounts (SA):**
- SeedSA manages the creation of ProjectSAs, Projects, and ProjectStateBuckets.
- ProjectSAs handle edits to Projects and their state buckets.
- **GitHub Actions:**
- Automated workflows (`bootstrap.yml`, `plan.yml`, `apply.yml`, etc.) execute Terraform commands.
- **Terraform Modules:**
- **Bootstrap:** Initial infrastructure setup.
- **Platform:** Core infrastructure components.
- **Seed:** Seed project configurations.
- **Terraform Examples:** Example modules for various resources.
- **Scripts:**
- Automate project and service account creation, Terraform initialization, and other repetitive tasks.
- **Billing Account:** Centralized billing management for all projects.

##### b. Relationships and Interactions
- **Seed Project ↔ SeedSA:**
- Seed Project hosts the Seed State Bucket and SeedSA.
- **SeedSA ↔ ProjectSAs & Projects:**
- SeedSA creates and manages ProjectSAs, which in turn manage individual Projects and their state buckets.
- **GitHub Actions ↔ Terraform Modules:**
- Actions workflows execute Terraform scripts within the respective modules to manage infrastructure.
- **Scripts ↔ Seed Project & Services:**
- Scripts automate interactions with the Seed Project and Service Accounts to provision and manage resources.

##### c. Architectural Patterns and Design Principles
- **Modularity:** Separate directories for different infrastructure components promote reusability and maintainability.
- **Automation:** Extensive use of scripts and GitHub Actions minimizes manual intervention and ensures consistent deployments.
- **Security:** Dedicated service accounts with specific roles ensure principle of least privilege.
- **Scalability:** Modular Terraform design facilitates the addition of new projects and resources with ease.

##### d. Relevant Technologies, Frameworks, or Libraries
- **Terraform:** Core tool for infrastructure provisioning.
- **Google Cloud Platform (GCP):** Cloud provider for hosting the infrastructure.
- **GitHub Actions:** CI/CD tool for automating Terraform workflows.
- **Shell Scripts:** Automate setup and management tasks.
- **Checkov, Talisman, Trivy:** Tools for infrastructure as code security and compliance.

##### Elements

- **Clear Labels:**
- Name each component (e.g., Seed Project, SeedSA, ProjectSAs, GitHub Actions, Terraform Modules).
- Data flow and dependencies (e.g., SeedSA creates ProjectSAs, GitHub Actions triggers Terraform Apply).
- Differentiate between types of components:

##### Final Recommendations

- **Iterate and Refine:** Start with high-level components and progressively add details to ensure clarity and comprehensiveness.
- **Validate with Team:** Collaborate with team members to ensure all components and interactions are accurately represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs and modules
    subgraph "Seed Infrastructure"
        SeedProject["Seed Project"]:::infrastructure
        SeedStateBucket["Seed State Bucket"]:::infrastructure
        SeedSA["Seed Service Account"]:::serviceaccounts
    end
    
    subgraph "Service Accounts"
        Bodleian["Bodleian"]:::serviceaccounts
        PlatformSA["PlatformSA"]:::serviceaccounts
        ExamplesSA["ExamplesSA"]:::serviceaccounts
    end
    
    subgraph "Terraform Modules"
        Bootstrap["Bootstrap Module"]:::infrastructure
        Platform["Platform Module"]:::infrastructure
        SeedModule["Seed Module"]:::infrastructure
        Examples["Terraform Examples Module"]:::infrastructure
    end
    
    subgraph "Automation"
        GitHubActions["GitHub Actions"]:::automation
        ApplyYML["apply.yml"]:::automation
        BootstrapYML["bootstrap.yml"]:::automation
        DestroyYML["destroy.yml"]:::automation
        PlanYML["plan.yml"]:::automation
        ReceivePRYML["receive-pull-request.yml"]:::automation
    end
    
    subgraph "Scripts"
        Scripts["Scripts"]:::scripts
    end
    
    subgraph "Billing"
        BillingAccount["Billing Account"]:::billing
        BillingAlert["billing-alert.tf"]:::billing
    end

    %% Connections
    SeedProject -->|Hosts| SeedStateBucket
    SeedProject -->|Hosts| SeedSA

    SeedSA -.->|Creates| Bodleian
    SeedSA -.->|Creates| PlatformSA
    SeedSA -.->|Creates| ExamplesSA

    Bodleian -.->|Manages| Bootstrap
    PlatformSA -.->|Manages| Platform
    ExamplesSA -.->|Manages| Examples

    GitHubActions -->|Executes| Bootstrap
    GitHubActions -->|Executes| Platform
    GitHubActions -->|Executes| SeedModule
    GitHubActions -->|Executes| Examples

    Scripts -->|Automate| SeedProject
    Scripts -->|Automate| SeedSA

    SeedSA -->|Links| BillingAccount
    Bodleian -->|Links| BillingAccount
    PlatformSA -->|Links| BillingAccount
    ExamplesSA -->|Links| BillingAccount
    BillingAccount -->|Manages| BillingAlert

    %% Click Events
    click SeedProject "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/seed/"
    click Bodleian "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/bodleian/"
    click PlatformSA "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/platform/sa.tf"
    click ExamplesSA "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/terraform-examples/sa.tf"
    click ApplyYML "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/.github/workflows/apply.yml"
    click BootstrapYML "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/.github/workflows/bootstrap.yml"
    click DestroyYML "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/.github/workflows/destroy.yml"
    click PlanYML "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/.github/workflows/plan.yml"
    click ReceivePRYML "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/.github/workflows/receive-pull-request.yml"
    click Bootstrap "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/bootstrap/"
    click Platform "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/platform/"
    click SeedModule "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/seed/"
    click Examples "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/terraform-examples/"
    click Scripts "https://github.com/koenighotze/koenighotze-gcp-base-setup/tree/main/scripts/"
    click BillingAlert "https://github.com/koenighotze/koenighotze-gcp-base-setup/blob/main/seed/billing-alert.tf"

    %% Styles
    classDef infrastructure fill:#add8e6,stroke:#333,stroke-width:1px
    classDef automation fill:#90ee90,stroke:#333,stroke-width:1px
    classDef serviceaccounts fill:#ffa500,stroke:#333,stroke-width:1px
    classDef scripts fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef billing fill:#f08080,stroke:#333,stroke-width:1px
```
