# wouldgo/terraform-provider-openwrt architecture

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

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

## Overview

##### Project type and purpose
- This is a Terraform provider plugin written in Go.
- Purpose: Expose OpenWrt-specific resources (files, UCI config, opkg packages, system services) as Terraform resources, so users can declaratively manage an OpenWrt device.

##### File structure
- Top-level files:
- `main.go` – entry point for the Terraform plugin.
- `go.mod`/`go.sum` – Go module definitions.
- `GNUmakefile`, `goreleaser.yml` – build & release scripts.
- `docs/`, `examples/` – user documentation & Terraform usage examples.
- `internal/` – divides the code into three subpackages:
- `internal/provider/` – Terraform provider setup (schema, configuration, resource registration).
- `internal/resources/` – implementations of CRUD logic for each resource type (fs/configfile, fs/file, opkg, system services).
- `internal/api/` – low-level client abstractions to perform operations on an OpenWrt device (UCI, filesystem, opkg).
- `internal/types/` – helpers for type conversion and validation.
- Tests are co-located alongside their target packages (`*_test.go`).

##### Extract architecture from README
- Confirms the stack: Terraform CLI ↔ provider plugin ↔ OpenWrt device.
- No built-in UI or database; all state is managed by Terraform and remote device.

##### Main components
A. Terraform CLI
– Reads `.tf` configuration & state files.
– Loads the provider plugin binary.
B. Terraform Registry (optional)
– Hosts official release of `foxboron/openwrt`.
C. Provider Plugin (Go binary)
1. Provider Core (`internal/provider`)
- Registers resources (fs, file, opkg, system).
- Validates provider-level config (e.g. device address, credentials).
2. Resource Layer (`internal/resources`)
- Implements Create/Read/Update/Delete for each Terraform resource.
3. API Client (`internal/api`)
- Abstracts SSH or RPC calls:
– UCI command invocations (`uci.go`)
– File operations (`fs.go`)
– Package management via `opkg` (`opkg.go`)
4. Types (`internal/types`)
- Common type conversions and schema helpers.
D. OpenWrt Device
– Remote target.
– Provides SSH or API access for UCI, filesystem, opkg, system services.

##### Relationships & interactions
- Optionally: Terraform CLI ↔ Terraform Registry (when fetching the plugin)

##### Architectural patterns & principles
- Plugin pattern (Terraform Plugin SDK)
- Layered architecture:
- **API layer** (abstract OS calls)
- **Resource layer** (map Terraform operations to API calls)
- **Provider layer** (schema & orchestration)
- Single binary, no external server.

