# truelayer/truelayer-php architecture

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

- Interactive diagram: https://gitdiagram.com/truelayer/truelayer-php
- Repository: https://github.com/truelayer/truelayer-php

## Overview

##### Project Type and Purpose
- This is a PHP SDK / client library for the TrueLayer API.
- It’s an open-source tool that provides a type-safe facade over TrueLayer’s REST endpoints (payments, refunds, payouts, merchant accounts, signup-plus, webhooks).
- Key indicators:
- src/Client.php and src/Webhook.php expose the public API
- src/Services/Api and src/Services/ApiClient handle HTTP calls
- src/Entities, src/Interfaces and src/Factories implement a domain model + builder factories
- README describes usage scenarios (creating payments, refunds, webhooks)

##### File Structure Analysis
- Top-level src contains:
- Client entry point (Client.php, Settings.php)
- Domain model: Entities/Interfaces for AccountIdentifier, Payment, Payout, Webhook, etc.
- Factories: ApiFactory, ClientFactory, EntityFactory, WebhookFactory
- Services:
– Api (AccessTokenApi, PaymentsApi, …)
– ApiClient (core HTTP request builder + Decorators for signing, idempotency, retry, TL-Agent header)
– Auth (AccessToken service)
– Configuration (ClientConfig, WebhookConfig)
– Util (Arr, Str, Encryption, Retry, FromGlobals)
– Webhooks (JwksManager, Webhook, WebhookHandlerManager, WebhookVerifier)
- Patterns:
- Builder / Fluent configurator (Client::configure())
- Factory pattern for Entities and API clients
- Decorator pattern around ApiClient for cross-cutting concerns
- Layered separation: Public API → Services / Factories → Domain Entities → HTTP layer
- Config and lang directories hold config files and translations (validation messages)

##### Key Architectural Insights from README
- Public façade handles: authentication (with caching), signing, idempotency, retry logic, typed resource builders
- Dependencies: any PSR-18 HTTP client, PSR-16 cache
- Webhook subsystem verifies signatures via JWKs fetched from TrueLayer

