# alibaba/jvm-sandbox-repeater architecture

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

- Interactive diagram: https://gitdiagram.com/alibaba/jvm-sandbox-repeater
- Repository: https://github.com/alibaba/jvm-sandbox-repeater

## Overview

##### Project Type & Purpose
- This is a multi-module Maven project implementing a full-stack, plugin-based “record & replay” solution for JVM applications.
- On the “agent” side it builds on Alibaba’s JVM-Sandbox to instrument your target application, record ingress calls (HTTP/Dubbo/Java), capture sub-calls, serialize them via Hessian, and optionally replay/mock them.
- On the “server” side it delivers a Spring‐Boot based console (with Velocity templates and a JS front end) for managing modules, browsing recorded flows, and triggering replays, backed by a relational database.

##### High-Level Directory Structure
- bin/ – shell‐scripts to bootstrap/healthcheck/package the agent.
- hessian-lite/ – in-house Hessian serialization library used by the agent for payload marshalling.
- repeater-module/ & repeater-plugin-api/ & repeater-plugin-core/ – the core agent components:
– repeater-module: JVM-Sandbox agent plug-in, life-cycle & classloader logic.
– plugin-api: SPI interfaces (InvokePlugin, Repeater, MockStrategy, etc.).
– plugin-core: event listener, tracing, caching, dispatch & serializer adapters.
- repeater-plugins/ – a collection of concrete plugin implementations (HTTP, Dubbo, MyBatis, Redis, etc.).
- repeater-client/ – a small client library (SpringContextAware, HTTP util) for calling console APIs from code.
- repeater-aide/ – offline comparison/diff library for analyzing recorded flows.
- repeater-console/ – the console application, split into:
– repeater-console-common (shared DTOs, exceptions, request/response objects)
– repeater-console-dal (DAO, JPA/MyBatis models & repositories)
– repeater-console-service (business services, converters, caching, Jackson config)
– repeater-console-start (Spring Boot app, controllers, Velocity UI, static assets, front-end JS)
- docs/, LICENSE, pom.xml, Readme.md, etc.

##### Key Insights from README
- Agent records “entranceInvocation” + “subInvocations” using JVM-Sandbox hooks (BEFORE/RETURN/THROW) and TTL for cross-thread tracing.
- Recorded data is serialized (Hessian/JSON) and can be sent to a server or kept in standalone mode.
- Replay is driven by an async EventBus, FlowDispatcher & Repeater SPI; supports mock (short-circuit) or real calls.
- Console UI for browsing, filtering, replaying flows, built as a Spring Boot application with Velocity and front-end assets.

a. Main Components
1. Application Under Test (JVM).
2. JVM-Sandbox Agent:
- Repeater-Module (Sandbox plugin loader & advices)
- Plugin-Core (EventListener → Tracer → Record/Replay Cache → FlowDispatcher → Serializer)
- Plugin-API (SPI definitions)
- Plugin Implementations (http, dubbo, mybatis, etc.)
3. Hessian-Lite Library (payload serialization).
4. Network/Transport (HTTP via HttpUtil or standalone file store).
5. Repeater-Console Server:
- API Controllers (REST + Velocity controllers)
- Service Layer (business logic, conversion, caching)
- DAL Layer (DAO, repositories, DB schema)
- Front-end (Velocity templates + static JS/CSS/ACE editor plugin)
6. Relational Database.
7. Optional Repeater-Client (embedded in other apps to call console APIs).
8. Repeater-Aide (offline diffing tool).

b. Relationships & Data Flow
1. Agent intercepts calls → builds Invocation objects → serializes → sends HTTP POST to Console API (or writes to local storage).
2. Console API receives & persists into DB via DAL → Service processes & caches → UI queries Service → templates/JS display.
3. User clicks “Replay” in UI → UI calls REST Replay endpoint → Service publishes ReplayEvent on EventBus → plugin-core in agent (subscribed via HTTP client) picks it up → replays calls in the target app.
4. MockStrategy SPI may short-circuit sub-calls by throwReturnImmediately via Sandbox.

