# mostenberg/soastaperfperl architecture

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

- Interactive diagram: https://gitdiagram.com/mostenberg/soastaperfperl
- Repository: https://github.com/mostenberg/soastaperfperl

## Overview

##### Project type and purpose
- This is an open-source integration tool (a Perl script plus supporting libraries) whose purpose is to automate the execution of SOASTA CloudTest performance tests from within a Jenkins build, collect results, enforce performance thresholds, and publish trends and pass/fail status back into Jenkins.

##### File structure
- Top-level:
- parseSOASTAResultsSummary.pl: main Perl script
- bin/unzip.exe: Windows helper binary
- http-message-master, HTTP-Cookies-6.01, libwww-perl-master: third-party Perl modules under versioned directories
- README.md: high-level instructions for Jenkins setup
- Each module directory contains a Makefile.PL, lib/HTTP/*, and t/ (tests), indicating standard Perl distribution layout.
- No frontend/backend separation; it's a command-line tool that talks over HTTP to external services.

##### README for additional insights
- Dependencies: Jenkins Plot Plugin, JUnit publisher
- Workflow:
a) Jenkins sources the code from GitHub into workspace/SOASTA
b) Jenkins runs parseSOASTAResultsSummary.pl with credentials and thresholds
c) Script invokes SCOMMAND tool to trigger test on CloudTest server
d) Script polls or retrieves results via HTTP (using LWP, HTTP::Message, HTTP::Cookies)
e) Script writes .csv files for metrics and an XML JUnit report for thresholds
f) Jenkins Plot Plugin renders time-series graphs, JUnit publisher shows pass/fail

a. Main components
- GitHub Repository (source code + Perl modules)
- Jenkins CI Server
- SCM step
- Build step (invokes Perl script)
- Plot Plugin
- JUnit Publisher
- Workspace/SOASTA directory
- parseSOASTAResultsSummary.pl
- SCOMMAND executable
- HTTP:: libraries (LWP, HTTP::Message, HTTP::Cookies)
- SOASTA CloudTest Server (external performance test endpoint)
- Artifacts:
- CSV files for Avg/90th/etc.
- 5_PERF_THRESHOLD_RESULTS.xml
b. Relationships and interactions
1. Jenkins polls GitHub → clones into workspace/SOASTA
2. Jenkins executes parseSOASTAResultsSummary.pl
3. Script calls SCOMMAND → issues HTTP requests to CloudTest (via LWP + HTTP::Message)
4. CloudTest executes load test → responds with raw result data
5. Script processes data → writes CSV metrics + JUnit XML
6. Jenkins Plot Plugin reads CSV → generates trends graph
7. Jenkins JUnit Publisher reads XML → marks build PASS/FAIL
c. Architectural patterns/design principles
- Modular reuse of existing CPAN libraries
- Single responsibility: script orchestrates test, data collection, reporting
- Clear separation of concerns:
- SCM
- Execution (Jenkins steps)
- HTTP communication layer (LWP modules)
- Data output
- Reporting plugins
d. Key technologies/frameworks/libraries
- Perl (main script)
- CPAN modules: LWP::UserAgent, HTTP::Message, HTTP::Cookies, HTTP::Headers
- SCOMMAND (SOASTA command-line tool)
- Jenkins with Plot Plugin & JUnit Publisher
- GitHub SCM

##### Detail
- Environment boundaries: Jenkins plugin ecosystem vs. external CloudTest service vs. code repository

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Repository
    GitHubRepo["GitHub Repository"]:::repo

    %% Jenkins Server and Steps
    subgraph "Jenkins Server"
        SCM["SCM Checkout"]:::process
        Build["Build Step\n(parseSOASTAResultsSummary.pl)"]:::process
        Plot["Plot Plugin"]:::process
        JUnitPub["JUnit Publisher"]:::process
    end

    %% Workspace with Code and Modules
    subgraph "Workspace/SOASTA"
        Script["parseSOASTAResultsSummary.pl"]:::module
        Helper["bin/unzip.exe"]:::module
        SCmd["SCOMMAND Executable"]:::module
        subgraph "CPAN Modules"
            CookiesMod["HTTP::Cookies Module"]:::module
            MessageMod["HTTP::Message & Headers"]:::module
            LWPMod["libwww-perl (LWP)"]:::module
        end
        subgraph "Build Scripts"
            MF_Cookies["HTTP-Cookies-6.01/Makefile.PL"]:::module
            MF_Message["http-message-master/Makefile.PL"]:::module
            MF_LWP["libwww-perl-master/Makefile.PL"]:::module
        end
        subgraph "Test Suites"
            Test_Cookies["HTTP-Cookies-6.01/t/cookies.t"]:::module
            Test_Message["http-message-master/t/"]:::module
            Test_LWP["libwww-perl-master/t/"]:::module
        end
    end

    %% External Service
    CloudTest["SOASTA CloudTest Server"]:::external

    %% Artifacts
    CSV["CSV Metrics Files"]:::artifact
    XML["5_PERF_THRESHOLD_RESULTS.xml"]:::artifact

    %% Documentation
    README["README.md"]:::module

    %% Connections
    GitHubRepo -->|cloned by Jenkins| SCM
    SCM -->|into workspace| Script
    SCM -->|into workspace| Helper
    SCM -->|into workspace| CookiesMod
    SCM -->|into workspace| MessageMod
    SCM -->|into workspace| LWPMod
    SCM -->|into workspace| SCmd
    SCM -->|into workspace| MF_Cookies
    SCM -->|into workspace| MF_Message
    SCM -->|into workspace| MF_LWP
    SCM -->|into workspace| Test_Cookies
    SCM -->|into workspace| Test_Message
    SCM -->|into workspace| Test_LWP
    SCM -->|into workspace| README

    Script -->|invokes| SCmd
    Script -->|uses HTTP libs| CookiesMod
    Script -->|uses HTTP libs| MessageMod
    Script -->|uses HTTP libs| LWPMod

    Build -->|runs| Script

    Script -->|HTTP POST test run| CloudTest
    CloudTest -->|HTTP GET results| Script

    Script -->|writes| CSV
    Script -->|writes| XML

    CSV -->|reads| Plot
    XML -->|reads| JUnitPub

    %% Click Events
    click Script "https://github.com/mostenberg/soastaperfperl/blob/master/parseSOASTAResultsSummary.pl"
    click Helper "https://github.com/mostenberg/soastaperfperl/blob/master/bin/unzip.exe"
    click CookiesMod "https://github.com/mostenberg/soastaperfperl/blob/master/HTTP-Cookies-6.01/lib/HTTP/Cookies.pm"
    click MessageMod "https://github.com/mostenberg/soastaperfperl/blob/master/http-message-master/lib/HTTP/Message.pm"
    click LWPMod "https://github.com/mostenberg/soastaperfperl/tree/master/libwww-perl-master/lib/LWP/"
    click MF_Cookies "https://github.com/mostenberg/soastaperfperl/blob/master/HTTP-Cookies-6.01/Makefile.PL"
    click MF_Message "https://github.com/mostenberg/soastaperfperl/blob/master/http-message-master/Makefile.PL"
    click MF_LWP "https://github.com/mostenberg/soastaperfperl/blob/master/libwww-perl-master/Makefile.PL"
    click Test_Cookies "https://github.com/mostenberg/soastaperfperl/blob/master/HTTP-Cookies-6.01/t/cookies.t"
    click Test_Message "https://github.com/mostenberg/soastaperfperl/tree/master/http-message-master/t/"
    click Test_LWP "https://github.com/mostenberg/soastaperfperl/tree/master/libwww-perl-master/t/"
    click README "https://github.com/mostenberg/soastaperfperl/blob/master/README.md"

    %% Styles
    classDef repo fill:#cfe2f3,stroke:#036
    classDef process fill:#d9ead3,stroke:#060
    classDef external fill:#f9cb9c,stroke:#b45f06
    classDef artifact fill:#eeeeee,stroke:#666
    classDef module fill:#c9daf8,stroke:#1155cc
```
