# nimbolus/terraform-backend architecture

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

- Interactive diagram: https://gitdiagram.com/nimbolus/terraform-backend
- Repository: https://github.com/nimbolus/terraform-backend

## Overview

This project is a Terraform Backend Server that implements the Terraform HTTP backend API with configurable, plugable modules for authentication, state storage, state locking, and state encryption (KMS). The project structure and README indicate that the server is designed to allow various backends (e.g., file system, S3, Postgres for storage; local, Redis, and Postgres for locking; basic and JWT for authentication; local and Vault/Transit for encryption) to be swapped or extended as needed.

##### Main Components
- HTTP Server – The entrypoint for API requests (see pkg/server and cmd/terraform-backend.go).
- Configuration Module – Located under internal/config.go to load settings (e.g., environment variables).
- Authentication Modules – Under pkg/auth; includes both HTTP Basic and JWT implementations.
- Storage Modules – Under pkg/storage (filesystem, S3, and Postgres drivers), handling state file persistence.
- Locking Modules – In pkg/lock; different implementations (local, Redis, or Postgres) to prevent concurrent modifications.
- KMS / Encryption Modules – In pkg/kms; contains local AES and Vault Transit based encryption.
- API Clients – In pkg/client, which provide abstraction for interacting with external services like Postgres, Redis, and Vault.
- Terraform Integration – The application is designed to be plugged into Terraform’s HTTP backend interface.

##### Relationships and Interactions
- The HTTP Server receives API requests from Terraform clients. It then uses the configuration module to determine which backends to use.
- Once a request is received, the server routes it to the appropriate modules:
- For authentication, the server consults the selected auth module (basic or JWT).
- For state storage, the server interacts with the selected storage backend.
- For state locking, it uses the locking backend to ensure safe updates.
- For state encryption, the KMS module encrypts/decrypts the state files.
- Each module may, in turn, use one or more of the clients (e.g., pkg/client/postgres, pkg/client/redis, or pkg/client/vault) to connect to external systems as required.
- The modularity indicates loosely-coupled components with clear APIs (for instance, the server is decoupled from the specifics of each backend).

##### Architectural Patterns and Design Principles
- Plugable/Modular Architecture – Components have interchangeable modules for authentication, storage, locking, and KMS.
- Separation of Concerns – Each module handles one specific aspect of the backend server.
- Dependency Injection – The system’s configuration allows selecting the appropriate implementations at runtime.
- Clear API boundaries – The HTTP endpoints (designated in the README as /state/<project-id>/<state-name>) interact with modules via defined interfaces.