##### Relevant technologies & frameworks
- Go modules (`go.mod`)
- Terraform Plugin SDK v2
- SSH/UCI/opkg CLI on OpenWrt
- GNU Make & GoReleaser for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Terraform" 
        CLI["Terraform CLI"]:::terraform
        Registry["Terraform Registry"]:::terraform
    end

    subgraph "Module & Build Files"
        GoMod["go.mod"]:::build
        GoSum["go.sum"]:::build
        Makefile["GNUmakefile"]:::build
        Release[".goreleaser.yml"]:::build
        Manifest["terraform-registry-manifest.json"]:::build
    end

    subgraph "Provider Plugin (Go Binary)"
        Entry["main.go"]:::provider

        subgraph "Provider Core"
            ProviderCore["Schema & Config"]:::provider
            ProvGo["provider.go"]:::provider
            ProvTest1["checkers_test.go"]:::provider
            ProvTest2["provider_test.go"]:::provider
        end

        subgraph "Resource Layer"
            ConfigFile["configfile.go"]:::resources
            FileRes["file.go"]:::resources
            OpkgRes["opkg.go"]:::resources
            NTPRes["resource_ntp.go"]:::resources
            RNGDRes["resource_rngd.go"]:::resources
            SystemRes["resource_system.go"]:::resources
            WatchRes["resource_watchcat.go"]:::resources
        end

        subgraph "API Client Layer"
            APIcore["api.go"]:::api
            FSapi["fs.go"]:::api
            OpkgApi["opkg.go"]:::api
            UciApi["uci.go"]:::api
        end

        subgraph "Types & Helpers"
            BoolType["bools.go"]:::types
            StrType["strings.go"]:::types
            TypesFile["types.go"]:::types
        end
    end

    subgraph "Documentation"
        DocIndex["index.md"]:::docs
        DocConfig["configfile.md"]:::docs
        DocFile["file.md"]:::docs
        DocOpkg["opkg.md"]:::docs
        DocSystem["system.md"]:::docs
    end

    subgraph "Examples"
        ExProvider["provider.tf"]:::examples
        ExConfig["openwrt_configfile/resource.tf"]:::examples
        ExFile["openwrt_file/resource.tf"]:::examples
        ExOpkg["openwrt_opkg/resource.tf"]:::examples
        ExSystem["openwrt_system/resource.tf"]:::examples
    end

    OpenWrt["OpenWrt Device"]:::device

    CLI -->|"load plugin"| Entry
    CLI -->|"fetch plugin"| Registry
    Entry -->|"init provider"| ProviderCore
    ProviderCore -->|"Invoke CRUD"| ConfigFile & FileRes & OpkgRes & NTPRes & RNGDRes & SystemRes & WatchRes
    ConfigFile & FileRes & OpkgRes & NTPRes & RNGDRes & SystemRes & WatchRes -->|"call API"| APIcore & FSapi & OpkgApi & UciApi
    APIcore & FSapi & OpkgApi & UciApi -->|"SSH/UCI/opkg"| OpenWrt

    click Entry "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/main.go"
    click ProvGo "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/provider/provider.go"
    click ProvTest1 "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/provider/checkers_test.go"
    click ProvTest2 "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/provider/provider_test.go"
    click ConfigFile "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/fs/configfile.go"
    click FileRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/fs/file.go"
    click OpkgRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/opkg/opkg.go"
    click NTPRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/system/resource_ntp.go"
    click RNGDRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/system/resource_rngd.go"
    click SystemRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/system/resource_system.go"
    click WatchRes "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/resources/system/resource_watchcat.go"
    click APIcore "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/api/api.go"
    click FSapi "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/api/fs.go"
    click OpkgApi "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/api/opkg.go"
    click UciApi "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/api/uci.go"
    click BoolType "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/types/bools.go"
    click StrType "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/types/strings.go"
    click TypesFile "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/internal/types/types.go"
    click GoMod "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/go.mod"
    click GoSum "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/go.sum"
    click Makefile "https://github.com/wouldgo/terraform-provider-openwrt/tree/master/GNUmakefile"
    click Release "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/.goreleaser.yml"
    click Manifest "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/terraform-registry-manifest.json"
    click DocIndex "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/docs/index.md"
    click DocConfig "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/docs/resources/configfile.md"
    click DocFile "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/docs/resources/file.md"
    click DocOpkg "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/docs/resources/opkg.md"
    click DocSystem "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/docs/resources/system.md"
    click ExProvider "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/examples/provider/provider.tf"
    click ExConfig "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/examples/resources/openwrt_configfile/resource.tf"
    click ExFile "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/examples/resources/openwrt_file/resource.tf"
    click ExOpkg "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/examples/resources/openwrt_opkg/resource.tf"
    click ExSystem "https://github.com/wouldgo/terraform-provider-openwrt/blob/master/examples/resources/openwrt_system/resource.tf"

    classDef terraform fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef provider fill:#90EE90,stroke:#000,stroke-width:1px
    classDef resources fill:#98FB98,stroke:#000,stroke-width:1px
    classDef api fill:#8FBC8F,stroke:#000,stroke-width:1px
    classDef types fill:#8EE5EE,stroke:#000,stroke-width:1px
    classDef device fill:#FFA500,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef docs fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef examples fill:#E6E6FA,stroke:#000,stroke-width:1px
```
