# twingate/terraform-provider-twingate architecture

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

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

## Overview

##### Main Components

a) Provider Core Layer:
- Main provider initialization component (twingate/provider.go)
- To the internal provider components

b) Resource Management Layer:
- Resource types (connectors, groups, networks, etc.)
- Connection to the core provider
- Both resource and data source implementations

c) Client Layer:
- API client implementation
- GraphQL query handling
- Cache mechanism

d) Model Layer:
- Domain models
- To both resource and client layers

##### Component Relationships

**Terraform Core -> Provider Layer -> Resource Layer -> Client Layer -> Twingate API**
- > Model Layer

##### Specific Implementation Details

- Blue rectangles: Core provider components
- Green rectangles: Resources and data sources
- Yellow rectangles: Client components
- Purple rectangles: Models
- Orange rectangles: External systems (Terraform, Twingate API)

##### Key Elements to Highlight

a) Provider Operations:
- CRUD operations flow
- Authentication handling
- Resource state management

b) Resource Types (group these together):
- Network resources (connectors, remote networks)
- Access control (users, groups, service accounts)
- Security (security policies, DNS filtering)

c) Client Operations:
- GraphQL query handling
- Error management
- Caching mechanism

##### Implementation Notes

Annotations for:
- GraphQL query patterns
- State management
- Validation rules
- Test coverage

##### Technical Details

- Go version requirements
- Terraform version compatibility
- API version support
- Testing frameworks

##### Architectural Patterns

Highlight:
- Resource abstraction pattern
- Data source pattern
- Client-side caching
- Error handling strategy

##### External systems

Keep the abstraction level focused on the architectural components while including enough detail to show the provider's specific implementation patterns and resource management approach.

This will give other engineers a clear understanding of:
- How the provider integrates with Terraform
- How resources are managed
- How the API communication is handled
- How different components interact
- Where to find specific functionality in the codebase

Remember to include version information and technical requirements as noted in the README, and consider adding notes about the testing strategy given the extensive test coverage evident in the file structure.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#FFA500,stroke:#000
    classDef core fill:#4169E1,stroke:#000
    classDef resource fill:#90EE90,stroke:#000
    classDef client fill:#FFD700,stroke:#000
    classDef model fill:#DDA0DD,stroke:#000
    classDef test fill:#A9A9A9,stroke:#000

    TF[Terraform Core]:::external
    API[Twingate API]:::external

    subgraph Provider["Provider Layer"]
        PC[Provider Core]:::core
        PI[Provider Implementation]:::core
    end

    subgraph Resources["Resource Management Layer"]
        direction TB
        RM[Resource Manager]:::resource
        subgraph ResourceTypes["Resource Types"]
            direction TB
            CON[Connectors]:::resource
            GRP[Groups]:::resource
            RN["Remote Networks"]:::resource
            RES[Resources]:::resource
        end
        subgraph DataSources["Data Sources"]
            direction TB
            DCON[Connector Data]:::resource
            DGRP[Group Data]:::resource
            DRN["Remote Network Data"]:::resource
            DRES[Resource Data]:::resource
        end
    end

    subgraph Client["Client Layer"]
        direction TB
        CL[API Client]:::client
        GQL[GraphQL Handler]:::client
        Cache[Cache Manager]:::client
    end

    subgraph Models["Model Layer"]
        direction TB
        DOM[Domain Models]:::model
        ATTR[Attribute Definitions]:::model
    end

    subgraph Testing["Testing Framework"]
        direction TB
        TF1[Test Framework]:::test
        ACC[Acceptance Tests]:::test
    end

    TF --> PC
    PC --> PI
    PI --> RM
    RM --> ResourceTypes
    RM --> DataSources
    ResourceTypes --> CL
    DataSources --> CL
    CL --> GQL
    CL --> Cache
    GQL --> API
    ResourceTypes --> DOM
    DataSources --> DOM
    DOM --> ATTR

    %% Click events for component mapping
    click PC "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/provider.go"
    click PI "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/provider/"
    click RM "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/resource/all-resources.go"
    click CL "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/client/client.go"
    click Cache "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/client/cache.go"
    click GQL "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/client/query/"
    click DOM "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/model/"
    click CON "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/resource/connector.go"
    click GRP "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/resource/group.go"
    click RN "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/resource/remote-network.go"
    click RES "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/resource/resource.go"
    click DCON "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/datasource/connector.go"
    click DGRP "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/datasource/group.go"
    click DRN "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/datasource/remote-network.go"
    click DRES "https://github.com/Twingate/terraform-provider-twingate/blob/main/twingate/internal/provider/datasource/resource.go"
    click ATTR "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/attr/"
    click TF1 "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/test/"
    click ACC "https://github.com/Twingate/terraform-provider-twingate/tree/main/twingate/internal/test/acctests/"

    %% Legend
    subgraph Legend
        direction TB
        L1[External Systems]:::external
        L2[Core Components]:::core
        L3[Resources]:::resource
        L4[Client Components]:::client
        L5[Models]:::model
        L6[Testing]:::test
    end
```
