# ciscodevnet/terraform-provider-catalystcenter architecture

> Architecture diagram of the GitHub repository ciscodevnet/terraform-provider-catalystcenter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ciscodevnet/terraform-provider-catalystcenter
- Repository: https://github.com/ciscodevnet/terraform-provider-catalystcenter

## Overview

##### Project type and purpose
- This is a Terraform Provider plugin for Cisco Catalyst Center, written in Go.
- It consists of a build‐time code‐generation pipeline, the provider runtime (plugin binary), documentation generation, example configurations, tests, and CI/CD workflows.
- At runtime, Terraform Core loads the provider plugin, which translates Terraform resource/data-source blocks into REST calls to the Catalyst Center API.

##### File structure
- Top level
– gen/definitions/*.yaml: canonical resource & data-source definitions
– gen/generator.go + gen/templates/: code-gen engine and Go/TF template files
– internal/provider/: generated & handwritten Go code implementing the Terraform Plugin SDK interfaces (resources, data-sources, models)
– main.go: plugin entrypoint (registers provider with Terraform SDK)
– docs/ + templates/guides: Markdown docs sources for Terraform Registry
– examples/: sample Terraform configurations (basic, data-sources, resources)
– .github/, GNUmakefile, .goreleaser.yml: CI/CD definitions (GitHub Actions, Make targets, GoReleaser)

- Architectural patterns
– Build-time code generation (DRY definitions → Go code + docs)
– Plugin pattern (Terraform SDK)
– Clear separation: generator, provider runtime, docs, examples, CI

##### README for insights
- Describes the provider purpose (REST API integration)
- Lists build/release/test commands (`go install`, `go generate`, `make testacc`, GitHub Actions)
- Points at Terraform Registry for generated docs

a. Components
1. Definitions (gen/definitions/*.yaml)
2. Generator Tool (gen/generator.go + templates)
3. Generated Code (models, schema, provider stubs in internal/provider)
4. Provider Entrypoint (main.go) → Compiled binary (Terraform plugin)
5. Terraform Core (CLI & SDK)
6. Cisco Catalyst Center REST API (external)
7. Documentation Generator (same gen pipeline → docs/)
8. Examples & Tests (examples/, internal/provider/*_test.go)
9. CI/CD Pipeline (GitHub Actions, Make, GoReleaser)

b. Relationships & data flow
- Definitions + Templates → Generator → Generated Code
- Generated Code + Entrypoint → Build → Provider Binary
- Terraform CLI ↔ Provider Binary (RPC via Terraform SDK)
- Provider Binary → REST calls → Catalyst Center API
- Definitions + Templates → Doc Generator → Markdown docs → Terraform Registry
- Examples feed Terraform CLI & acceptance tests
- CI/CD orchestrates Generation → Build → Test → Release → Docs publication

c. Architectural patterns & principles
- Build‐time code generation ensures consistency across code and docs
- Plugin interface for extensibility via Terraform SDK
- Single source of truth: YAML definitions drive both code and documentation
- Modular directories separating concerns (gen, internal, docs, examples, CI)

d. Key technologies
- Go (modules), Terraform Plugin SDK
- YAML & Go templates
- GitHub Actions, Make, GoReleaser
- REST API for Catalyst Center

##### Detail checklist
- Clearly name each component (e.g., “gen/generator.go”, “internal/provider/resource_xyz.go”, “main.go”)
- Output artifacts (e.g., provider binary, Markdown docs)
- Flow from definitions to generated code to runtime behavior
- External dependency (Cisco Catalyst Center REST API)
- CI/CD steps: test (unit + acc), release (GoReleaser), docs publish
- Where examples and tests plug in for validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Phase
    subgraph "Build-Time" 
        direction TB
        Definitions["Canonical Resource & Data-Source Definitions"]:::build
        Schema["Schema Definition"]:::build
        GeneratorTool["Generator Tool"]:::build
        Templates["Templates"]:::build
        GeneratedCode["Generated Code"]:::build
    end

    %% Runtime Phase
    subgraph "Runtime" 
        direction TB
        TerraformCLI["Terraform CLI & SDK"]:::runtime
        ProviderBinary["Provider Binary"]:::runtime
        CatalystAPI["Cisco Catalyst Center REST API"]:::runtime
    end

    %% Documentation Phase
    subgraph "Documentation"
        direction TB
        DocGenerator["Doc Generator"]:::docs
        MarkdownDocs["Markdown Docs"]:::docs
        Registry["Terraform Registry Manifest"]:::docs
    end

    %% Validation Phase
    subgraph "Validation"
        direction TB
        Examples["Example Configurations"]:::validation
        Tests["Unit & Acceptance Tests"]:::validation
    end

    %% Orchestration Phase
    subgraph "Orchestration"
        direction TB
        CICD["CI/CD Pipeline"]:::orchestration
        Makefile["GNUmakefile"]:::orchestration
        GoReleaser["GoReleaser"]:::orchestration
    end

    %% Build-Time Flow
    Definitions -->|"provide definitions"| GeneratorTool
    Schema -->|"provide schema"| GeneratorTool
    Templates -->|"provide templates"| GeneratorTool
    GeneratorTool -->|"generate code"| GeneratedCode
    GeneratorTool -->|"generate docs"| DocGenerator

    %% Runtime Flow
    GeneratedCode -->|"compiled with"| Entrypoint["Plugin Entrypoint (main.go)"]:::runtime
    Entrypoint -->|"build"| ProviderBinary
    TerraformCLI -->|"invoke RPC"| ProviderBinary
    ProviderBinary -->|"call REST API"| CatalystAPI

    %% Documentation Flow
    DocGenerator -->|"output docs"| MarkdownDocs
    MarkdownDocs -->|"publish"| Registry

    %% Validation Flow
    Examples -->|"feed configs"| TerraformCLI
    Tests -->|"run tests"| ProviderBinary

    %% Orchestration Flow
    CICD -.->|"trigger generation"| GeneratorTool
    CICD -.->|"trigger build"| Entrypoint
    CICD -.->|"run tests"| Tests
    CICD -.->|"release binary"| GoReleaser
    CICD -.->|"publish docs"| MarkdownDocs
    CICD --> Makefile
    CICD --> GoReleaser

    %% Click Events
    click Definitions "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/gen/definitions/*.yaml"
    click Schema "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/gen/schema/schema.yaml"
    click GeneratorTool "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/gen/generator.go"
    click Templates "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/gen/templates/"
    click GeneratedCode "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/internal/provider/"
    click Entrypoint "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/main.go"
    click DocGenerator "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/templates/guides/"
    click MarkdownDocs "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/docs/"
    click Registry "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/terraform-registry-manifest.json"
    click Examples "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/examples/"
    click Tests "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/internal/provider/*_test.go"
    click CICD "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/.github/workflows/"
    click Makefile "https://github.com/ciscodevnet/terraform-provider-catalystcenter/tree/main/GNUmakefile"
    click GoReleaser "https://github.com/ciscodevnet/terraform-provider-catalystcenter/blob/main/.goreleaser.yml"

    %% Styles
    classDef build fill:#b3cde0,stroke:#000,color:#000
    classDef runtime fill:#ccebc5,stroke:#000,color:#000
    classDef docs fill:#fddaac,stroke:#000,color:#000
    classDef validation fill:#decbe4,stroke:#000,color:#000
    classDef orchestration fill:#f2f2f2,stroke:#000,color:#000
```