c. Architectural Patterns & Principles
- Plugin SPI + SPI Loader (loose coupling, extensibility)
- EventBus for intra-agent async dispatch
- Tracer + TTL for context propagation across threads
- Layered architecture on server: Controllers → Services → DAL → DB
- Standalone vs. client/server modes

d. Key Technologies
- JVM-Sandbox (Java agent, byte-code instrumentation)
- Spring Boot + Velocity + jQuery/ACE for console UI
- Maven multi-module, SPI, ServiceLoader
- Hessian for binary serialization (hessian-lite)
- Relational DB (via JPA/MyBatis)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application under test and agent
    APT["Application Under Test (JVM)"]:::jvm
    subgraph "Agent Side"
        direction TB
        BIN["bin/"]:::agent
        HESS["hessian-lite/"]:::agent
        subgraph "Agent Modules"
            direction TB
            MOD["repeater-module"]:::agent
            API["repeater-plugin-api"]:::pluginapi
            CORE["repeater-plugin-core"]:::plugincore
            IMPL["repeater-plugins"]:::pluginimpl
        end
    end

    %% Transport
    APT -->|"instrument & intercept"| MOD
    MOD -->|"uses SPI"| API
    API --> CORE
    CORE --> IMPL
    HESS --> CORE
    BIN --> MOD

    CORE -->|"serialize via Hessian"| HESS
    CORE -->|"HTTP POST /api/record"| NET["Network/Transport (HTTP)"]:::network

    %% Console Server
    subgraph "Console Server"
        direction TB
        subgraph "Front-end"
            direction TB
            UI["Velocity Templates & JS"]:::frontend
        end
        subgraph "Controllers"
            direction TB
            CTRL["REST & Page Controllers"]:::controller
        end
        subgraph "Service Layer"
            direction TB
            SVC["repeater-console-service"]:::service
        end
        subgraph "DAL Layer"
            direction TB
            DAL["repeater-console-dal"]:::dal
        end
    end

    NET -->|"POST /api/record"| CTRL
    CTRL -->|"calls"| SVC
    SVC -->|"persists via DAO"| DAL
    DAL -->|"writes"| DB["Relational Database"]:::db

    UI -->|"user actions"| CTRL
    CTRL -->|"ReplayEvent"| SVC
    SVC -->|"HTTP call to agent"| NET

    %% Optional Components
    CLIENT["repeater-client"]:::util
    AIDE["repeater-aide"]:::util
    CLIENT -->|"calls Console APIs"| CTRL
    AIDE -->|"offline diff"| SVC

    %% Click Events
    click BIN "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/bin/"
    click HESS "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/hessian-lite/"
    click MOD "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-module/"
    click API "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-plugin-api/"
    click CORE "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-plugin-core/"
    click IMPL "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-plugins/"
    click CLIENT "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-client/"
    click AIDE "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-aide/"
    click SVC "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-console/repeater-console-service/"
    click DAL "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-console/repeater-console-dal/"
    click CTRL "https://github.com/alibaba/jvm-sandbox-repeater/tree/master/repeater-console/repeater-console-start/"

    %% Styles
    classDef jvm fill:#f9f,stroke:#333,stroke-width:1px
    classDef agent fill:#cce5ff,stroke:#2a4d69,stroke-width:1px
    classDef pluginapi fill:#e0e0e0,stroke:#6c757d,stroke-width:1px,stroke-dasharray: 5 5
    classDef plugincore fill:#b3d9ff,stroke:#00509e,stroke-width:1px
    classDef pluginimpl fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef frontend fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef controller fill:#cfe2ff,stroke:#0b61a4,stroke-width:1px
    classDef service fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef dal fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef db fill:#d1d1d1,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
    classDef util fill:#f0f0f0,stroke:#333,stroke-width:1px
```
