# expediagroup/jarviz architecture

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

- Interactive diagram: https://gitdiagram.com/expediagroup/jarviz
- Repository: https://github.com/expediagroup/jarviz

## Overview

##### Project Type & Purpose
- Jarviz is a multi‐module, open‐source dependency‐analysis tool for Java bytecode.
- Purpose: scan JAR/WAR artifacts, extract method‐level coupling data (JSONL), and render it as an interactive HTML graph via a Node.js component, all orchestrated by a shell CLI.

##### File Structure
- Top‐level modules:
– jarviz-lib (Java library, Maven project)
– jarviz-graph (Node.js/TypeScript or JavaScript project, npm‐based)
– jarviz-cli (Bash/POSIX shell wrapper)
- build-config holds CI/CD and Maven settings; GitHub workflows for build, test, release.
- jarviz-lib/src contains packages for config, model, service, util, visitor → indicates a service‐oriented, visitor‐pattern–based bytecode analyzer using ASM.
- jarviz-graph/lib/client contains static HTML/JS/CSS → the front‐end graph renderer.
- jarviz-cli/jarviz is the shell script orchestrating Java and Node tools.

##### Extract Architecture Insights from README
- Three distinct components → clear separation of concerns.
- jarviz-lib uses ASM to analyze bytecode, outputs JSON Lines (.jsonl).
- jarviz-graph reads JSONL, produces a self‐contained HTML graph.
- jarviz-cli glues both pieces together via command‐line arguments and sample JSON configs (artifacts.json, filter.json).

##### Main Components & Their Interactions
A. External Inputs & Platforms
– Java runtime + Maven (for jarviz-lib)
– Node.js + npm (for jarviz-graph)
– Shell environment (for jarviz-cli)
– Artifacts to analyze (JAR/WAR files)
– JSON config files: artifacts.json, filter.json
B. Jarviz Library (jarviz-lib)
– Services: ArtifactDiscoveryService, ClassLoaderService, CouplingAnalyser
– Workflow: load artifacts → custom classloader → ASM visitor (FilteredClassVisitor, FilteredMethodVisitor) → collect MethodCoupling records → JsonUtils → write JSONL
C. Jarviz Graph Tool (jarviz-graph)
– Node.js process reads JSONL → lib/index.js → transforms data → write-to-disk → produces index.html + graph.js + CSS → uses client‐side D3/force‐layout (graph.js)
D. Jarviz CLI (jarviz-cli)
– Shell script “jarviz” parses CLI args → invokes jarviz-lib’s AnalyzeCommand (via java -cp) to emit JSONL → invokes jarviz-graph bin/index.js (via node) to produce HTML → opens or saves output
E. Outputs
– .jsonl coupling data file
– .html interactive graph

##### Architectural Patterns & Design Principles
- Modularization: each component lives in its own module (Java, Node, Shell).
- Visitor pattern in jarviz-lib (ASM visitors).
- Service locator / dependency‐injection (JarvizServiceLocator).
- Pipeline/producer‐consumer: jarviz-lib produces JSONL → jarviz-graph consumes it.
- CLI orchestration adheres to Unix philosophy (small, composable tools).
- Configuration‐driven (filter.json, artifacts.json).

