# schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool architecture

> Architecture diagram of the GitHub repository schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool
- Repository: https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool

## Overview

##### Main Components

- Polarion Integration:
– The extension is designed to be deployed inside Polarion by copying a generated jar file to the Polarion instance.
– It makes use of Polarion’s configuration (e.g., project administration pages, sidebar extensions, and REST API interactions).
– Integration points include the addition of extra document properties pages, nodes in Polarion’s navigation tree, and administration configuration.

- Backend (Java/Maven Extension):
– Core business logic implemented in Java.
– Organized in packages such as ch.sbb.polarion.extension.diff_tool with submodules for diffing (fields, work items, collections), merging, and document copying.
– Contains controllers for REST endpoints (under …/rest/controller) and Velocity context integration for calling diff functions from templates.
– Includes service layers that perform diffing computations, merging, PDF conversion, and handling of work items (with further subdivisions into “service”, “handler”, “cleaners”, “util”, etc.).
– Supporting extensions such as web resources (plugin.xml, web.xml, velocity scripts) are located under src/main/resources.

- Frontend / UI Application:
– Located in the “ui” directory, which contains a modern JavaScript-based application.
– This component is responsible for presenting the diff and merge interfaces (diff views, merge buttons, configuration, and listing components) and interacts with the backend REST API endpoints.
– Likely built with Next.js/React, as suggested by next.config.mjs, package.json, and directory structure under ui/src.

- External Dependencies and Integration Points:
– PDF-Exporter integration (mentioned in the README, with compatibility details).
– Interaction with Polarion’s REST API for data retrieval and submission.
– Usage of Maven for build and deployment automation (Maven workflows, pom.xml, maven configuration files).

##### Visualizing Relationships and Data Flows

- The Frontend makes AJAX (REST) calls to the Backend REST API endpoints (controllers) to request diffing data, merge operations, and configuration data.
- The Backend processes these REST calls using various service layers that handle the core diff/merge logic.
- Some backend endpoints might also be called by Polarion’s UI through Velocity Templates, with functions like diffText and diffHtml provided via a Velocity context variable ($diffTool).
- The extension itself is integrated into the Polarion ecosystem. When the extension is installed (by copying the jar to the <polarion_home>/... directory), it “plugs in” to features such as extra document property panes and navigation topics. Data flows back and forth between the Polarion instance and the extension’s backend.
- The overall system uses Maven for building, testing (unit tests under src/test), and packaging the extension as well as automation via GitHub workflows (in .github/workflows).

##### Architectural Patterns and Design Principles

- Modular separation: The project is separated into distinct modules – a backend Java module (organized by functionality: controllers, models, services, utilities, etc.) and a standalone UI module.
- MVC / REST patterns: The backend uses REST controllers (and also servlet controllers for UI forms) to separate data processing from view rendering. The UI acts as a consuming client of these REST services.
- Plugin/Extension architecture: The project is designed to be “plugged” into an existing system (Polarion) with clear boundaries and prescribed integration points (configuration instructions provided in the README).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External System
    Polarion["Polarion ALM System"]:::external

    %% Diff Tool Extension subgraph
    subgraph "Polarion Diff Tool Extension"
        direction TB
        %% Plugin Resources
        PluginConfig["Plugin Config (plugin.xml)"]:::backend
        AdminPages["Admin Web Pages"]:::backend
        PropPages["Document Property Pages"]:::backend

        %% Backend Application subgraph
        subgraph "Backend Java/Maven Extension"
            direction TB
            RestControllers["REST API Controllers"]:::backend
            ServiceLayers["Service Layers (Diff/Merge/PDF)"]:::backend
            Utilities["Utilities"]:::backend
            Velocity["Velocity Integration"]:::backend
        end

        %% Frontend UI subgraph
        subgraph "Frontend UI Application"
            direction TB
            UIDiff["Document Diff & Merge UI"]:::frontend
        end
    end

    %% Build and CI/CD subgraph
    subgraph "Build and CI/CD Integration"
        direction TB
        Maven["Maven Build System"]:::build
        GitHub["GitHub Workflows"]:::build
    end

    %% Relationships between components

    %% Polarion integration with plugin resources
    Polarion -->|"loads"| PluginConfig
    Polarion -->|"displays"| AdminPages
    Polarion -->|"displays"| PropPages

    %% Frontend making AJAX calls to backend REST API
    UIDiff -->|"AJAX_diff/merge_request"| RestControllers

    %% REST processing in backend
    RestControllers -->|"delegates_to"| ServiceLayers
    ServiceLayers -->|"utilizes"| Utilities

    %% Velocity integration handling special diff calls via templates
    Polarion -->|"Velocity_template_calls"| Velocity

    %% Build system automates extension packaging
    Maven -->|"builds_extension"| PluginConfig
    Maven -->|"builds_extension"| RestControllers
    Maven -->|"builds_extension"| ServiceLayers
    Maven -->|"builds_extension"| Utilities
    Maven -->|"builds_extension"| Velocity
    GitHub -->|"CI/CD_automation"| Maven

    %% Styling
    classDef frontend fill:#a8eaff,stroke:#333,stroke-width:2px,rx:5,ry:5;
    classDef backend fill:#c7f9cc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd1dc,stroke:#333,stroke-width:2px;
    classDef build fill:#fff5ba,stroke:#333,stroke-width:2px;

    %% Click Events
    click PluginConfig "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/blob/main/src/main/resources/plugin.xml"
    click AdminPages "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/resources/webapp/diff-tool-admin"
    click PropPages "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/resources/webapp/diff-tool"
    click RestControllers "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/java/ch/sbb/polarion/extension/diff_tool/rest/controller"
    click ServiceLayers "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/java/ch/sbb/polarion/extension/diff_tool/service"
    click Utilities "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/java/ch/sbb/polarion/extension/diff_tool/util"
    click Velocity "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/src/main/java/ch/sbb/polarion/extension/diff_tool/velocity"
    click UIDiff "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/ui"
    click Maven "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/blob/main/pom.xml"
    click GitHub "https://github.com/schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool/tree/main/.github/workflows"
```
