# terraform-linters/tflint architecture

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

- Interactive diagram: https://gitdiagram.com/terraform-linters/tflint
- Repository: https://github.com/terraform-linters/tflint

## Overview

- Parse and analyze Terraform configurations
- Execute linting rules (both built-in and plugin-supplied)
- Provide output in various formats
- Optionally offer integrations like language server capabilities and Docker usage

##### Main Components

a. Command-Line Interface (CLI)
– Represented by the “cmd” directory (files such as cli.go, init.go, version.go, etc.).
– It handles user input, initialization, and the overall execution flow.
– This component triggers plugin initialization, configuration loading, and subsequent linter operations.

b. Configuration & Core Linting Engine
– Located partly in the “tflint” package and the “terraform” directory.
– Responsible for loading configurations (as shown in files like config.go), parsing Terraform files (under terraform/parser.go and related files), and executing the linting logic.
– Acts as the heart of the application by evaluating rules, managing module references, and reporting issues.

c. Plugin Framework
– Found in the “plugin” directory and related stub-generator sources.
– Manages discovery, installation, checksum verification (e.g. checksum.go), and executing external plugins.
– Enables extensibility so that linting rules can be added or overridden (notice the bundled plugin mechanism for rulesets such as AWS, Azure, GCP, etc.).
– The configuration files (like .tflint.hcl examples in the README) indicate how users add/enable their plugins.

d. Formatter Layer
– Present in the “formatter” directory.
– Converts internal lint diagnostics into various user-facing formats: JSON, checkstyle, junit, compact, and SARIF.
– Should be represented as a component that accepts results from the linting core and outputs the final report.

e. Language Server
– Implemented in the “langserver” directory.
– Provides IDE integrations by enabling real-time linting data and other communications via protocols (files include text_document_did_open.go, handler.go, etc.).
– Mark it as an optional integration service that is invoked when users run the tool with the “--langserver” flag.

f. Integration and Testing Infrastructure
– The “integrationtest” directory contains various test scenarios and sample Terraform configurations.
– Though primarily for testing, this outlines the expected flows from user input through parsing and linting to output.

g. Supporting and Build Infrastructure
– Acknowledge the presence of Dockerfile, Makefile, CI/CD workflows (in .github/workflows), and various shell scripts.
– These files indicate how the application is built, containerized, and released. Mark them as supporting components that feed into the continuous integration/deployment pipeline.

##### Relationships and Interactions

– The CLI component acts as the entry point. It interacts with the configuration loader which, in turn, initializes the linting engine.
– The linting engine consults the Plugin Framework to load built-in and user-supplied rules.
– Once rules are evaluated on Terraform configurations (using parsing and evaluation logic from the “terraform” packages), the results are passed to the Formatter for output.
– Optionally, if running in language server mode, the langserver component will interface with an IDE, receiving real-time file changes and providing feedback.
– Surround the main process with integration flows (and testing feedback loops) that verify the rule engine’s integrity.
– Also, highlight the CI/CD components (Docker, GitHub workflows) that orchestrate builds, tests, and releases.

##### Architectural Patterns and Design Principles

– Plugin Architecture: Emphasize that TFLint is designed to be extended via plugins, hence use a “plugin manager” or “modular” component that supports dynamic loading and validation (e.g., checksum/signer verification).
– Layered Design: Separate interaction concerns (CLI, language server) from business logic (parsing, evaluation) and output (formatter).
– Extensibility & Reusability: Indicate that the engine is built to support multiple Terraform providers by enabling external rulesets.
– Testing/Integration: Clearly mark the usage of integration tests that simulate real-world scenarios and validate end-to-end flows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes
    CLI["CLI (cmd)"]:::cli
    Core["Core Engine (tflint/terraform)"]:::engine
    Formatter["Formatter (formatter)"]:::formatter
    LS["Language Server (langserver)"]:::langserver
    IT["Integration Tests (integrationtest)"]:::integration
    CI["CI/CD & Build (Dockerfile, Makefile, Workflows)"]:::support

    %% Plugin Framework Subgraph
    subgraph "Plugin Framework"
        PluginManager["Plugin Manager"]:::plugin
        Stub["Stub Generator"]:::plugin
    end

    %% Relationships
    CLI -->|"triggers"| Core
    Core -->|"loads rules from"| PluginManager
    Core -->|"sends results to"| Formatter
    CLI -->|"invokes with--langserver"| LS
    IT -->|"validates"| Core
    CI -->|"builds and tests"| CLI
    CI -->|"orchestrates"| IT

    %% Styles
    classDef cli fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef engine fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef plugin fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef formatter fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef langserver fill:#EE82EE,stroke:#333,stroke-width:2px;
    classDef integration fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef support fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/terraform-linters/tflint/tree/master/cmd"
    click Core "https://github.com/terraform-linters/tflint/tree/master/tflint"
    click PluginManager "https://github.com/terraform-linters/tflint/tree/master/plugin"
    click Stub "https://github.com/terraform-linters/tflint/tree/master/plugin/stub-generator"
    click Formatter "https://github.com/terraform-linters/tflint/tree/master/formatter"
    click LS "https://github.com/terraform-linters/tflint/tree/master/langserver"
    click IT "https://github.com/terraform-linters/tflint/tree/master/integrationtest"
    click CI "https://github.com/terraform-linters/tflint/tree/master/.github/workflows"
```
