# mondoohq/cnquery architecture

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

- Interactive diagram: https://gitdiagram.com/mondoohq/cnquery
- Repository: https://github.com/mondoohq/cnquery

## Overview

- CLI / Command Interface – The “apps/cnquery” and “cli” directories contain the core command implementations. This is where user commands (run, shell, scan) and query input are handled.
- Query Engine – Look at directories such as “mql”, “mqlc”, “internal”, and “explorer”. These hold the logic for parsing, processing, and executing MQL queries against the infrastructure.
- Providers / Plugin System – The “providers” directory (which is huge and subdivided into many subdirectories for AWS, Azure, Google, Kubernetes, etc.) indicates that providers are modular components. This layer abstracts the connections to external resources and APIs.
- Data Aggregation and Processing – Components like “internal/workerpool” and portions of “llx” (which appear to handle data types, bundling, and transformation) suggest an aggregation layer that collects and processes data from multiple sources.
- SDK and Shared Libraries – The “providers-sdk” and “shared” directories indicate additional reusable libraries, common interface definitions (including gRPC protos) and utilities.
- SBOM and Packaging – The “sbom” directory manages software bill of materials generation, suggesting that the tool also tracks its own dependencies and outputs formal artifact descriptions.
- Logging, Configuration, and Utilities – Throughout the file tree you see “logger”, “cli/config”, “utils”, and “types” that are used for logging, configuration management, error handling, and utility functions.

##### Interactions and Data Flow
- The CLI passes query strings and parameters to the Query Engine, which parses the provided MQL queries (using modules from “mql” and “mqlc”).
- Each provider works via its connection code (often in a “connection” subdirectory) to query external systems such as cloud APIs, Kubernetes clusters, etc.
- The providers return structured resource data back to the Query Engine, which aggregates and processes the data.
- The output is then formatted via reporting functionalities (in “cli/reporter”) and printed to the console or outputted in JSON (or other formats).
- Optionally, the SBOM subsystem gathers metadata and dependencies during builds or runs.
- Throughout these flows, logging and error management (via “logger” and “cli/errors”) capture key events.

##### Architectural Patterns
- Plugin-based architecture: Each provider is a loosely coupled module that implements a common interface, allowing the system to support “over 850 resources” across different services.
- Layered design: The separation between CLI, Query Engine, and Provider integration forms distinct layers (presentation, processing, integration).
- Use of worker pools and concurrency: The “internal/workerpool” indicates that queries and provider calls may run concurrently to speed execution.
- Extensive use of shared protocols: Protobuf definitions in “shared/proto” and in provider-specific directories indicate that inter-component communications and (possibly) remote procedure calls are standardized.

##### Technologies and Frameworks
- The project is implemented in Go and uses Docker (as evidenced by multiple Dockerfiles and devcontainer configurations).
- It utilizes GitHub Actions (under the “.github” directory) for CI/CD and linting.
- The communication between components is supported by gRPC in shared/proto.
- The tool interacts natively with numerous external systems (cloud APIs, container systems, etc.) using provider-specific libraries and protocols.

##### Detailing Essential Architectural Elements
- Plugin architecture clearly: show a common interface between the Query Engine and Provider modules that standardize how queries are sent and responses are returned.
- Configuration and logging components as cross-cutting concerns that interact with almost all modules.

