# googlecloudplatform/magic-modules architecture

> Architecture diagram of the GitHub repository googlecloudplatform/magic-modules, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/magic-modules
- Repository: https://github.com/googlecloudplatform/magic-modules

## Overview

Magic Modules turns product and resource definitions into Terraform provider code and documentation, with an experimental OpenAPI-to-definition path. Contributors also use repository tools for schema-diff analysis, template conversion and checks, changelog validation, test reading, issue labeling, and TeamCity service configuration. The sampled generator source establishes its loading, validation, and provider-generation flow; several tool implementations were not sampled, so their internal wiring is intentionally not inferred.

Main entry points: [`mmv1/main.go`](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/main.go) (MMv1 runner), [`mmv1/loader/loader.go`](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/loader/loader.go) (Definition loader), [`mmv1/provider/terraform.go`](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/provider/terraform.go) (Provider generator), [`mmv1/openapi_generate/parser.go`](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/openapi_generate/parser.go) (OpenAPI converter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Provider generation"]
  node_mmv1_runner["MMv1 runner<br/>[main.go]"]
  node_loader["Definition loader<br/>[loader.go]"]
  node_provider_generator["Provider generator<br/>[terraform.go]"]
  node_provider_variants["Provider variants<br/>[provider.go]"]
end

subgraph group_schema["Schema inputs"]
  node_api_model["Product/resource model<br/>[product.go]"]
  node_openapi_parser["OpenAPI converter<br/>[parser.go]"]
end

subgraph group_analysis["Schema analysis"]
  node_diff_processor["Schema diff CLI<br/>[root.go]"]
  node_diff_engine["Breaking-change analysis"]
  node_diff_detectors["Missing-item detectors<br/>[detector.go]"]
end

subgraph group_contributor["Contributor tools"]
  node_template_converter["Resource template converter<br/>[root.go]"]
  node_template_checks["Template checks<br/>[root.go]"]
  node_test_reader["Test reader<br/>[reader.go]"]
  node_issue_labeler["Issue labeler<br/>[labels.go]"]
  node_changelog_check["Changelog validator<br/>[main.go]"]
end

subgraph group_teamcity["TeamCity configuration"]
  node_teamcity_generator["Service map generator<br/>[main.go]"]
  node_teamcity_check["Service map checker<br/>[main.go]"]
end

node_contributor_actor(("Contributor"))
node_generated_output["Provider code and docs"]
node_openapi_input["OpenAPI definitions"]
node_definition_files["Product definitions"]
node_github(("GitHub"))
node_provider_services["Provider service packages"]
node_teamcity_services["TeamCity service map"]

node_contributor_actor -->|"runs generation"| node_mmv1_runner
node_mmv1_runner -->|"loads definitions"| node_loader
node_loader -->|"reads"| node_definition_files
node_loader -->|"builds and validates"| node_api_model
node_mmv1_runner -->|"requests generation"| node_provider_generator
node_provider_generator -->|"selects provider"| node_provider_variants
node_provider_generator -->|"writes code and docs"| node_generated_output
node_contributor_actor -->|"runs conversion"| node_openapi_parser
node_openapi_parser -->|"reads"| node_openapi_input
node_openapi_parser -->|"writes YAML"| node_definition_files
node_contributor_actor -->|"runs analysis"| node_diff_processor
node_contributor_actor -->|"runs conversion"| node_template_converter
node_contributor_actor -->|"runs checks"| node_template_checks
node_contributor_actor -->|"reads tests"| node_test_reader
node_contributor_actor -->|"runs labeling"| node_issue_labeler
node_issue_labeler -.->|"interacts with"| node_github
node_contributor_actor -->|"checks PR"| node_changelog_check
node_changelog_check -.->|"retrieves PR"| node_github
node_contributor_actor -->|"runs generation"| node_teamcity_generator
node_teamcity_generator -->|"reads packages"| node_provider_services
node_teamcity_generator -->|"writes map"| node_teamcity_services
node_contributor_actor -->|"runs comparison"| node_teamcity_check
node_teamcity_check -->|"reads list"| node_provider_services
node_teamcity_check -->|"reads map"| node_teamcity_services
node_diff_processor -->|"runs analysis"| node_diff_engine
node_diff_processor -->|"runs detection"| node_diff_detectors

click node_mmv1_runner "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/main.go"
click node_loader "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/loader/loader.go"
click node_api_model "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/api/product.go"
click node_provider_generator "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/provider/terraform.go"
click node_provider_variants "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/provider/provider.go"
click node_openapi_parser "https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/openapi_generate/parser.go"
click node_diff_processor "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/cmd/root.go"
click node_diff_engine "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/breaking_changes/breaking_changes.go"
click node_diff_detectors "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/detector/detector.go"
click node_template_converter "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/resource-template-converter/cmd/root.go"
click node_template_checks "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/template-check/cmd/root.go"
click node_test_reader "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/test-reader/reader/reader.go"
click node_issue_labeler "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/issue-labeler/labeler/labels.go"
click node_changelog_check "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/go-changelog/cmd/changelog-pr-body-check/main.go"
click node_teamcity_generator "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/teamcity-generator/main.go"
click node_teamcity_check "https://github.com/googlecloudplatform/magic-modules/blob/main/tools/teamcity-diff-check/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mmv1_runner,node_loader,node_provider_generator,node_provider_variants toneBlue
class node_api_model,node_openapi_parser toneAmber
class node_diff_processor,node_diff_engine,node_diff_detectors,node_openapi_input toneMint
class node_template_converter,node_template_checks,node_test_reader,node_issue_labeler,node_changelog_check toneRose
class node_teamcity_generator,node_teamcity_check,node_contributor_actor,node_generated_output,node_definition_files,node_github,node_provider_services,node_teamcity_services toneIndigo
```

## Components

### Provider generation

- [MMv1 runner](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/main.go): `mmv1/main.go`
- [Definition loader](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/loader/loader.go): `mmv1/loader/loader.go`
- [Provider generator](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/provider/terraform.go): `mmv1/provider/terraform.go`
- [Provider variants](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/provider/provider.go): `mmv1/provider/provider.go`

### Schema inputs

- [Product/resource model](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/api/product.go): `mmv1/api/product.go`
- [OpenAPI converter](https://github.com/googlecloudplatform/magic-modules/blob/main/mmv1/openapi_generate/parser.go): `mmv1/openapi_generate/parser.go`

### Schema analysis

- [Schema diff CLI](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/cmd/root.go): `tools/diff-processor/cmd/root.go`
- [Breaking-change analysis](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/breaking_changes/breaking_changes.go): `tools/diff-processor/breaking_changes/breaking_changes.go`
- [Missing-item detectors](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/diff-processor/detector/detector.go): `tools/diff-processor/detector/detector.go`

### Contributor tools

- [Resource template converter](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/resource-template-converter/cmd/root.go): `tools/resource-template-converter/cmd/root.go`
- [Template checks](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/template-check/cmd/root.go): `tools/template-check/cmd/root.go`
- [Test reader](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/test-reader/reader/reader.go): `tools/test-reader/reader/reader.go`
- [Issue labeler](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/issue-labeler/labeler/labels.go): `tools/issue-labeler/labeler/labels.go`
- [Changelog validator](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/go-changelog/cmd/changelog-pr-body-check/main.go): `tools/go-changelog/cmd/changelog-pr-body-check/main.go`

### TeamCity configuration

- [Service map generator](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/teamcity-generator/main.go): `tools/teamcity-generator/main.go`
- [Service map checker](https://github.com/googlecloudplatform/magic-modules/blob/main/tools/teamcity-diff-check/main.go): `tools/teamcity-diff-check/main.go`

### Other components

- **Contributor**
- **Provider code and docs**
- **OpenAPI definitions**
- **Product definitions**
- **GitHub**
- **Provider service packages**
- **TeamCity service map**

## Connections

- Contributor → MMv1 runner: runs generation
- MMv1 runner → Definition loader: loads definitions
- Definition loader → Product definitions: reads
- Definition loader → Product/resource model: builds and validates
- MMv1 runner → Provider generator: requests generation
- Provider generator → Provider variants: selects provider
- Provider generator → Provider code and docs: writes code and docs
- Contributor → OpenAPI converter: runs conversion
- OpenAPI converter → OpenAPI definitions: reads
- OpenAPI converter → Product definitions: writes YAML
- Contributor → Schema diff CLI: runs analysis
- Contributor → Resource template converter: runs conversion
- Contributor → Template checks: runs checks
- Contributor → Test reader: reads tests
- Contributor → Issue labeler: runs labeling
- Issue labeler → GitHub: interacts with
- Contributor → Changelog validator: checks PR
- Changelog validator → GitHub: retrieves PR
- Contributor → Service map generator: runs generation
- Service map generator → Provider service packages: reads packages
- Service map generator → TeamCity service map: writes map
- Contributor → Service map checker: runs comparison
- Service map checker → Provider service packages: reads list
- Service map checker → TeamCity service map: reads map
- Schema diff CLI → Breaking-change analysis: runs analysis
- Schema diff CLI → Missing-item detectors: runs detection