# endava/cats architecture

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

- Interactive diagram: https://gitdiagram.com/endava/cats
- Repository: https://github.com/endava/cats

## Overview

##### Overall Project Type and Purpose
- This is a monolithic CLI tool built using Java/Maven.
- Its goal is to generate, execute, and report on API tests using a comprehensive set of “fuzzers” that cover various scenarios.
- It includes modules for reading API contracts (e.g., via OpenAPI), generating test payloads, executing HTTP calls, and reporting results (HTML, JUnit, etc).

##### Identifying the Main Components
- CLI/Entry Point: Represent the main application (CatsMain) as the starting point. This is where the command line arguments are parsed.
- Command Dispatcher: The command package holds various command implementations (e.g., RunCommand, ListCommand, InfoCommand) directing the application flow.
- Core Engine: This includes the central context (CatsGlobalContext) and configuration (CatsConfiguration) which passes execution parameters across components.
- Fuzzing Modules: Multiple “fuzzer” sub-packages are neatly organized into areas such as:
– Fields Fuzzers (e.g., BaseFieldsFuzzer and its variants organized by type such as leading, trailing, within, only),
– Header Fuzzers (with similar sub-organization),
– HTTP Fuzzers (handling method variations, payload anomalies, etc.),
– Special Fuzzers: handling functional, random, security, or template-based fuzzing.
- DSL Parsing: The DSL packages (e.g., CatsDSLParser, various DSL implementations) handle the parsing of simple non-code syntax provided by the user.
- Generator Modules: Organize generators for data formats (under “generator/format”) and for “simple” generation that produce test payloads and value variations.
- I/O and HTTP Layer: The “io” package encapsulates the ServiceCaller, HTTP handling (which internally may use the forked version of OkHttp) and related utilities.
- Reporting: The reporting module that constructs test reports in various formats (HTML, JUnit, etc.) and monitors execution statistics.
- OpenAPI and Contract Parsing: The “openapi” package and related classes extract API definitions and update test cases as the contract changes.
- Utility/Helper Classes: Shared utilities (e.g., CatsUtil, JsonUtils, VersionChecker, etc.) facilitate cross-module functions.

##### Relationships and Data Flow
- Start at the CLI/Entry point which routes to a specific command.
- The selected Command interacts with the Global Context and dispatches responsibilities to:
– The Fuzzing Engine: which iterates through available Fuzzers.
– The DSL and Generator modules that dynamically create request payloads, using configuration arguments (found in the args package).
– The HTTP Client (in the io package), which sends test requests.
– The Report Generator, that listens and collates the output into reports.
- External libraries – such as the forked OkHttp and swagger-parser – should be annotated as dependencies within the respective modules (HTTP execution and OpenAPI contract generation).

