# wl-online-payments-direct/plugin-magento-redirect-payments architecture

> Architecture diagram of the GitHub repository wl-online-payments-direct/plugin-magento-redirect-payments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wl-online-payments-direct/plugin-magento-redirect-payments
- Repository: https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments

## Overview

##### Overall Project Type and Purpose
- The project is a Magento module (plugin) that adds a payment solution using Worldline’s hosted and redirect capabilities.
- Its purpose is to integrate single “redirect payment” buttons and enhance Magento’s checkout functionality to communicate with external payment gateways.
- Key functionalities include building requests for hosted payments, handling payment configurations from the admin, and exposing REST endpoints for payment management.

##### Major Architectural Components
- Frontend Components:
- UI: Contains configuration providers (Ui/ConfigProvider.php, TokenUiComponentProvider.php) and JavaScript components that handle the redirection and dynamic behavior on the checkout page (located in view/frontend/web/js).
- Templates: HTML templates (view/frontend/web/template) and layouts (view/frontend/layout/checkout_index_index.xml) that integrate the payment method into Magento’s frontend.

- Backend Components:
- Blocks & Admin UI: Directories like Block/Adminhtml/System/Config provide GUI components for Magento’s admin panel, allowing configuration of payment methods and notifications.
- Observer & Plugin:
- Observer (e.g., Observer/PaymentMethodIsActive.php) to react to Magento events such as checking if a payment method is active.
- Plugin classes (under Plugin/Magento/Checkout) intercept and modify behaviors, particularly for the checkout layout and display logic.
- WebAPI Endpoints: WebApi folder exposes endpoints (e.g., CreatePaymentManagement) for managing payment processes and assigning specific payment data.
- Services:
- Service/CreateHostedCheckoutRequest contains builder classes to create payment requests for different payment types (card, mobile, redirect, SEPA Direct Debit, etc.).
- Service/HostedCheckout builds the complete hosted checkout request.
- Gateway: Contains configuration classes for integrating with the payment gateway and setting up necessary parameters.
- Vault: Manages secure storage of payment details using Magento’s vault system.
- Setup: Contains installation scripts and data patches (Setup/Patch/Data) that modify or migrate database settings when the module is installed or upgraded.
- Configuration/DI: etc/di.xml and other configuration files (system.xml, payment.xml, etc.) define dependency injections and module settings, ensuring that components are wired within Magento’s framework.

- Testing & Quality:
- Test/Integration: Extensive integration tests ensure proper payment flow behaviors, covering order placement, refunds, void operations, and configuration validations.
- .github/workflows configuration files indicate automated quality checks (coding standards, mess detectors).

##### Relationships and Data Flow
- The front end (checkout page) calls the UI components and uses JavaScript to capture customer actions. When a payment is initiated:
- The UI interacts with the Magento backend via WebAPIs.
- Plugins and Observers intercept relevant events and adjust the behavior (e.g., layout processing, payment activation).
- Service classes handle the business logic by building requests (including specific input data for various payment methods) and forwarding them to the Worldline API.
- The Gateway and configuration classes ensure that requests are properly formatted and that credentials/configurations are in place.
- The Vault and Setup components maintain and evolve the module’s state in the Magento ecosystem.
- Integration tests verify the end-to-end processing of payment requests.

##### Key Architectural Patterns and Technologies
- Modular Design: The module is separated into clearly defined domains (UI, service, gateway, web API, etc.), which follows the divide-and-conquer principle common in Magento extension design.
- Observer/Plugin Pattern: Employing Magento’s event-driven and interception (plugin) mechanisms to modify behaviors without core code changes.
- Dependency Injection: Extensive use of Magento’s DI configuration (etc/di.xml) for clean separation and testability.
- Integration Testing: A robust suite of integration tests to ensure that major workflows (from payment initiation to order processing) are covered.
- External SDK Integration: Integration with Worldline’s PHP SDK for processing transactions, reflected in service builders and dependency on the external library.