##### Relevant Technologies, Frameworks, and Libraries
- Go – The project is written in Go using standard project layout practices.
- Terraform HTTP Backend API – The server is built to integrate with Terraform’s backend configuration.
- Docker / Docker Compose – Provided for local testing and deployment, illustrating container-based deployment practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Components"
        Terraform_Client["Terraform Client"]
    end

    subgraph "Core System"
        HTTP_Server["HTTP Server"]
        Config["Configuration Module"]
        Terraform_Integration["Terraform Integration"]
    end

    subgraph "Authentication Modules"
        HTTP_Basic["HTTP Basic"]
        JWT["JWT"]
    end

    subgraph "Storage Modules"
        Filesystem["Filesystem"]
        S3["S3"]
        Postgres_Storage["Postgres Storage"]
    end

    subgraph "Locking Modules"
        Local_Locking["Local Locking"]
        Redis_Locking["Redis Locking"]
        Postgres_Locking["Postgres Locking"]
    end

    subgraph "KMS / Encryption Modules"
        Local_AES["Local AES"]
        Vault_Transit["Vault Transit"]
    end

    subgraph "API Clients"
        Postgres_Client["Postgres Client"]
        Redis_Client["Redis Client"]
        Vault_Client["Vault Client"]
    end

    %% Connections from Terraform Client to Core HTTP Server
    Terraform_Client -->|"APIRequest"| HTTP_Server

    %% HTTP Server uses configuration and Terraform integration
    HTTP_Server -->|"LoadConfig"| Config
    HTTP_Server -->|"TerraformAPI"| Terraform_Integration

    %% HTTP Server routes to Authentication Modules
    HTTP_Server -->|"Authenticate"| HTTP_Basic
    HTTP_Server -->|"Authenticate"| JWT

    %% HTTP Server routes to Storage Modules
    HTTP_Server -->|"StoreState"| Filesystem
    HTTP_Server -->|"StoreState"| S3
    HTTP_Server -->|"StoreState"| Postgres_Storage

    %% HTTP Server routes to Locking Modules
    HTTP_Server -->|"AcquireLock"| Local_Locking
    HTTP_Server -->|"AcquireLock"| Redis_Locking
    HTTP_Server -->|"AcquireLock"| Postgres_Locking

    %% HTTP Server routes to KMS / Encryption Modules
    HTTP_Server -->|"EncryptDecrypt"| Local_AES
    HTTP_Server -->|"EncryptDecrypt"| Vault_Transit

    %% Modules receive configuration settings
    Config -->|"Config"| HTTP_Basic
    Config -->|"Config"| JWT
    Config -->|"Config"| Filesystem
    Config -->|"Config"| S3
    Config -->|"Config"| Postgres_Storage
    Config -->|"Config"| Local_Locking
    Config -->|"Config"| Redis_Locking
    Config -->|"Config"| Postgres_Locking
    Config -->|"Config"| Local_AES
    Config -->|"Config"| Vault_Transit

    %% API Clients connections from modules
    Postgres_Storage -->|"DBCall"| Postgres_Client
    Postgres_Locking -->|"DBCall"| Postgres_Client
    Redis_Locking -->|"DBCall"| Redis_Client
    Vault_Transit -->|"KMSCall"| Vault_Client

    %% Click Events
    click HTTP_Server "https://github.com/nimbolus/terraform-backend/blob/main/cmd/terraform-backend.go"
    click HTTP_Server "https://github.com/nimbolus/terraform-backend/tree/main/pkg/server/"
    click Config "https://github.com/nimbolus/terraform-backend/blob/main/internal/config.go"
    click HTTP_Basic "https://github.com/nimbolus/terraform-backend/blob/main/pkg/auth/basic/basic.go"
    click JWT "https://github.com/nimbolus/terraform-backend/blob/main/pkg/auth/jwt/jwt.go"
    click Filesystem "https://github.com/nimbolus/terraform-backend/tree/main/pkg/storage/filesystem/"
    click S3 "https://github.com/nimbolus/terraform-backend/tree/main/pkg/storage/s3/"
    click Postgres_Storage "https://github.com/nimbolus/terraform-backend/tree/main/pkg/storage/postgres/"
    click Local_Locking "https://github.com/nimbolus/terraform-backend/tree/main/pkg/lock/local/"
    click Redis_Locking "https://github.com/nimbolus/terraform-backend/tree/main/pkg/lock/redis/"
    click Postgres_Locking "https://github.com/nimbolus/terraform-backend/tree/main/pkg/lock/postgres/"
    click Local_AES "https://github.com/nimbolus/terraform-backend/tree/main/pkg/kms/local/"
    click Vault_Transit "https://github.com/nimbolus/terraform-backend/tree/main/pkg/kms/transit/"
    click Postgres_Client "https://github.com/nimbolus/terraform-backend/tree/main/pkg/client/postgres/"
    click Redis_Client "https://github.com/nimbolus/terraform-backend/tree/main/pkg/client/redis/"
    click Vault_Client "https://github.com/nimbolus/terraform-backend/tree/main/pkg/client/vault/"
    click Terraform_Integration "https://github.com/nimbolus/terraform-backend/blob/main/pkg/terraform/terraform.go"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef module fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;

    class Terraform_Client,HTTP_Server,Config,Terraform_Integration core;
    class HTTP_Basic,JWT,Filesystem,S3,Postgres_Storage,Local_Locking,Redis_Locking,Postgres_Locking,Local_AES,Vault_Transit,Postgres_Client,Redis_Client,Vault_Client module;
```