- Clear labels for each component (e.g., “PaymentsApi”, “ApiClient”, “SigningDecorator”)
- from Client façade to API calls
- from ApiClient through Decorators to external TrueLayer endpoint
- from Webhook endpoint to WebhookVerifier to handlers
- Public façade (blue)
- Application services + factories (green)
- Domain entities (yellow)
- Infrastructure adapters (gray)
- External systems (orange)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public Facade Layer
    subgraph "Public Facade" 
        direction TB
        Client["Client Facade"]:::facade
        WebhookEntry["Webhook Facade"]:::facade
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ClientConfig["ClientConfig"]:::service
        WebhookConfig["WebhookConfig"]:::service
        Settings["Settings"]:::service
    end

    %% Factory Layer
    subgraph "Factory Layer"
        direction TB
        ApiFactory["ApiFactory"]:::service
        ClientFactory["ClientFactory"]:::service
        EntityFactory["EntityFactory"]:::service
        WebhookFactory["WebhookFactory"]:::service
    end

    %% API Services Layer
    subgraph "API Services"
        direction TB
        PaymentsApi["PaymentsApi"]:::service
        PayoutsApi["PayoutsApi"]:::service
        MerchantAccountsApi["MerchantAccountsApi"]:::service
        SignupPlusApi["SignupPlusApi"]:::service
        WebhooksApi["WebhooksApi"]:::service
    end

    %% Authentication Service
    subgraph "Authentication Service"
        direction TB
        AccessTokenApi["AccessTokenApi"]:::service
        AccessTokenService["AccessToken"]:::service
    end

    %% API Client Core and Decorators
    subgraph "API Client Layer"
        direction TB
        ApiClientCore["ApiClient"]:::infra
        ApiRequest["ApiRequest"]:::infra
        AccessTokenDecorator["AccessTokenDecorator"]:::infra
        SigningDecorator["SigningDecorator"]:::infra
        IdempotencyKeyDecorator["IdempotencyKeyDecorator"]:::infra
        ExponentialBackoffDecorator["ExponentialBackoffDecorator"]:::infra
        TLAgentDecorator["TLAgentDecorator"]:::infra
    end

    %% Webhook Subsystem
    subgraph "Webhook Subsystem"
        direction TB
        WebhookService["Webhook"]:::service
        WebhookVerifier["WebhookVerifier"]:::service
        JwksManager["JwksManager"]:::service
        HandlerManager["WebhookHandlerManager"]:::service
    end

    %% Domain Layer
    subgraph "Domain Model"
        direction TB
        Entities["Entities"]:::domain
        Interfaces["Interfaces"]:::domain
    end

    %% Utility Services
    subgraph "Utility & Infrastructure"
        direction TB
        EncryptedCache["EncryptedCache"]:::infra
        Encrypter["Encrypter"]:::infra
        RetryUtil["Retry"]:::infra
        Arr["Arr"]:::infra
        Str["Str"]:::infra
        FromGlobals["FromGlobals"]:::infra
        HTTPClient["PSR-18 HTTP Client"]:::external
        CacheImpl["PSR-16 Cache"]:::external
        TrueLayerAPI["TrueLayer REST API"]:::external
    end

    %% Relationships
    Client -->|uses| ClientConfig
    Client -->|uses| Settings
    Client -->|uses| ApiFactory
    Client -->|uses| WebhookFactory

    ClientFactory -->|creates| Client
    ApiFactory -->|provides APIs| PaymentsApi
    ApiFactory --> PayoutsApi
    ApiFactory --> MerchantAccountsApi
    ApiFactory --> SignupPlusApi
    ApiFactory --> WebhooksApi

    PaymentsApi -->|calls| ApiClientCore
    PayoutsApi --> ApiClientCore
    MerchantAccountsApi --> ApiClientCore
    SignupPlusApi --> ApiClientCore
    WebhooksApi --> ApiClientCore

    ApiClientCore --> ApiRequest
    ApiRequest --> AccessTokenDecorator
    AccessTokenDecorator --> SigningDecorator
    SigningDecorator --> IdempotencyKeyDecorator
    IdempotencyKeyDecorator --> ExponentialBackoffDecorator
    ExponentialBackoffDecorator --> TLAgentDecorator
    TLAgentDecorator --> HTTPClient
    HTTPClient --> TrueLayerAPI

    AccessTokenDecorator -->|requests token| AccessTokenApi
    AccessTokenApi --> AccessTokenService
    AccessTokenService --> EncryptedCache
    EncryptedCache --> CacheImpl
    EncryptedCache --> Encrypter

    %% Factory to Entities
    EntityFactory --> Entities
    EntityFactory --> Interfaces

    %% Webhook flow
    WebhookEntry --> WebhookService
    WebhookService --> FromGlobals
    WebhookService -->|verifies| WebhookVerifier
    WebhookVerifier --> JwksManager
    JwksManager --> TrueLayerAPI
    WebhookVerifier --> HandlerManager

    %% Click events
    click Client "https://github.com/truelayer/truelayer-php/blob/main/src/Client.php"
    click WebhookEntry "https://github.com/truelayer/truelayer-php/blob/main/src/Webhook.php"
    click ClientConfig "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Client/ClientConfig.php"
    click WebhookConfig "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Webhooks/WebhookConfig.php"
    click Settings "https://github.com/truelayer/truelayer-php/blob/main/src/Settings.php"
    click AccessTokenApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/AccessTokenApi.php"
    click AccessTokenService "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Auth/AccessToken.php"
    click ApiClientCore "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/ApiClient.php"
    click ApiRequest "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/ApiRequest.php"
    click AccessTokenDecorator "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/Decorators/AccessTokenDecorator.php"
    click SigningDecorator "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/Decorators/SigningDecorator.php"
    click IdempotencyKeyDecorator "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/Decorators/IdempotencyKeyDecorator.php"
    click ExponentialBackoffDecorator "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/Decorators/ExponentialBackoffDecorator.php"
    click TLAgentDecorator "https://github.com/truelayer/truelayer-php/blob/main/src/Services/ApiClient/Decorators/TLAgentDecorator.php"
    click PaymentsApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/PaymentsApi.php"
    click PayoutsApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/PayoutsApi.php"
    click MerchantAccountsApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/MerchantAccountsApi.php"
    click SignupPlusApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/SignupPlusApi.php"
    click WebhooksApi "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Api/WebhooksApi.php"
    click ApiFactory "https://github.com/truelayer/truelayer-php/blob/main/src/Factories/ApiFactory.php"
    click ClientFactory "https://github.com/truelayer/truelayer-php/blob/main/src/Factories/ClientFactory.php"
    click EntityFactory "https://github.com/truelayer/truelayer-php/blob/main/src/Factories/EntityFactory.php"
    click WebhookFactory "https://github.com/truelayer/truelayer-php/blob/main/src/Factories/WebhookFactory.php"
    click WebhookService "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Webhooks/Webhook.php"
    click JwksManager "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Webhooks/JwksManager.php"
    click WebhookVerifier "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Webhooks/WebhookVerifier.php"
    click HandlerManager "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Webhooks/WebhookHandlerManager.php"
    click EncryptedCache "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/EncryptedCache.php"
    click Encrypter "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/Encryption/Encrypter.php"
    click RetryUtil "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/Retry.php"
    click Arr "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/Arr.php"
    click Str "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/Str.php"
    click FromGlobals "https://github.com/truelayer/truelayer-php/blob/main/src/Services/Util/FromGlobals.php"

    %% Styles
    classDef facade fill:#D0E6FF,stroke:#0000CC,color:#000
    classDef service fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef domain fill:#FFF2CC,stroke:#9F6000,color:#000
    classDef infra fill:#E0E0E0,stroke:#666666,color:#000
    classDef external fill:#FFD2D2,stroke:#CC0000,color:#000
```