##### Final Advice
- Since the overall system integrates with an external payments provider, make sure that external interactions are clearly demarcated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI1["UI: Config Provider"] 
        UI2["UI: Token Component Provider"]
        T1["Template/Layout: checkout_index_index.xml"]
        T2["Template: worldlinerp.html"]
    end

    %% Application/Logic Layer
    subgraph "Application/Logic Layer"
        ACB["Admin Config Blocks"]
        OBS["Payment Observer"]
        PLG["Checkout Plugin"]
        WAPI1["WebAPI: CreatePaymentManagement"]
        WAPI2["WebAPI: RedirectManagement"]
        PRS["Payment Request Service Builders"]
        HCRB["Hosted Checkout Request Builder"]
        PVC["Payment Vault Integration"]
    end

    %% Integration Layer
    subgraph "Integration Layer"
        PGW["Payment Gateway Configuration"]
    end

    %% Data & Configuration Layer
    subgraph "Data & Configuration Layer"
        SETUP["Module Setup & Data Patches"]
        DI["Dependency Injection & Module Config"]
    end

    %% Testing and CI/CD Layer
    subgraph "Testing and CI/CD"
        TEST["Integration Testing"]
        CICD["CI/CD & Automated Quality Checks"]
    end

    %% Connections - Frontend to Logic
    UI1 -->|"initiates"| WAPI1
    UI2 -->|"initiates"| WAPI1
    T1 -->|"renders"| WAPI1
    T2 -->|"renders"| WAPI2

    %% Connections - WebAPI to Service Layer
    WAPI1 -->|"triggers"| PRS
    WAPI2 -->|"triggers"| PRS

    %% Connections - Service to Integration and Vault
    PRS -->|"builds request"| PGW
    PRS -->|"handles secure data"| PVC
    HCRB --> PRS

    %% Connections - DI influences Application/Logic Components
    DI --> ACB
    DI --> OBS
    DI --> PLG

    %% Connections - Setup feeds into DI
    SETUP --> DI

    %% Optional: Testing and CI/CD verification arrows (illustrative)
    TEST --- PGW
    TEST --- PRS
    CICD --- DI

    %% Styles
    classDef frontend fill:#F9C,stroke:#333,stroke-width:2px;
    classDef logic fill:#CCF,stroke:#333,stroke-width:2px;
    classDef integration fill:#CFC,stroke:#333,stroke-width:2px;
    classDef dataconfig fill:#FC9,stroke:#333,stroke-width:2px;
    classDef testing fill:#FCC,stroke:#333,stroke-width:2px;
    
    class UI1,UI2,T1,T2 frontend;
    class ACB,OBS,PLG,WAPI1,WAPI2,PRS,HCRB,PVC logic;
    class PGW integration;
    class SETUP,DI dataconfig;
    class TEST,CICD testing;

    %% Click Events
    click UI1 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Ui/ConfigProvider.php"
    click UI2 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Ui/TokenUiComponentProvider.php"
    click T1 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/view/frontend/layout/checkout_index_index.xml"
    click T2 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/view/frontend/web/template/payment/worldlinerp.html"
    click ACB "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Block/Adminhtml/System/Config/MealvouchersGlobalNotification.php"
    click OBS "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Observer/PaymentMethodIsActive.php"
    click PLG "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Plugin/Magento/Checkout/Block/Checkout/LayoutProcessor/PaymentsLayoutProcessor.php"
    click WAPI1 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/tree/main/WebApi/CreatePaymentManagement"
    click WAPI2 "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/WebApi/RedirectManagement.php"
    click PRS "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/tree/main/Service/CreateHostedCheckoutRequest"
    click HCRB "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Service/HostedCheckout/CreateHostedCheckoutRequestBuilder.php"
    click PGW "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Gateway/Config/Config.php"
    click PVC "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/Vault/Vault.php"
    click SETUP "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/tree/main/Setup"
    click DI "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/blob/main/etc/di.xml"
    click TEST "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/tree/main/Test/Integration"
    click CICD "https://github.com/wl-online-payments-direct/plugin-magento-redirect-payments/tree/main/.github/workflows"
```
