# saeg/jaguar2 architecture

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

- Interactive diagram: https://gitdiagram.com/saeg/jaguar2
- Repository: https://github.com/saeg/jaguar2

## Overview

##### Main components and modules
- API Module (jaguar2-api): This defines the overall public interfaces such as Spectrum-related interfaces (e.g., IBundleSpectrum, IClassSpectrum, ICodeSpectrum, etc.), as well as the heuristic contract (Heuristic, SpectrumEval). It sets the contract for how coverage controllers and spectrum exporters should behave.
- Core Module (jaguar2-core): Contains the core computation logic, including the main Jaguar engine and different heuristics (DRT, Jaccard, Kulczynski2, McCon, Minus, Ochiai, Op, Tarantula, Wong3, Zoltar). This is the processing heart of the system.
- Commons Module (jaguar2-commons): Offers utility classes and common functionality that is shared among the other modules.
- Build Module (jaguar2-build): Provides infrastructure to handle the build aspects specific to Jaguar2.
- Exporters Modules (jaguar2-exporters): Contains different submodules (CSV and XML exporters) that implement the SpectrumExporter SPI to deliver coverage data in various formats.
- Providers Modules (jaguar2-providers): Provides multiple coverage provider implementations (such as the Ba-Dua and JaCoCo providers) that plug into the system through the SPI mechanism. Note the use of META-INF/services files that help with dynamic discovery.
- Integration Modules (jaguar2-junit4, jaguar2-examples): Supply integration examples and JUnit-based test runners that demonstrate how Jaguar2 can be consumed in a testing context.
- Tests and Validations (jaguar2-tests & jaguar2-validations): Organized tests validating the functionality across API, core, commons, and integration points.
- CI/CD and Build System: The presence of Maven wrapper files, GitHub Actions configuration (in .github/workflows), and various pom.xml files in each module indicates an emphasis on automated builds and continuous integration.

##### Relationships and interactions
- The API module provides the interfaces and contracts that the other components adhere to.
- The Core module implements the logic required to perform spectrum evaluations using various heuristics. It interacts with the API by invoking defined interfaces.
- The Providers modules implement the CoverageController and SpectrumExporter interfaces (using Java SPI via the META-INF/services) to integrate external coverage tools, making them pluggable.
- The Exporters modules (CSV and XML) read the processed spectrum data from the core and export it in different formats.
- The Commons module acts as a support library which other modules (like Core and Providers) rely on.
- The integration modules (Junit4 and examples) demonstrate how the system is used in real testing scenarios, utilizing the API, Core, and installed providers.
- The Tests modules ensure that each component is correctly validating its functionality, acting as both unit and integration tests.
- The Build and CI/CD configuration ensures that the entire system is seamlessly built, tested, and deployed.

##### Architectural patterns and design principles
- Modular / Multi-Module Architecture: Each separate concern is isolated in its own Maven module, which makes for loose coupling and clearer separation of concerns.
- Service Provider Interface (SPI) Pattern: The use of META-INF/services for components like SpectrumExporter and CoverageController illustrates the plug-in architecture that allows for third-party extension.
- Integration with External Tools: There is clear support for integrating with external coverage tools (e.g., JaCoCo) and testing frameworks (JUnit integrated modules), following standard integration practices.
- Dependency Injection / Inversion of Control: Though not explicitly stated, the SPI mechanism implies an inversion of control by allowing providers to be discovered and used dynamically.

