# thevops/runblock architecture

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

- Interactive diagram: https://gitdiagram.com/thevops/runblock
- Repository: https://github.com/thevops/runblock

## Overview

The “runblock” project is a command‐line tool designed to extract, list, print, and execute code blocks from Markdown files. Its primary purpose is to allow users to interact easily with code snippets embedded in Markdown, making it particularly useful for developers who need to quickly test or demonstrate code samples.

##### Main Components
- Command-Line Interface (CLI): The entry point is the main.go file, and internal commands are contained in the internal/cmd directory. These components use a CLI framework (as indicated by the README acknowledgement of Cobra).
- Markdown Processing Module: The pkg/markdown.go file, along with other related code in pkg, is responsible for parsing Markdown files. Furthermore, the project leverages Goldmark for Markdown parsing.
- Execution Engine: The functionality for executing code blocks is incorporated within both the CLI commands (in internal/cmd) and library code in pkg/exec.go.
- Logging: There’s a dedicated logging package (pkg/logger/logger.go) which abstracts and handles logging functionalities throughout the tool.
- Example Files and Documentation: The example directory and README provide usage samples and demonstration files.
- Build and Release: Files like Makefile, .goreleaser.yml, and GitHub workflows in .github/workflows indicate the build, CI/CD, and release process.

##### Component Relationships and Interactions
- The CLI (main.go and internal/cmd/*) acts as the system’s facade. It parses user input, invokes the appropriate command (list, print, execute, interactive mode), and then calls into lower-level packages.
- The Markdown processing component (pkg/markdown.go) is invoked by these command routines to extract code blocks from specified Markdown files.
- Code Execution routines (in pkg/exec.go and corresponding internal/cmd/ files) handle executing the extracted code blocks in the current shell.
- Logging is woven throughout the code paths, especially within the execution and CLI handling layers, to provide runtime feedback.
- Configuration for releases and builds are managed through the Makefile and CI/CD configs (GitHub workflows).

##### Architectural Patterns and Design Principles
- Modularity: The separation into internal (commands), pkg (utility functions for execution, markdown parsing, logging), and main.go helps to isolate concerns.
- CLI Framework: By using Cobra (as mentioned in the README), the project adheres to a command-driven architecture suitable for command-line utilities.
- Extensibility: The use of packages and a structured command pattern means that adding new commands or processing steps can be done without overhauling the entire system.

##### Specific Elements
- Logging functionality (pkg/logger) as a cross-cutting concern that interacts with both the CLI and execution modules.
- User Interface components (CLI)
- Core Logic components (Markdown processing, execution)
- Utility components (logging, helper libraries)
- External/deployment support elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U["User Input"]:::core

    %% CLI Layer Subgraph
    subgraph "CLI Layer"
        MA["main.go"]:::cli
        CMD["internal/cmd"]:::cli
    end

    %% Core Processing Subgraph
    subgraph "Core Processing"
        MP["pkg/markdown.go (Markdown Parser)"]:::core
        subgraph "Execution Engine"
            EX1["pkg/exec.go"]:::core
            EX2["internal/cmd/exec.go"]:::core
        end
    end

    %% Utility: Logging
    L["pkg/logger/logger.go (Logging)"]:::utility

    %% External Libraries
    subgraph "External Libraries"
        CB["Cobra"]:::utility
        GM["Goldmark"]:::utility
        CL["Charmbracelet Log"]:::utility
    end

    %% Build & Release Subgraph
    subgraph "Build & Release"
        MF["Makefile"]:::deployment
        GR[".goreleaser.yml"]:::deployment
        GH[".github/workflows/release.yaml"]:::deployment
    end

    %% Documentation and Examples Subgraph
    subgraph "Docs & Examples"
        EXMD["example/example.md"]:::docs
        RD["README.md"]:::docs
    end

    %% Data Flow
    U -->|"triggers"| MA
    MA -->|"dispatches"| CMD
    CMD -->|"invokes"| MP
    MP -->|"extracts code blocks"| EX1
    EX1 -->|"passes execution"| EX2

    %% Logging interactions (dotted arrows)
    CMD ---|"logs"| L
    EX1 ---|"logs"| L
    EX2 ---|"logs"| L

    %% External library associations
    MA ---|"uses"| CB
    CMD ---|"uses"| CB
    MP ---|"parses with"| GM
    L ---|"formats via"| CL

    %% Build & Release and Documentation supporting roles
    MF ---|"builds project"| CMD
    GR ---|"releases project"| CMD
    GH ---|"CI/CD pipeline"| CMD
    RD ---|"provides usage"| U
    EXMD ---|"demonstrates usage"| U

    %% Click Events
    click MA "https://github.com/thevops/runblock/blob/master/main.go"
    click CMD "https://github.com/thevops/runblock/tree/master/internal/cmd"
    click MP "https://github.com/thevops/runblock/blob/master/pkg/markdown.go"
    click EX1 "https://github.com/thevops/runblock/blob/master/pkg/exec.go"
    click EX2 "https://github.com/thevops/runblock/blob/master/internal/cmd/exec.go"
    click L "https://github.com/thevops/runblock/blob/master/pkg/logger/logger.go"
    click EXMD "https://github.com/thevops/runblock/blob/master/example/example.md"
    click RD "https://github.com/thevops/runblock/blob/master/README.md"
    click MF "https://github.com/thevops/runblock/tree/master/Makefile"
    click GR "https://github.com/thevops/runblock/blob/master/.goreleaser.yml"
    click GH "https://github.com/thevops/runblock/blob/master/.github/workflows/release.yaml"

    %% Styles
    classDef cli fill:#FFD580,stroke:#333,stroke-width:2px;
    classDef core fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef utility fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef docs fill:#D7BDE2,stroke:#333,stroke-width:2px;
```
