# wfouche/tulip architecture

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

- Interactive diagram: https://gitdiagram.com/wfouche/tulip
- Repository: https://github.com/wfouche/tulip

## Overview

##### Project type and purpose
- This is a Kotlin-based multi-module library and CLI utility for load testing, stress testing, and performance regression (“Tulip”).
- It provides both a core runtime SDK (tulip-runtime) and example CLI apps/utilities (tulip-main, kwrk via JBang), plus scripts and sandbox experiments.

##### File structure
- Top-level build infrastructure:
- buildSrc (custom Gradle conventions)
- gradle/, gradlew, CI workflows (.github/workflows)
- Modules:
- tulip-runtime – the core SDK (API, engine, reporting, user abstractions)
- tulip-main – example app that uses the runtime to run benchmarks
- Utilities & scripts:
- scripts/ – Java/Kotlin/JS/Jython helpers and demo servers
- sandbox/ – ad hoc experiments and prototyping
- Documentation:
- doc/ – design ADRs, presentations
- README.adoc – project overview and CLI usage
- Reports and sample output in reports/

##### README for additional insights
- Tulip is analogous to JMeter/Gatling/Locust.
- It has a `kwrk` HTTP benchmark utility built with the runtime.
- Output: JSON and HTML reports.
- Designed for JVM (Kotlin/Java) and uses JBang for distribution of `kwrk`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI
    subgraph "Build & CI"
        BS["buildSrc"]:::build
        GH["GitHub Actions"]:::build
        GW1["gradlew"]:::build
        GW2["gradlew.bat"]:::build
        GW3["gradle/"]:::build
        GW4["settings.gradle.kts"]:::build
    end

    %% CLI Applications
    subgraph "CLI Applications" 
        CLI["tulip-main / kwrk"]:::cli
        CL1["benchmark_config.jsonc"]:::cli
        CL2["App.kt (Picocli)"]:::cli
    end

    %% Tulip Runtime (Core SDK)
    subgraph "Tulip Runtime (Core SDK)"
        subgraph "API Layer"
            A1["TulipApi"]:::runtime
            A2["TulipConsole"]:::runtime
            A3["TulipUserFactory"]:::runtime
            A4["TulipUtils"]:::runtime
            A5["TulipUser.kt"]:::runtime
        end
        subgraph "Core Engine"
            C1["Tulip.kt"]:::runtime
            C2["TulipMarkov.kt"]:::runtime
        end
        subgraph "Reporting Engine"
            R1["TulipReport.kt"]:::runtime
            R2["report_py.java"]:::runtime
            R3["report2_py.java"]:::runtime
        end
        subgraph "User Abstractions"
            U1["HttpUser.java"]:::runtime
            U2["HttpUser_RestClient.java"]:::runtime
            U3["HttpUserTest.java"]:::runtime
        end
    end

    %% External Service
    EXT["External HTTP Service"]:::external

    %% Reports Output
    REP["Reports (JSON/HTML)"]:::output

    %% Utilities & Scripts
    OPS["scripts/ & sandbox/"]:::optional

    %% Documentation
    DOC["Documentation (doc/, README.adoc)"]:::optional

    %% Connections
    CLI -->|"invokes"| A1
    CLI -->|"loads config"| CL1
    CL2 -->|"parses args"| A1
    A1 -->|"calls core"| C1
    C1 -->|"executes scenarios"| C2
    C1 -->|"sends HTTP requests"| EXT
    C1 -->|"generates data"| R1
    R1 -->|"renders templates"| R2
    R1 --> R3
    R1 -->|"writes reports"| REP
    BS -->|"provides conventions"| tulip-runtime
    GH -->|"CI build/test/publish"| tulip-runtime
    GW1 -->|"build tasks"| tulip-runtime
    GW2 -->|"build tasks"| tulip-runtime
    GW3 -->|"Gradle tooling"| tulip-runtime
    GW4 -->|"settings"| tulip-runtime
    OPS -->|"optional triggers"| CLI
    OPS -->|"experiments"| tulip-runtime
    DOC -->|"design docs"| tulip-runtime

    %% Click Events
    click BS "https://github.com/wfouche/tulip/tree/main/buildSrc/"
    click GH "https://github.com/wfouche/tulip/blob/main/.github/workflows/release.yml"
    click GW1 "https://github.com/wfouche/tulip/tree/main/gradlew"
    click GW2 "https://github.com/wfouche/tulip/blob/main/gradlew.bat"
    click GW3 "https://github.com/wfouche/tulip/tree/main/gradle/"
    click GW4 "https://github.com/wfouche/tulip/blob/main/settings.gradle.kts"
    click CLI "https://github.com/wfouche/tulip/tree/main/tulip-main/"
    click CL1 "https://github.com/wfouche/tulip/blob/main/tulip-main/benchmark_config.jsonc"
    click CL2 "https://github.com/wfouche/tulip/blob/main/tulip-main/src/main/kotlin/org/example/app/App.kt"
    click A1 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/api/TulipApi.java"
    click A2 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/api/TulipConsole.java"
    click A3 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/api/TulipUserFactory.java"
    click A4 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/api/TulipUtils.java"
    click A5 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/kotlin/io/github/wfouche/tulip/api/TulipUser.kt"
    click C1 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/kotlin/io/github/wfouche/tulip/core/Tulip.kt"
    click C2 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/kotlin/io/github/wfouche/tulip/pfsm/TulipMarkov.kt"
    click R1 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/kotlin/io/github/wfouche/tulip/report/TulipReport.kt"
    click R2 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/report/report_py.java"
    click R3 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/report/report2_py.java"
    click U1 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/user/HttpUser.java"
    click U2 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/user/HttpUser_RestClient.java"
    click U3 "https://github.com/wfouche/tulip/blob/main/tulip-runtime/src/main/java/io/github/wfouche/tulip/user/HttpUserTest.java"

    %% Styles
    classDef build fill:#ccf,stroke:#339,stroke-width:1px
    classDef cli fill:#cfc,stroke:#393,stroke-width:1px
    classDef runtime fill:#fc9,stroke:#f90,stroke-width:1px
    classDef external fill:#ff9,stroke:#fa0,stroke-width:1px
    classDef output fill:#c9f,stroke:#96f,stroke-width:1px
    classDef optional fill:#eee,stroke:#999,stroke-width:1px
```
