# vashishthask/mocktail architecture

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

- Interactive diagram: https://gitdiagram.com/vashishthask/mocktail
- Repository: https://github.com/vashishthask/mocktail

## Overview

##### Main Components
- Core Library (mocktail-core): This is the heart of the project. It contains the Java packages for configuration (MocktailConfig, MocktailMode), metadata management (classes under “metadata” in various subpackages), XML processing (using XStream and related readers), and repository handling (for saving and reading cached responses from disk).
- Maven Plugin (mocktail-maven-plugin): This module integrates with Maven builds via a plugin interface. It orchestrates the usage of the core library and coordinates with the AspectJ Maven Plugin to generate AOP advice.
- Aspect Generation (AspectJ Integration): The project leverages AspectJ (using aspectjrt, aspectj-maven-plugin, and generated aspects) to weave AOP proxies at compile time. These aspects intercept designated method calls and decide if to execute the original logic or return a cached response based on the recording mode.
- Configuration Files:
– mocktail.xml (in test resources) tells the system which methods (and in which classes) should be intercepted for recording and playback.
– Maven POM files and property files (e.g., mocktailconfig.properties) configure the runtime behavior and build parameters.
- Sample Applications (mocktail-samples): These modules (e.g. for database, webservice, Spring Boot REST API) illustrate real-world use cases. Each sample shows how Mocktail integrates with different technical stacks (JDBC, ORM, Axis2, CXF, Spring Boot etc.) and how tests use the “MethodMocktail” wrapper to trigger recording and playback functionality.

##### Relationships and Data Flow
- At build time, the Maven build system uses the mocktail-maven-plugin and aspectj-maven-plugin to generate AOP aspects based on the configuration provided in mocktail.xml.
- During test execution, a test method (using JUnit, Cucumber, etc.) instantiates a MethodMocktail object. When the test calls a method that has been designated for recording (e.g., a database or REST call), the corresponding AOP proxy intercepts the call.
- The proxy checks for an existing cached response in the repository (using DiskObjectRepository, YamlDiskRepository, etc.). If a recording is present (and the mode is “recording”), it returns the cached response; if not (or if the mode is “recording_new”), it proceeds to execute the method, caches the response on disk, and then returns it.
– From Test Method → MethodMocktail (test context)
– From MethodMocktail → Intercepted method call (AOP proxy from generated aspects)
– From the proxy → Disk repository lookup vs. method execution
– Returning response from cache or after execution back to the test method.
- Interaction between the Maven Plugin and AspectJ’s aspect generation process.

##### Architectural Patterns & Technologies
- AOP (Aspect-Oriented Programming): Emphasize that the system relies on dynamically generated proxies (via AspectJ) to “wrap” the selected method calls.
- Record and Playback Pattern: Illustrate how initial method invocation records responses on disk, and subsequent calls retrieve the recorded responses, thus decoupling tests from real-world external dependencies.
- Modularization: The separation into mocktail-core, mocktail-maven-plugin, and various sample modules shows a clear separation of concerns.
- Usage of Maven for dependency and build management, including the integration of plugins that contribute to the overall build and runtime behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Time Subgraph
    subgraph "Build Time"
        A("Maven Plugin\n(mocktail-maven-plugin)"):::plugin
        B("Configuration File\n(mocktail.xml)"):::config
        A --> B
    end

    %% Core Library Subgraph
    subgraph "Core Library\n(mocktail-core)"
        DT1("MocktailConfig.java"):::core
        DT2("MocktailMode.java"):::core
        D_meta("Metadata Management"):::core
        D_xml("XML Processing"):::xml
        D_repo1("Disk Repository"):::repo
        D_repo2("YAML Repository"):::repo
        D_aspect("Aspect Generation\n(MocktailAspectsCreator)"):::aspect
        %% Grouping connections within Core (logical grouping)
        DT1 --- DT2
        DT2 --- D_meta
    end

    %% Build time to Core Integration
    B -->|"generateAspect"| D_aspect

    %% Runtime Flow Subgraph
    subgraph "Runtime Flow"
        J("Sample Applications\n(mocktail-samples)"):::sample
        E("Test Method Invocation"):::runtime
        F("MethodMocktail"):::runtime
        G("AOP Proxy\n(Generated Aspect)"):::aspect
        H("Original Method Execution"):::runtime
        I("Response to Test Method"):::runtime
        J --> E
        E --> F
        D_meta --> F
        F --> G
        %% Aspect usage from build time
        D_aspect -->|"aspectInvoke"| G
        %% Repository cache checks
        G -->|"CacheCheck"| D_repo1
        G -->|"CacheCheckYaml"| D_repo2
        %% When cache miss, execution path
        G -->|"NoCache"| H
        H -->|"RecordResponse"| D_repo1
        D_repo1 -->|"ReturnCached"| G
        D_repo2 -->|"ReturnCached"| G
        G --> I
    end

    %% Click Events
    click A "https://github.com/vashishthask/mocktail/tree/master/mocktail-maven-plugin/"
    click DT1 "https://github.com/vashishthask/mocktail/blob/master/mocktail-core/src/main/java/in/malonus/mocktail/MocktailConfig.java"
    click DT2 "https://github.com/vashishthask/mocktail/blob/master/mocktail-core/src/main/java/in/malonus/mocktail/MocktailMode.java"
    click D_meta "https://github.com/vashishthask/mocktail/tree/master/mocktail-core/src/main/java/in/malonus/mocktail/metadata/"
    click D_xml "https://github.com/vashishthask/mocktail/tree/master/mocktail-core/src/main/java/in/malonus/mocktail/metadata/xml/reader"
    click D_repo1 "https://github.com/vashishthask/mocktail/blob/master/mocktail-core/src/main/java/in/malonus/mocktail/repository/DiskObjectRepository.java"
    click D_repo2 "https://github.com/vashishthask/mocktail/blob/master/mocktail-core/src/main/java/in/malonus/mocktail/repository/YamlDiskRepository.java"
    click D_aspect "https://github.com/vashishthask/mocktail/tree/master/mocktail-core/src/main/java/in/malonus/mocktail/metadata/aj/creator"
    click J "https://github.com/vashishthask/mocktail/tree/master/mocktail-samples/"

    %% Styles
    classDef plugin fill:#cfc,stroke:#333,stroke-width:2px;
    classDef config fill:#fcf,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef xml fill:#eef,stroke:#333,stroke-width:2px;
    classDef repo fill:#ddf,stroke:#333,stroke-width:2px;
    classDef aspect fill:#fdd,stroke:#333,stroke-width:2px;
    classDef runtime fill:#ffd,stroke:#333,stroke-width:2px;
    classDef sample fill:#f9c,stroke:#333,stroke-width:2px;
```
