# k1low/runn architecture

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

- Interactive diagram: https://gitdiagram.com/k1low/runn
- Repository: https://github.com/k1low/runn

## Overview

##### Project Type & Purpose
- This is a Go-based CLI tool and library for “scenario based testing” and “workflow automation.” It serves both as a standalone CLI for running runbook YAML files (which define multi-step scenarios for web requests, gRPC calls, database queries, and even browser automation via CDP) and as a Go test helper package.
- The README and file tree reveal a rich set of “runners” (modules for HTTP, gRPC, DB, CDP, SSH, Exec, etc.) as well as various features like variable binding, loop controls, and dependency between steps. This indicates that the architecture must support executing many different kinds of operations in a unified “runbook” framework.

##### File Structure Analysis
- The top-level directories/files (such as “cmd”, “internal”, “docs”, “examples”, test-related files, etc.) clearly separate the CLI command implementations, internal libraries (including builtin functions and runner-specific logic), and documentation.
- The “cmd” directory contains individual CLI commands (for “new”, “list”, “run”, “rprof”, etc.) which are the entry points of the tool.
- The “internal” tree contains modules for expression evaluation (using expr-lang), built-in runner implementations (e.g., for “bind”, “dump”, “include”), and other helper functionality.
- The presence of multiple YAML files in “testdata” and “docs/designs” shows that the system is driven by configuration – the user’s runbooks that describe a series of steps.

##### Key Architectural Components
A. CLI/Entry Point:
- A “Command-line Interface” component (from the “cmd” folder) that processes user commands and arguments.
- This component loads runbook YAML files and passes them to the core engine.
B. Runbook Parser & Loader:
- A module that reads and parses the YAML runbooks; handles configuration elements such as “runners”, “steps”, “vars”, “labels”, “if”, “loop”, “defer”, etc.
- This processor then creates an in-memory representation of the sequence of steps.
C. Core Execution Engine:
- The central engine that “orchestrates” the execution of runbook steps, performing evaluation of expressions (using the embedded expr-lang engine) and coordinating retries, loops, conditions, etc.
- It also manages storing results into variables (for use later in other steps) and deferring cleanup steps.
D. Runners (Plugin/Strategy Layer):
- Each “runner” is a pluggable module that handles a specific type of operation. Include nodes for:
- HTTP Runner – sends HTTP requests, handles redirection, cookie management, OpenAPI validations.
- gRPC Runner – issues gRPC calls (both unary and streaming), incorporates Buf support.
- DB Runner – executes database queries and records responses.
- CDP Runner – controls the browser via the Chrome DevTools Protocol.
- SSH Runner – runs commands via SSH.
- Exec Runner – executes local commands (with options for background or live output).
- Bind, Dump, Include, and Test runners – built-in modules for binding variables, dumping outputs, including other runbooks, and performing testing assertions.
E. Expression Evaluation & Built-in Functions:
- A dedicated module (or set of libraries) that evaluates the expressions used in “if” conditions, “test” scripts, and variable interpolations.
- This component integrates the built-in functions (e.g., urlencode, compare, diff, merge) to support dynamic behavior.
F. External Services & Dependencies:
- External systems that runners interact with. For example:
- HTTP endpoints and APIs.
- gRPC servers.
- SQL/NoSQL databases.
- Remote SSH hosts.
- Browser sessions (for CDP).

##### Relationships & Data Flow
- The CLI then invokes the Runbook Loader to parse the YAML configuration.
- The Core Execution Engine orchestrates the steps, and for each step, the engine:
– Evaluates conditions or loops using the Expression Evaluator.
– Dispatches to the proper Runner through an abstraction or strategy interface.
– Records the response (e.g., HTTP response, query result) inside its internal “steps” variable map.
- The results (and any bound variables) are used later by subsequent steps.
- Optionally, if steps are “deferred” or “included”, then the engine queues them for later processing.