##### Architectural Patterns and Design Principles
- Modular design: Different packages/submodules (commands, fuzzers, DSL, generator, reporting) are largely independent, making it easier to extend the tool with new test scenarios.
- Plugin-like extensibility: The fuzzer modules and DSL parsers use polymorphism (abstract/factory patterns evident in the base fuzzer classes) to allow additional strategies without major changes to the core.
- Command pattern: Each CLI command encapsulates its function inside dedicated classes (e.g., RunCommand, LintCommand).
- Clear separation of concerns: There is a distinct separation between generating test cases, executing them, handling HTTP interactions, and reporting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (CatsMain)"]:::cli
        CMD["Command Dispatcher"]:::cmd
    end

    %% Core Engine
    subgraph "Core Engine"
        CTX["CatsGlobalContext"]:::core
        CFG["CatsConfiguration"]:::core
    end

    %% Fuzzing Modules
    subgraph "Fuzzing Modules"
        FF["Fields Fuzzers"]:::fuzzer
        HF["Header Fuzzers"]:::fuzzer
        HF2["HTTP Fuzzers"]:::fuzzer
        SF["Special Fuzzers"]:::fuzzer
    end

    %% Test Generation
    subgraph "Test Generation"
        DSL["DSL Parsing"]:::generator
        GEN["Generator Modules"]:::generator
    end

    %% Execution Layer
    subgraph "Execution Layer"
        IO["I/O and HTTP Layer"]:::http
    end

    %% Reporting
    subgraph "Reporting"
        REP["Report Generator"]:::report
    end

    %% Contract & OpenAPI
    subgraph "Contract & OpenAPI"
        OAPI["OpenAPI & Contract Parsing"]:::openapi
    end

    %% Utilities
    subgraph "Utilities"
        UTIL["Utility/Helper Classes"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OK["OkHttp"]:::external
        SWAG["swagger-parser"]:::external
    end

    %% Connections
    CLI -->|"parseCommand"| CMD
    CMD -->|"initContext"| CTX
    CMD -->|"initContext"| CFG
    CTX -->|"triggerTests"| DSL
    CTX -->|"triggerTests"| GEN
    CFG -->|"triggerTests"| DSL
    CFG -->|"triggerTests"| GEN
    CTX -->|"executeFuzzTests"| FF
    CTX -->|"executeFuzzTests"| HF
    CTX -->|"executeFuzzTests"| HF2
    CTX -->|"executeFuzzTests"| SF
    CFG -->|"executeFuzzTests"| FF
    CFG -->|"executeFuzzTests"| HF
    CFG -->|"executeFuzzTests"| HF2
    CFG -->|"executeFuzzTests"| SF
    FF -->|"invokeAPI"| IO
    HF -->|"invokeAPI"| IO
    HF2 -->|"invokeAPI"| IO
    SF -->|"invokeAPI"| IO
    DSL -->|"generatePayloads"| IO
    GEN -->|"generatePayloads"| IO
    IO -->|"returnResults"| REP
    CTX -.->|"updateContract"| OAPI
    IO -->|"uses"| OK
    OAPI -->|"uses"| SWAG

    %% Utility support (dashed connections)
    UTIL ---|"supports"| CLI
    UTIL ---|"supports"| CMD
    UTIL ---|"supports"| CTX
    UTIL ---|"supports"| CFG
    UTIL ---|"supports"| DSL
    UTIL ---|"supports"| GEN
    UTIL ---|"supports"| FF
    UTIL ---|"supports"| HF
    UTIL ---|"supports"| HF2
    UTIL ---|"supports"| SF
    UTIL ---|"supports"| IO
    UTIL ---|"supports"| REP
    UTIL ---|"supports"| OAPI

    %% Styles
    classDef cli fill:#A7C7E7,stroke:#333,stroke-width:2px;
    classDef cmd fill:#BFD8B8,stroke:#333,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef fuzzer fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef generator fill:#FFE082,stroke:#333,stroke-width:2px;
    classDef http fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef report fill:#B2DFDB,stroke:#333,stroke-width:2px;
    classDef openapi fill:#FFCC80,stroke:#333,stroke-width:2px;
    classDef util fill:#E0E0E0,stroke:#333,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/endava/cats/blob/master/src/main/java/com/endava/cats/CatsMain.java"
    click CMD "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/command/"
    click CTX "https://github.com/endava/cats/blob/master/src/main/java/com/endava/cats/context/CatsGlobalContext.java"
    click CFG "https://github.com/endava/cats/blob/master/src/main/java/com/endava/cats/model/CatsConfiguration.java"
    click FF "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/fuzzer/fields/"
    click HF "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/fuzzer/headers/"
    click HF2 "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/fuzzer/http/"
    click SF "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/fuzzer/special/"
    click DSL "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/dsl/"
    click GEN "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/generator/"
    click IO "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/io/"
    click REP "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/report/"
    click OAPI "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/openapi/"
    click UTIL "https://github.com/endava/cats/tree/master/src/main/java/com/endava/cats/util/"
```