- Optionally, add annotations such as “query parsing,” “data aggregation,” and “reporting” to clarify subsystem responsibilities.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    U("User"):::user

    %% Presentation Layer - CLI
    subgraph "Presentation Layer (CLI)"
        CLI1("CLI: apps/cnquery"):::cli
        CLI2("CLI: cli"):::cli
    end

    %% Core Query Engine
    subgraph "Core Query Engine"
        QE1("Query Engine: mql"):::qe
        QE2("Query Engine: mqlc"):::qe
        QE3("Query Engine: internal"):::qe
        QE4("Query Engine: explorer"):::qe
    end

    %% Providers / Plugin System
    subgraph "Providers / Plugin System"
        PR("Providers: providers"):::prov
    end

    %% Data Aggregation and Processing
    subgraph "Data Aggregation & Processing"
        DA1("Data Aggregation: internal/workerpool"):::dag
        DA2("Data Aggregation: llx"):::dag
    end

    %% SDK and Shared Libraries
    subgraph "SDK and Shared Libraries"
        SDK("SDK: providers-sdk"):::sdk
        SHARED("Shared Libraries: shared"):::sdk
    end

    %% SBOM and Packaging
    subgraph "SBOM and Packaging"
        SB("SBOM: sbom"):::sbom
    end

    %% Logging, Configuration, and Utilities
    subgraph "Logging, Configuration, and Utilities"
        LOG("Logging: logger"):::logcfg
        CFG("Configuration: cli/config"):::logcfg
        UTIL("Utilities: utils"):::logcfg
        TYP("Types: types"):::logcfg
    end

    %% External Systems
    EXT("External Systems/APIs"):::external

    %% Flow Connections
    U -->|"invokes"| CLI1
    U -->|"invokes"| CLI2

    CLI1 -->|"forwards"| QE1
    CLI2 -->|"forwards"| QE1

    QE1 -->|"parses"| QE2
    QE2 -->|"processes"| QE3
    QE3 -->|"executes"| QE4

    QE4 -->|"dispatches"| PR
    PR -->|"returnsData"| QE4

    QE4 -->|"aggregates"| DA1
    QE4 -->|"aggregates"| DA2

    PR -->|"queries"| EXT

    PR -->|"uses"| SDK
    PR -->|"uses"| SHARED

    QE4 -->|"packages"| SB

    %% Logging connections (cross-cutting)
    CLI1 -->|"logs"| LOG
    QE1 -->|"logs"| LOG
    PR -->|"logs"| LOG
    DA1 -->|"logs"| LOG

    %% Class Definitions
    classDef user fill:#D6EAF8, stroke:#2874A6, stroke-width:2px;
    classDef cli fill:#AED6F1, stroke:#1B4F72, stroke-width:2px;
    classDef qe fill:#A9DFBF, stroke:#1E8449, stroke-width:2px;
    classDef prov fill:#F9E79F, stroke:#B7950B, stroke-width:2px;
    classDef dag fill:#F5CBA7, stroke:#7D6608, stroke-width:2px;
    classDef sdk fill:#D2B4DE, stroke:#6C3483, stroke-width:2px;
    classDef sbom fill:#F1948A, stroke:#922B21, stroke-width:2px;
    classDef logcfg fill:#D5F5E3, stroke:#117A65, stroke-width:2px;
    classDef external fill:#FAD7A0, stroke:#B03A2E, stroke-width:2px;

    %% Click Events
    click CLI1 "https://github.com/mondoohq/cnquery/tree/main/apps/cnquery"
    click CLI2 "https://github.com/mondoohq/cnquery/tree/main/cli"
    click QE1 "https://github.com/mondoohq/cnquery/tree/main/mql"
    click QE2 "https://github.com/mondoohq/cnquery/tree/main/mqlc"
    click QE3 "https://github.com/mondoohq/cnquery/tree/main/internal"
    click QE4 "https://github.com/mondoohq/cnquery/tree/main/explorer"
    click PR "https://github.com/mondoohq/cnquery/tree/main/providers"
    click DA1 "https://github.com/mondoohq/cnquery/tree/main/internal/workerpool"
    click DA2 "https://github.com/mondoohq/cnquery/tree/main/llx"
    click SDK "https://github.com/mondoohq/cnquery/tree/main/providers-sdk"
    click SHARED "https://github.com/mondoohq/cnquery/tree/main/shared"
    click SB "https://github.com/mondoohq/cnquery/tree/main/sbom"
    click LOG "https://github.com/mondoohq/cnquery/tree/main/logger"
    click CFG "https://github.com/mondoohq/cnquery/tree/main/cli/config"
    click UTIL "https://github.com/mondoohq/cnquery/tree/main/utils"
    click TYP "https://github.com/mondoohq/cnquery/tree/main/types"
```