##### Architectural Patterns & Design Principles
- Use a layered or modular architecture where the CLI is separate from the runbook processing and execution engine.
- The runners adhere to a “plugin” or “strategy” pattern. Each runner implements a common interface to the core engine.
- The engine uses dependency injection (for example, providing custom functions to the expression engine) and supports extension with new runner types.
- Provide clear separation between configuration/input processing (the YAML runbooks) and the runtime execution and reporting components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Initiation
    U["User/CI-CD Pipeline"]:::external

    %% CLI/Entry Point
    CLI["CLI/Entry Point"]:::cli

    %% Runbook Parser & Loader
    RPL["Runbook Parser & Loader"]:::loader

    %% Expression Evaluator & Built-in Functions
    EE["Expression Evaluator"]:::internal
    BF["Built-in Functions"]:::internal

    %% Core Execution Engine
    CE["Core Execution Engine"]:::core

    %% Runners Module
    subgraph "Runners Module"
        HTTP["HTTP Runner"]:::runner
        GRPC["gRPC Runner"]:::runner
        DB["DB Runner"]:::runner
        CDP["CDP Runner"]:::runner
        SSH["SSH Runner"]:::runner
        EXEC["Exec Runner"]:::runner
        BIND["Bind Runner"]:::runner
        DUMP["Dump Runner"]:::runner
        INCLUDE["Include Runner"]:::runner
    end

    %% External Systems
    subgraph "External Systems"
        HTTP_API["HTTP API"]:::external
        GRPC_SRV["gRPC Server"]:::external
        DATABASE["Database"]:::external
        REMOTE_HOST["Remote SSH Host"]:::external
        BROWSER["Browser Session"]:::external
        LOCALSYS["Local System"]:::external
    end

    %% Control Flow
    U -->|"runs"| CLI
    CLI -->|"loadsYAML"| RPL
    RPL -->|"parsesRunbook"| CE
    RPL -->|"evaluates"| EE
    CE -->|"orchestrates"| EE
    CE -->|"delegatesStep"| HTTP
    CE -->|"delegatesStep"| GRPC
    CE -->|"delegatesStep"| DB
    CE -->|"delegatesStep"| CDP
    CE -->|"delegatesStep"| SSH
    CE -->|"delegatesStep"| EXEC
    CE -->|"delegatesStep"| BIND
    CE -->|"delegatesStep"| DUMP
    CE -->|"delegatesStep"| INCLUDE

    %% Runners return results
    HTTP -->|"returns"| CE
    GRPC -->|"returns"| CE
    DB -->|"returns"| CE
    CDP -->|"returns"| CE
    SSH -->|"returns"| CE
    EXEC -->|"returns"| CE
    BIND -->|"returns"| CE
    DUMP -->|"returns"| CE
    INCLUDE -->|"returns"| CE

    %% Runner interactions with External Systems
    HTTP -->|"HTTPrequest"| HTTP_API
    GRPC -->|"gRPCcall"| GRPC_SRV
    DB -->|"query"| DATABASE
    SSH -->|"SSHcommand"| REMOTE_HOST
    CDP -->|"browserControl"| BROWSER
    EXEC -->|"executesCommand"| LOCALSYS

    %% Click Events
    click CLI "https://github.com/k1low/runn/blob/main/cmd/runn/main.go"
    click RPL "https://github.com/k1low/runn/blob/main/runbook.go"
    click CE "https://github.com/k1low/runn/blob/main/operator.go"
    click HTTP "https://github.com/k1low/runn/blob/main/http.go"
    click GRPC "https://github.com/k1low/runn/blob/main/grpc.go"
    click DB "https://github.com/k1low/runn/blob/main/db.go"
    click CDP "https://github.com/k1low/runn/blob/main/cdp.go"
    click SSH "https://github.com/k1low/runn/blob/main/ssh.go"
    click EXEC "https://github.com/k1low/runn/blob/main/exec.go"
    click BIND "https://github.com/k1low/runn/blob/main/bind.go"
    click DUMP "https://github.com/k1low/runn/blob/main/dump.go"
    click INCLUDE "https://github.com/k1low/runn/blob/main/include.go"
    click EE "https://github.com/k1low/runn/blob/main/internal/expr/expr.go"
    click BF "https://github.com/k1low/runn/tree/main/internal/builtin"

    %% Style Definitions
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cli fill:#bbf,stroke:#333,stroke-width:2px;
    classDef loader fill:#bfb,stroke:#333,stroke-width:2px;
    classDef core fill:#ffb,stroke:#333,stroke-width:2px;
    classDef runner fill:#fcc,stroke:#333,stroke-width:2px;
    classDef internal fill:#cfc,stroke:#333,stroke-width:2px;
```