##### Final Checklist
- External dependencies/platforms (Java VM, Node.js, Maven, npm).
- Configuration inputs (JSON configs, command‐line flags).
- Patterns (visitor, service‐locator, pipeline).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Platforms
    JavaPlatform["Java Runtime & Maven"]:::external
    NodePlatform["Node.js & npm"]:::external

    %% Data Artifacts
    subgraph "Data Artifacts"
        direction TB
        InputArtifacts["JAR/WAR inputs"]:::data
        JSONL["Coupling Data (.jsonl)"]:::data
        HTML["Interactive Graph (.html + assets)"]:::data
        Configs["JSON Configs"]:::data
    end

    %% CLI Orchestrator
    subgraph "CLI Orchestrator" 
        direction TB
        CLI["jarviz (shell script)"]:::shell
    end

    %% Jarviz Library (Java Module)
    subgraph "Jarviz Library (jarviz-lib)" 
        direction TB
        AnalyzeCmd["AnalyzeCommand"]:::java
        ServiceLocator["JarvizServiceLocator"]:::java
        ArtifactDiscoveryService["ArtifactDiscoveryService & MavenArtifactDiscoveryService"]:::java
        ClassLoaderService["ClassLoaderService & JarClassLoaderService"]:::java
        FilteredClassVisitor["FilteredClassVisitor"]:::java
        FilteredMethodVisitor["FilteredMethodVisitor"]:::java
        CouplingAnalyser["CouplingAnalyser"]:::java
        CouplingWriter["CouplingRecordWriter"]:::java
        ModelDefs["Model Definitions"]:::java
        JsonUtils["JsonUtils"]:::java
        FileIO["FileReadWriteUtils"]:::java
    end

    %% Jarviz Graph Tool (Node.js Module)
    subgraph "Jarviz Graph Tool (jarviz-graph)"
        direction TB
        GraphCLI["bin/index.js"]:::node
        Transformer["lib/index.js"]:::node
        DiskWriter["lib/write-to-disk.js"]:::node
        Utils["lib/utils & log"]:::node
        Client["lib/client/"]:::node
    end

    %% Connections: CLI to Java
    CLI -->|"invoke AnalyzeCommand"| AnalyzeCmd
    JavaPlatform -->|"runs"| AnalyzeCmd
    AnalyzeCmd -->|"uses ServiceLocator"| ServiceLocator
    ServiceLocator -->|"provides"| ArtifactDiscoveryService
    ServiceLocator -->|"provides"| ClassLoaderService
    ArtifactDiscoveryService -->|discover| InputArtifacts
    ClassLoaderService -->|load| InputArtifacts
    AnalyzeCmd -->|"start ASM visitor"| FilteredClassVisitor
    FilteredClassVisitor -->|calls| FilteredMethodVisitor
    FilteredMethodVisitor -->|populate| ModelDefs
    ModelDefs -->|analyzed by| CouplingAnalyser
    CouplingAnalyser -->|produce records| CouplingWriter
    CouplingWriter -->|write via JsonUtils & FileIO| JSONL

    %% CLI to Node
    CLI -->|"reads configs"| Configs
    CLI -->|"invoke Node generator"| GraphCLI
    NodePlatform -->|"runs"| GraphCLI
    GraphCLI -->|read| JSONL
    GraphCLI -->|transform| Transformer
    Transformer -->|utilize| Utils
    Transformer -->|write| DiskWriter
    DiskWriter -->|output| HTML
    Client -->|render with D3| HTML

    %% Click Events
    click CLI "https://github.com/expediagroup/jarviz/tree/master/jarviz-cli/jarviz"
    click AnalyzeCmd "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/AnalyzeCommand.java"
    click ServiceLocator "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/service/JarvizServiceLocator.java"
    click ArtifactDiscoveryService "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/service/ArtifactDiscoveryService.java"
    click ClassLoaderService "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/service/ClassLoaderService.java"
    click FilteredClassVisitor "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/visitor/FilteredClassVisitor.java"
    click FilteredMethodVisitor "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/visitor/FilteredMethodVisitor.java"
    click CouplingAnalyser "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/service/CouplingAnalyser.java"
    click CouplingWriter "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/service/CouplingRecordWriter.java"
    click ModelDefs "https://github.com/expediagroup/jarviz/tree/master/jarviz-lib/src/main/java/com/vrbo/jarviz/model/"
    click JsonUtils "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/util/JsonUtils.java"
    click FileIO "https://github.com/expediagroup/jarviz/blob/master/jarviz-lib/src/main/java/com/vrbo/jarviz/util/FileReadWriteUtils.java"
    click GraphCLI "https://github.com/expediagroup/jarviz/blob/master/jarviz-graph/bin/index.js"
    click Transformer "https://github.com/expediagroup/jarviz/blob/master/jarviz-graph/lib/index.js"
    click DiskWriter "https://github.com/expediagroup/jarviz/blob/master/jarviz-graph/lib/write-to-disk.js"
    click Utils "https://github.com/expediagroup/jarviz/blob/master/jarviz-graph/lib/utils.js"
    click Client "https://github.com/expediagroup/jarviz/tree/master/jarviz-graph/lib/client/"

    %% Styles
    classDef java fill:#cfe2f3,stroke:#6c8ebf,color:#000
    classDef node fill:#d9ead3,stroke:#6aa84f,color:#000
    classDef shell fill:#fce5cd,stroke:#e69138,color:#000
    classDef data fill:#eeeeee,stroke:#aaaaaa,color:#000
    classDef external fill:#ece0f8,stroke:#a36acf,color:#000
```
