# storagebits/venom architecture

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

- Interactive diagram: https://gitdiagram.com/storagebits/venom
- Repository: https://github.com/storagebits/venom

## Overview

##### Main Project Components
- CLI Component: Represent the “cli” directory (especially cli/venom) as the entry point. This is where the command line commands are parsed and dispatched. Also include the update and version subdirectories.
- Core Engine: Identify the core logic files (e.g., venom.go, process.go, extract.go, templater.go, process_files.go, process_testcase.go, etc.) that parse test suites, handle variables, and coordinate the processing of test steps.
- Executors: Illustrate the “executors” directory as a collection of modular components (dbfixtures, exec, http, imap, kafka, etc.). Each executor implements the same interface but handles a specific protocol or type of test step.
- Assertion Framework: Include the assertions package and related files (assertion.go, assertion_test.go, etc.) that encapsulate the assertion keywords, evaluation, and result handling.
- Context Layer: Show the “context” folder with its distinct implementations (default, redis, webctx) used to store and manage shared data across steps in a test case.
- Testing/Example Suites: Represent the “tests” directory as a sample or integration test repository that demonstrates how test suites are structured and used to run end-to-end tests on the system.

##### Relationships and Data Flow
- The CLI Component interacts with the Core Engine by receiving user commands (such as “venom run”) and dispatching them.
- The Core Engine reads test suite files (from the tests folder or user-specified locations), parses the YAML/JSON definitions, substitutes variables/templating, and builds an execution plan.
- Optionally, include an output/reporting component that takes the aggregate test results and generates xUnit (or other) formatted files.

##### Architectural Patterns and Design Principles
- Modular and pluggable executors: The design clearly favors a plugin-like mechanism where each executor is self-contained but exposes a uniform “Run” method per the Executor interface.
- Separation of Concerns: Distinct modules for CLI, core processing, executor handling, assertions, and context help keep responsibilities separate.
- Dependency Injection / Interface-based design: Each test step is decoupled from specific executor logic with standardized interfaces, facilitating extensibility.
- Template and Variable Substitution: The templating functionality seen in the README indicates that preprocessing of test scripts and variable interpolation is a central concept.

##### Relevant Technologies and Frameworks
- The project is written in Go, so indicate that the system leverages Go’s module system (with go.mod and go.sum), testing libraries, and a custom assertion library.
- The use of Makefile, golangci.yml, and linting.mk indicates build automation and code quality practices that support the overall architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI - Command Entry Point"]:::cli
    end

    %% Core Processing Layer
    subgraph "Core Engine - Test Runner & Orchestrator"
        direction TB
        core1["venom.go"]:::core
        core2["process.go"]:::core
        core3["extract.go"]:::core
        core4["templater.go"]:::core
        core5["process_files.go"]:::core
        core6["process_testcase.go"]:::core
        core7["process_teststep.go"]:::core
        core8["process_testsuite.go"]:::core
    end

    %% Executors Layer
    subgraph "Executors"
        direction TB
        ex1["Executor: Exec"]:::executor
        ex2["Executor: HTTP"]:::executor
        ex3["Executor: IMAP"]:::executor
        ex4["Executor: Kafka"]:::executor
    end

    %% Assertion Framework Layer
    subgraph "Assertion Framework"
        direction TB
        a1["assertion.go"]:::assertion
        a2["assertion_test.go"]:::assertion
        a3["Assertions: assertions.go"]:::assertion
        a4["Assertions: assertions_test.go"]:::assertion
        a5["Assertions: helper.go"]:::assertion
    end

    %% Context Layer
    subgraph "Context Layer"
        direction TB
        ctx1["Default Context"]:::context
        ctx2["Redis Context"]:::context
        ctx3["WebCtx Context"]:::context
    end

    %% Testing Suites
    subgraph "Testing/Example Suites"
        testsuite["Test Suites"]:::test
    end

    %% Report Generator (Output Component)
    report["Report Generator"]:::report

    %% Data Flows and Interactions
    CLI -->|"sendsCommand"| core1
    testsuite -->|"providesTests"| core1
    core1 -->|"delegatesTo"| ex1
    core1 --> ex2
    core1 --> ex3
    core1 --> ex4
    ex1 -->|"returnsResult"| a1
    ex2 -->|"returnsResult"| a1
    ex3 -->|"returnsResult"| a1
    ex4 -->|"returnsResult"| a1
    a1 -->|"generatesReport"| report
    core1 <-->|"sharesState"| ctx1
    core1 <--> ctx2
    core1 <--> ctx3
    %% Chain Core Engine internal modules vertically
    core1 --> core2
    core2 --> core3
    core3 --> core4
    core4 --> core5
    core5 --> core6
    core6 --> core7
    core7 --> core8
    core8 -->|"aggregatesResults"| report

    %% Styles
    classDef cli fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef executor fill:#f94144,stroke:#333,stroke-width:2px;
    classDef assertion fill:#277da1,stroke:#333,stroke-width:2px;
    classDef context fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef test fill:#577590,stroke:#333,stroke-width:2px;
    classDef report fill:#6a4c93,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/storagebits/venom/tree/master/cli/venom"
    click core1 "https://github.com/storagebits/venom/blob/master/venom.go"
    click core2 "https://github.com/storagebits/venom/blob/master/process.go"
    click core3 "https://github.com/storagebits/venom/blob/master/extract.go"
    click core4 "https://github.com/storagebits/venom/blob/master/templater.go"
    click core5 "https://github.com/storagebits/venom/blob/master/process_files.go"
    click core6 "https://github.com/storagebits/venom/blob/master/process_testcase.go"
    click core7 "https://github.com/storagebits/venom/blob/master/process_teststep.go"
    click core8 "https://github.com/storagebits/venom/blob/master/process_testsuite.go"
    click ex1 "https://github.com/storagebits/venom/tree/master/executors/exec"
    click ex2 "https://github.com/storagebits/venom/tree/master/executors/http"
    click ex3 "https://github.com/storagebits/venom/tree/master/executors/imap"
    click ex4 "https://github.com/storagebits/venom/tree/master/executors/kafka"
    click a1 "https://github.com/storagebits/venom/blob/master/assertion.go"
    click a2 "https://github.com/storagebits/venom/blob/master/assertion_test.go"
    click a3 "https://github.com/storagebits/venom/blob/master/assertions/assertions.go"
    click a4 "https://github.com/storagebits/venom/blob/master/assertions/assertions_test.go"
    click a5 "https://github.com/storagebits/venom/blob/master/assertions/helper.go"
    click ctx1 "https://github.com/storagebits/venom/tree/master/context/default"
    click ctx2 "https://github.com/storagebits/venom/tree/master/context/redis"
    click ctx3 "https://github.com/storagebits/venom/tree/master/context/webctx"
    click testsuite "https://github.com/storagebits/venom/tree/master/tests"
```