##### Final recommendations for the principal software engineer
- Be explicit in showing the flow: from coverage data input (via tests) to core evaluation, then dispatching to exporters and integration with external tools.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Engine Group
    subgraph "Core Engine"
        API["API Module (jaguar2-api)"]:::core
        CORE["Core Module (Jaguar2 Core)"]:::core
        COMMONS["Commons Module (jaguar2-commons)"]:::commons
    end

    %% Extensions Group
    subgraph "Extensions"
        EX_CSV["CSV Exporter"]:::exporter
        EX_XML["XML Exporter"]:::exporter
        PROVIDER_BA["Ba-Dua Provider"]:::provider
        PROVIDER_JACOCO["JaCoCo Provider"]:::provider
    end

    %% Integration & Testing Group
    subgraph "Integration & Testing"
        JUNIT["JUnit Integration"]:::integration
        EXAMPLES["Examples"]:::integration
        TESTS["Tests"]:::test
        VALIDATIONS["Validations"]:::test
    end

    %% Build & CI Group
    subgraph "Build & CI"
        BUILD["Build Module (jaguar2-build)"]:::build
        MAVEN["Maven Wrapper"]:::ci
        GITHUB["CI (GitHub Actions)"]:::ci
    end

    %% Relationships between Core Engine components
    API -->|"implements"| CORE
    COMMONS -->|"supports"| API
    COMMONS -->|"supports"| CORE

    %% Relationships between Core Engine and Extensions
    CORE -->|"data_to_export"| EX_CSV
    CORE -->|"data_to_export"| EX_XML
    CORE <-->|"SPI_interaction"| PROVIDER_BA
    CORE <-->|"SPI_interaction"| PROVIDER_JACOCO
    COMMONS -->|"supports"| EX_CSV
    COMMONS -->|"supports"| PROVIDER_BA

    %% Relationships between Core Engine and Integration
    JUNIT -->|"uses"| API
    JUNIT -->|"uses"| CORE
    EXAMPLES -->|"demonstrates_usage_of"| API
    EXAMPLES -->|"demonstrates_usage_of"| CORE
    TESTS -->|"validate"| API
    TESTS -->|"validate"| CORE
    VALIDATIONS -->|"validate"| CORE
    COMMONS -->|"supports"| JUNIT

    %% Relationships in Build & CI
    BUILD -->|"orchestrates"| MAVEN
    BUILD -->|"orchestrates"| GITHUB

    %% Click Events
    click API "https://github.com/saeg/jaguar2/tree/master/jaguar2-api"
    click CORE "https://github.com/saeg/jaguar2/tree/master/jaguar2-core"
    click COMMONS "https://github.com/saeg/jaguar2/tree/master/jaguar2-commons"
    click BUILD "https://github.com/saeg/jaguar2/tree/master/jaguar2-build"
    click EX_CSV "https://github.com/saeg/jaguar2/tree/master/jaguar2-exporters/jaguar2-csv-exporter"
    click EX_XML "https://github.com/saeg/jaguar2/tree/master/jaguar2-exporters/jaguar2-xml-exporter"
    click PROVIDER_BA "https://github.com/saeg/jaguar2/tree/master/jaguar2-providers/jaguar2-ba-dua-provider"
    click PROVIDER_JACOCO "https://github.com/saeg/jaguar2/tree/master/jaguar2-providers/jaguar2-jacoco-provider"
    click JUNIT "https://github.com/saeg/jaguar2/tree/master/jaguar2-junit4"
    click EXAMPLES "https://github.com/saeg/jaguar2/tree/master/jaguar2-examples"
    click TESTS "https://github.com/saeg/jaguar2/tree/master/jaguar2-tests"
    click VALIDATIONS "https://github.com/saeg/jaguar2/tree/master/jaguar2-validations"
    click MAVEN "https://github.com/saeg/jaguar2/blob/master/.mvn"
    click GITHUB "https://github.com/saeg/jaguar2/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef commons fill:#cfe,stroke:#333,stroke-width:2px;
    classDef exporter fill:#fed,stroke:#333,stroke-width:2px;
    classDef provider fill:#def,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffc,stroke:#333,stroke-width:2px;
    classDef test fill:#dff,stroke:#333,stroke-width:2px;
    classDef build fill:#cdf,stroke:#333,stroke-width:2px;
    classDef ci fill:#fcf,stroke:#333,stroke-width:2px;
```
