# templatemechanics/pulumi-gcp architecture

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

- Interactive diagram: https://gitdiagram.com/templatemechanics/pulumi-gcp
- Repository: https://github.com/templatemechanics/pulumi-gcp

## Overview

##### Project Type and Purpose
- This is an open-source, YAML-driven Infrastructure-as-Code (IaC) tool built on Pulumi for Google Cloud Platform (GCP).
- It reads a user’s `config.yaml` (aka `Pulumi.yaml`) and dynamically maps definitions into Pulumi GCP resource calls, handling naming conventions, secret resolution, and cross-resource references.

##### File Structure Analysis
- __main__.py
– Entry point. Parses the YAML file, invokes core orchestration.
- config.py
– Defines dataclasses, loads/parses YAML, and maps entries to Pulumi resource constructors.
- gcpclassic.py
– Encapsulates GCP naming conventions, secret resolution, region-abbr logic, and helper functions for referencing existing resources.
- Pulumi.yaml (aka config.yaml)
– User-supplied YAML describing team, service, environment, labels, and a list of `gcp_resources`.
- config.py / requirements.txt / Pulumi.yaml / Pulumi state
– Configuration, dependencies, and project metadata for Pulumi.

##### Key Architectural Insights from README
- Dynamic resource mapping via introspection of `pulumi_gcp`.
- Use of `ref:<resource>.<attribute>` syntax for linking resources.
- Custom name-override and secret resolution via Pulumi config.
- Extensible design aimed at adding new resource types or multi-environment support.

##### Components
a. Front-End:
- User-defined YAML config (Pulumi.yaml)
b. Orchestration Layer:
- __main__.py (CLI entrypoint)
- config.py (Parser & mapper)
- gcpclassic.py (Naming & helper logic)
c. Pulumi Engine:
- Pulumi Python SDK (pulumi, pulumi_gcp modules)
- State management (local or remote backend)
d. External System / Cloud Provider:
- GCP APIs (Compute, SQL, Networking, etc.)
- Secret store via Pulumi config
e. Optional Metadata:
- Dependency resolution graph (auto-generated by Pulumi)

##### Relationships and Data Flow
1. User runs `pulumi up` → triggers __main__.py
2. __main__.py loads Pulumi config (secrets, region)
3. config.py parses YAML into internal dataclasses
4. gcpclassic.py applies naming conventions & resolves `ref:` and `secret:` tokens
5. For each resource entry, invoke Pulumi GCP SDK to create or fetch resources
6. Pulumi Engine communicates with GCP APIs, records state in backend
7. Pulumi outputs resource attributes back to the user/CLI

##### Architectural Patterns and Principles
- Modular separation: parsing (config.py), business logic (gcpclassic.py), orchestration (__main__.py)
- Dependency injection: dataclasses decouple YAML schema from Pulumi calls
- Dynamic introspection: uses Pulumi’s provider metadata rather than hard-coding resources
- Convention-over-configuration: naming conventions reduce boilerplate
- Extensibility points: new YAML templates, additional helper functions in gcpclassic.py

##### Coverage of Essential Elements
- YAML config source, code modules, Pulumi engine, and external GCP services.
- Secret resolution path (YAML secret token → Pulumi config → runtime injection).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Front-End
    PulumiYAML["Pulumi.yaml<br/>(User YAML Config)"]:::frontend

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Main["__main__.py<br/>(Orchestration)"]:::internal
        Config["config.py<br/>(YAML Parser & Mapper)"]:::internal
        GCPClassic["gcpclassic.py<br/>(Naming & Helper Logic)"]:::internal
    end

    %% Pulumi Engine
    subgraph "Pulumi Engine"
        direction TB
        SDK["Pulumi Python SDK<br/>(pulumi, pulumi_gcp)"]:::engine
        Requirements["requirements.txt<br/>(Dependency Declarations)"]:::engine
        State["State Backend<br/>(Local/Remote)"]:::engine
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GCPAPIs["GCP APIs<br/>(Compute, SQL, Networking)"]:::external
        SecretStore["Pulumi Config<br/>(Secret Store)"]:::external
    end

    %% Metadata
    Metadata["Dependency Graph<br/>(Auto-generated)"]:::external

    %% Flows
    PulumiYAML -->|"pulumi up triggers"| Main
    Main -->|"load config & secrets"| SecretStore
    Main --> Config
    Config -->|"parse YAML to dataclasses"| GCPClassic
    GCPClassic -->|"resolve names, ref: & secret:"| SDK
    SDK -->|"create/fetch resources"| GCPAPIs
    SDK -->|"record state"| State
    SecretStore -->|"inject secrets at runtime"| GCPClassic
    Metadata --- SDK

    %% Click Events
    click PulumiYAML "https://github.com/templatemechanics/pulumi-gcp/blob/main/Pulumi.yaml"
    click Main "https://github.com/templatemechanics/pulumi-gcp/blob/main/__main__.py"
    click Config "https://github.com/templatemechanics/pulumi-gcp/blob/main/config.py"
    click GCPClassic "https://github.com/templatemechanics/pulumi-gcp/blob/main/gcpclassic.py"
    click Requirements "https://github.com/templatemechanics/pulumi-gcp/blob/main/requirements.txt"
    click Metadata "https://github.com/templatemechanics/pulumi-gcp/blob/main/README.md"
    click Metadata "https://github.com/templatemechanics/pulumi-gcp/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2E86C1,color:#154360
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B4F72
    classDef engine fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef external fill:#FDEBD0,stroke:#D35400,color:#6E2C00
```
