# research-iobserve/distributed-jpetstore-experiment architecture

> Architecture diagram of the GitHub repository research-iobserve/distributed-jpetstore-experiment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/research-iobserve/distributed-jpetstore-experiment
- Repository: https://github.com/research-iobserve/distributed-jpetstore-experiment

## Overview

##### Project type and purpose
- This is an experiment‐orchestration framework for a microservices version of JPetStore.
- It uses shell scripts to launch JPetStore services (account, catalog, order, frontend) in Docker or Kubernetes, runs a workload generator (Selenium), collects monitoring data with Kieker or iObserve, and stores results.

##### File structure
- Top‐level scripts:
- execute-jpetstore-with-workload.sh
- execute-observation.sh
- execute-integrated-experiment.sh
- execute-integrated-kube-experiment.sh
- helper scripts (common-functions.sh, show-log-info.sh, tag-and-push-to-repository.sh, etc.)
- Configuration:
- config.template → user‐filled config with $BASE_DIR, TOOLS_DIR, DATA_DIR, RESULT_DIR, DOCKER_REPO, LOGGER, JPETSTORE, WORKLOAD_RUNNER, WEB_DRIVER, COLLECTOR
- jpetstore-configuration.yaml
- Deployment directories:
- kubernetes/ and kub2/ → Kubernetes YAMLs for the four JPetStore services + services + optional USA geography
- Workload definitions:
- workloads/*.yaml → behavior/workload scenarios for Selenium-based runner
- Documentation:
- doc/*.md → setup instructions for Docker registry, Kubernetes, pushing images
- Output directories:
- results/ → alarms.txt, warnings.txt

##### Key insights from the README
- The scripts orchestrate:
- Stopping/removing old containers
- Starting JPetStore microservices on a bridged Docker network or on K8s
- Optionally starting the Selenium workload runner
- Optionally starting a monitoring collector (Kieker or iObserve) that sends logs to LOGGER host
- Dependencies: JPetStore-6 codebase, selenium-workloads, iobserve-analysis, Kieker distributable, Docker engine, Kubernetes cluster

##### Main components
a. Orchestration layer (shell‐script runner)
– Reads config
– Invokes Docker CLI or kubectl
– Starts/stops containers or pods
– Launches workload runner
– Launches collector
b. JPetStore microservices
– account service container/pod
– catalog service container/pod
– order service container/pod
– frontend service container/pod (exposes HTTP on :8080)
c. Network
– Docker bridged network or K8s cluster network
– Kubernetes Service objects routing to pods
d. Workload runner
– Selenium‐based Java app reading workloads/*.yaml
– Drives HTTP traffic against frontend
e. Monitoring collector
– Kieker or iObserve collector
– Receives tracing/monitoring events from instrumented services
– Sends logs to LOGGER host (could be local or remote)
f. Storage
– DATA_DIR for raw logs
– RESULT_DIR for analysis output
g. External systems
– Docker registry (optional, for pushing/pulling images)
– Kubernetes API server (when using k8s)

##### Relationships and data flows
- Orchestrator → Docker/K8s API: creates JPetStore service instances
- JPetStore services ↔ each other (account ↔ order ↔ catalog, etc.)
- Frontend ← HTTP ← Workload runner
- Services → monitoring events → Collector → LOGGER host → files in DATA_DIR
- After experiment: Collector/analysis tools → RESULT_DIR
- Images ←→ Docker registry (tag‐and‐push)

##### Architectural patterns & principles
- Microservices for core JPetStore domains
- Infrastructure‐as‐code: Kubernetes YAMLs, shell scripts as automation
- Separation of concerns: orchestration vs. workload generation vs. monitoring
- Pluggable monitoring backends (Kieker vs. iObserve)
- Config‐driven experiments (via config.template)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        EJ1["execute-jpetstore-with-workload.sh"]:::orchestration
        EO["execute-observation.sh"]:::orchestration
        EIE["execute-integrated-experiment.sh"]:::orchestration
        EIKE["execute-integrated-kube-experiment.sh"]:::orchestration
        ESJ["execute-single-jpetstore-test-experiment.sh"]:::orchestration
        CF["common-functions.sh"]:::orchestration
        SL["show-log-info.sh"]:::orchestration
        TP["tag-and-push-to-repository.sh"]:::orchestration
        CT["config.template"]:::orchestration
        JC["jpetstore-configuration.yaml"]:::orchestration
    end

    %% Compute Layer
    subgraph "Compute Layer"
        direction TB
        DN["Docker Network"]:::external
        K8SAPI["Kubernetes API Server"]:::external

        subgraph "Docker Containers"
            direction TB
            ACC["Account Service"]:::microservice
            CAT["Catalog Service"]:::microservice
            ORD["Order Service"]:::microservice
            FE["Frontend Service (:8080)"]:::microservice
        end

        subgraph "Kubernetes Manifests"
            direction TB
            KA["account-deployment.yaml"]:::microservice
            KC["catalog-deployment.yaml"]:::microservice
            KO["order-deployment.yaml"]:::microservice
            KF["frontend-deployment.yaml"]:::microservice
            KSVC["frontend-service.yaml"]:::microservice
            KJP["jpetstore.yaml"]:::microservice
            KUSA["usa.yaml"]:::microservice
            KA2["kub2/account-deployment.yaml"]:::microservice
            KC2["kub2/catalog-deployment.yaml"]:::microservice
            KO2["kub2/order-deployment.yaml"]:::microservice
            KF2["kub2/frontend-deployment.yaml"]:::microservice
            KSVC2["kub2/frontend-service.yaml"]:::microservice
        end
    end

    %% Workload Layer
    subgraph "Workload Generation"
        direction TB
        WR["Selenium Workload Runner"]:::workload
        WB1["account-browser-catlover.yaml"]:::workload
        WB2["account-intense.yaml"]:::workload
        WB3["account.yaml"]:::workload
        WB4["cat-lover.yaml"]:::workload
        WB5["new.yaml"]:::workload
        WB6["test.yaml"]:::workload
    end

    %% Monitoring Layer
    subgraph "Monitoring Collector"
        direction TB
        MC["Kieker/iObserve Collector"]:::monitoring
        L1["log4j.cfg"]:::monitoring
        L2["log4j-debug.cfg"]:::monitoring
    end

    %% Storage Layer
    subgraph "Storage"
        direction TB
        DD["DATA_DIR (raw logs)"]:::monitoring
        RD["RESULT_DIR (analysis output)"]:::monitoring
        AFT["results/alarms.txt"]:::monitoring
        WFT["results/warnings.txt"]:::monitoring
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DR["Docker Registry"]:::external
    end

    %% Connections
    CT -->|reads config| EJ1
    JC --> EJ1

    EJ1 -->|docker CLI| DN
    EJ1 -->|kubectl apply| K8SAPI

    DN --> ACC
    DN --> CAT
    DN --> ORD
    DN --> FE

    K8SAPI --> KA
    K8SAPI --> KC
    K8SAPI --> KO
    K8SAPI --> KF
    K8SAPI --> KSVC
    K8SAPI --> KJP
    K8SAPI --> KUSA
    K8SAPI --> KA2
    K8SAPI --> KC2
    K8SAPI --> KO2
    K8SAPI --> KF2
    K8SAPI --> KSVC2

    WR -->|HTTP| FE

    ACC -->|monitor events| MC
    CAT -->|monitor events| MC
    ORD -->|monitor events| MC
    FE -->|monitor events| MC

    MC -->|write logs| DD
    MC -->|post-analysis| RD

    RD --> AFT
    RD --> WFT

    EJ1 -->|push images| DR
    TP --> DR

    %% Click Events
    click EJ1 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/execute-jpetstore-with-workload.sh"
    click EO "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/execute-observation.sh"
    click EIE "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/execute-integrated-experiment.sh"
    click EIKE "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/execute-integrated-kube-experiment.sh"
    click ESJ "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/execute-single-jpetstore-test-experiment.sh"
    click CF "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/common-functions.sh"
    click SL "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/show-log-info.sh"
    click TP "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/tag-and-push-to-repository.sh"
    click CT "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/config.template"
    click JC "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/jpetstore-configuration.yaml"
    click KA "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/account-deployment.yaml"
    click KC "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/catalog-deployment.yaml"
    click KO "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/order-deployment.yaml"
    click KF "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/frontend-deployment.yaml"
    click KSVC "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/frontend-service.yaml"
    click KJP "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/jpetstore.yaml"
    click KUSA "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kubernetes/usa.yaml"
    click KA2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kub2/account-deployment.yaml"
    click KC2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kub2/catalog-deployment.yaml"
    click KO2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kub2/order-deployment.yaml"
    click KF2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kub2/frontend-deployment.yaml"
    click KSVC2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/kub2/frontend-service.yaml"
    click WB1 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/account-browser-catlover.yaml"
    click WB2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/account-intense.yaml"
    click WB3 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/account.yaml"
    click WB4 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/cat-lover.yaml"
    click WB5 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/new.yaml"
    click WB6 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/workloads/test.yaml"
    click L1 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/log4j.cfg"
    click L2 "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/log4j-debug.cfg"
    click AFT "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/results/alarms.txt"
    click WFT "https://github.com/research-iobserve/distributed-jpetstore-experiment/blob/master/results/warnings.txt"

    %% Styles
    classDef orchestration fill:#a7f0ba,stroke:#0f8f41,color:#000
    classDef microservice fill:#b3d1f2,stroke:#1a4f8a,color:#000
    classDef workload fill:#fce38a,stroke:#f9a825,color:#000
    classDef monitoring fill:#f8b195,stroke:#c94c4c,color:#000
    classDef external fill:#d3d3d3,stroke:#7a7a7a,color:#000
```
