# azat/chdig architecture

> Architecture diagram of the GitHub repository azat/chdig, 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/azat/chdig
- Repository: https://github.com/azat/chdig

## Overview

##### Main Components
- Entry Point & Core Library:
- Main entry point (src/main.rs) and the core library (src/lib.rs), which bootstraps the application.
- TUI/View Layer:
- TUI interface driven by multiple view modules (located in src/view, such as log_view, text_log_view, process_view, query_result_view, etc.) that render different data perspectives.
- Interpreter/Business Logic Layer:
– Background Runner (background_runner.rs): handling asynchronous/background tasks.
– ClickHouse Connector (clickhouse.rs and clickhouse_quirks.rs): managing the communication with the ClickHouse server.
– Query Processing (query_process.rs & options.rs): parsing options and processing query results.
– Flamegraph Generation (flamegraph.rs): converting performance data into flamegraph representations.
- Action Handling:
- Actions module (src/actions.rs), which likely maps user commands—triggered by the TUI—to business logic operations.
- Utility & Common Modules:
- A utilities block (src/utils.rs) and common components (src/common/stopwatch.rs, etc.) that support shared functions and timing utilities.
- External Systems:
- External ClickHouse server, which the application communicates with to fetch system and query log data.
- Configuration & Build/Deployment:
- Although not the application runtime, note the existence of configuration files (Cargo.toml, Cargo.lock, rustfmt.toml) and workflows (in .github/workflows) that indicate continuous integration/deployment pipelines.

##### Relationships and Interactions
- That the application’s entry point initializes the core components and wires up the TUI (view layer) with the interpreter.
- That the interpreter connects with the ClickHouse connector module which, in turn, communicates externally with the ClickHouse server.
- Optionally, include lines connecting shared utilities (from common and utils) with the interpreter and the TUI, as supporting infrastructure for time measurements, logging, or view data formatting.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Modular Design:
- Each view (for logs, queries, metrics) is implemented as a distinct module under src/view, implying that the system can be extended by adding new views or modifying existing ones.
- Asynchronous/Background Processing:
- Role of the background_runner and worker modules in handling asynchronous query execution or updates.
- External Integration:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Bootstrapping Layer
    subgraph "Entry & Bootstrapping"
        mainEntry["Entry Point (main.rs)"]
        libCore["Core Library (lib.rs)"]
    end

    %% Presentation Layer: TUI/View
    subgraph "Presentation Layer (TUI/View)"
        tuiViews["TUI Views (multiple modules)"]
    end

    %% Action Handling Layer
    subgraph "Action Handling"
        actions["Action Module (actions.rs)"]
    end

    %% Business Logic / Interpreter Layer
    subgraph "Business Logic / Interpreter Layer"
        bgRunner["Background Runner (background_runner.rs)"]
        queryProcess["Query Processing (query_process.rs)"]
        options["Options Parser (options.rs)"]
        chConnector["ClickHouse Connector (clickhouse.rs)"]
        chQuirks["ClickHouse Quirks (clickhouse_quirks.rs)"]
        context["Context (context.rs)"]
        flamegraph["Flamegraph Generator (flamegraph.rs)"]
        worker["Worker (worker.rs)"]
    end

    %% Utilities & Common Support
    subgraph "Utilities & Common"
        utilsModule["Utils (utils.rs)"]
        commonModule["Common Modules (src/common)"]
        stopwatch["Stopwatch (stopwatch.rs)"]
    end

    %% External System
    subgraph "External System"
        chServer["ClickHouse Server"]
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        cargoToml["Cargo.toml"]
        cargoLock["Cargo.lock"]
        rustfmt["rustfmt.toml"]
        workflows["Workflows (.github/workflows)"]
    end

    %% Connections: Bootstrapping initialization
    mainEntry --> tuiViews
    mainEntry --> actions
    libCore --> queryProcess
    libCore --> tuiViews

    %% TUI interactions
    tuiViews -->|"triggers"| actions

    %% Action Handling to Business Logic
    actions -->|"executes"| queryProcess
    actions -->|"spawns"| bgRunner

    %% Query Processing and Interpreter Components
    queryProcess -->|"parsesOptions"| options
    queryProcess -->|"invokesConnector"| chConnector
    queryProcess -->|"handlesQuirks"| chQuirks
    queryProcess -->|"buildsContext"| context
    queryProcess -->|"generatesFlamegraph"| flamegraph

    %% Background tasks
    bgRunner -->|"delegatesTask"| worker

    %% Interpreter External Communication
    chConnector -->|"queries"| chServer
    chQuirks   -->|"queries"| chServer
    chServer   -->|"returnsData"| queryProcess

    %% Utilities Support
    utilsModule --> tuiViews
    utilsModule --> queryProcess
    commonModule --> tuiViews
    commonModule --> queryProcess
    stopwatch --> tuiViews
    stopwatch --> bgRunner

    %% Class Definitions for Colors
    classDef entry fill:#f9c,stroke:#333,stroke-width:2px;
    classDef tui fill:#b3d9ff,stroke:#333,stroke-width:2px;
    classDef action fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef interpreter fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef utils fill:#ffffb3,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef config fill:#d9b3ff,stroke:#333,stroke-width:2px;

    %% Assign Classes to Nodes
    class mainEntry,libCore entry;
    class tuiViews,tui fill;
    class actions action;
    class bgRunner,queryProcess,options,chConnector,chQuirks,context,flamegraph,worker interpreter;
    class utilsModule,commonModule,stopwatch utils;
    class chServer external;
    class cargoToml,cargoLock,rustfmt,workflows config;

    %% Click Events for Components
    click mainEntry "https://github.com/azat/chdig/blob/main/src/main.rs"
    click libCore "https://github.com/azat/chdig/blob/main/src/lib.rs"
    click tuiViews "https://github.com/azat/chdig/tree/main/src/view/"
    click actions "https://github.com/azat/chdig/blob/main/src/actions.rs"
    click bgRunner "https://github.com/azat/chdig/blob/main/src/interpreter/background_runner.rs"
    click queryProcess "https://github.com/azat/chdig/blob/main/src/interpreter/query_process.rs"
    click options "https://github.com/azat/chdig/blob/main/src/interpreter/options.rs"
    click chConnector "https://github.com/azat/chdig/blob/main/src/interpreter/clickhouse.rs"
    click chQuirks "https://github.com/azat/chdig/blob/main/src/interpreter/clickhouse_quirks.rs"
    click context "https://github.com/azat/chdig/blob/main/src/interpreter/context.rs"
    click flamegraph "https://github.com/azat/chdig/blob/main/src/interpreter/flamegraph.rs"
    click worker "https://github.com/azat/chdig/blob/main/src/interpreter/worker.rs"
    click utilsModule "https://github.com/azat/chdig/blob/main/src/utils.rs"
    click commonModule "https://github.com/azat/chdig/tree/main/src/common/"
    click stopwatch "https://github.com/azat/chdig/blob/main/src/common/stopwatch.rs"
    click cargoToml "https://github.com/azat/chdig/blob/main/Cargo.toml"
    click cargoLock "https://github.com/azat/chdig/blob/main/Cargo.lock"
    click rustfmt "https://github.com/azat/chdig/blob/main/rustfmt.toml"
    click workflows "https://github.com/azat/chdig/tree/main/.github/workflows/"
```
