# openai-php/client architecture

> Architecture diagram of the GitHub repository openai-php/client, 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/openai-php/client
- Repository: https://github.com/openai-php/client

## Overview

- Client Facade & Factory:
– Represent the primary entry point (the Client/Facade found in files like OpenAI.php and Factory.php). This component exposes a high‑level API (e.g. client()->chat()->create([...])) that developers use to interact with OpenAI.
– Include configuration options (“withApiKey”, “withOrganization”, “withHttpClient”, etc.) that are set via the factory.

- Resource Layer:

- Contracts and Abstractions:
– Include the “Contracts” folder as a separate layer. These interfaces (e.g. ClientContract, TransporterContract, Resources contracts, ResponseContract, etc.) define the expected behavior for resources and dependencies. This signals a clean separation of interfaces from concrete implementations.

- Communication/Transport Layer:
– Illustrate the “Transporters” component (e.g. HttpTransporter.php) along with the “ValueObjects” that define API keys, Base URI, headers, query parameters, payload, etc.

- Response Handling:
– Indicate that responses often include “meta” information (as seen in the README) and that there are dedicated classes to map the raw API responses into well‑formatted PHP objects.

- Exception Handling:
– Add a separate portion for “Exceptions” which are thrown when errors occur. This layer encapsulates error, invalid argument, or transporter-related exceptions.

- Testing and Fakes:
– Finally, include a testing sublayer (derived from the “tests” and “src/Testing” folders). Show that there exists a “ClientFake” allowing developers to simulate API calls and assertions.

##### Relationships and Data Flow
- Start at the “Application” boundary (the code that calls OpenAI::client() or OpenAI::factory() to obtain a configured API client).
– Application → Client Facade → Resource Layer.
– Resource Layer → Contracts & Abstractions (to ensure interfaces are met).
– Resource Layer → Transporter Component (HTTP calls are delegated here).
- Additionally, annotate that the “meta” information and error handling occurs at the top level and in the Client so that users can inspect request IDs, token usage, and errors.

##### Architectural Patterns
- Use of the Facade pattern in exposing a simple API (via OpenAI::client() and resource methods) while hiding the underlying complexity.
- Use of Dependency Injection, where HTTP client implementations and configuration values (headers, base URI, etc.) are injected through a factory.
- Acknowledge the use of contracts (interfaces) to decouple components, meaning that resources can be swapped or extended without changing the core business logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    APP["Application"]:::client
    API["OpenAI External API"]:::transport

    %% Client/Factory Layer
    subgraph "Client/Factory"
        CF1["Client Facade"]:::client
        CF2["Client Factory"]:::client
    end

    %% Resource Layer
    subgraph "Resources"
        RES["Resources Endpoints\n(Chat, Completions, Models, etc.)"]:::resource
    end

    %% Contracts/Abstractions Layer
    subgraph "Contracts/Abstractions"
        CONTR["Contracts & Abstractions"]:::contracts
    end

    %% Communication/Transport Layer
    subgraph "Communication/Transport"
        TRANSPORT["HTTP Transporter"]:::transport
        VALUEOBJ["Value Objects"]:::transport
    end

    %% Response Handling Layer
    subgraph "Response Handling"
        RESH["Response Mapping & Meta Handling"]:::response
    end

    %% Exception Handling Layer
    subgraph "Exception Handling"
        EXC["Exceptions"]:::exception
    end

    %% Testing Layer
    subgraph "Testing"
        QA["ClientFake"]:::testing
    end

    %% Connections
    APP -->|"calls"| CF1
    APP -->|"calls"| CF2

    CF1 -->|"initializes"| RES
    CF2 -->|"configures"| RES

    RES -->|"implements"| CONTR
    RES -->|"delegatesHTTP"| TRANSPORT

    TRANSPORT -->|"uses"| VALUEOBJ
    TRANSPORT -->|"sendsRequest"| API
    API -->|"returnsResponse"| TRANSPORT

    TRANSPORT -->|"mapsResponse"| RESH
    RESH -->|"deliversMapped"| RES

    RES -->|"handlesErrors"| EXC

    APP -->|"canStubWith"| QA
    QA -->|"simulates"| RES

    %% Click Events
    click CF1 "https://github.com/openai-php/client/blob/main/src/OpenAI.php"
    click CF2 "https://github.com/openai-php/client/blob/main/src/Factory.php"
    click RES "https://github.com/openai-php/client/tree/main/src/Resources/"
    click CONTR "https://github.com/openai-php/client/tree/main/src/Contracts/"
    click TRANSPORT "https://github.com/openai-php/client/blob/main/src/Transporters/HttpTransporter.php"
    click VALUEOBJ "https://github.com/openai-php/client/tree/main/src/ValueObjects/Transporter/"
    click RESH "https://github.com/openai-php/client/tree/main/src/Responses/"
    click EXC "https://github.com/openai-php/client/tree/main/src/Exceptions/"
    click QA "https://github.com/openai-php/client/blob/main/src/Testing/ClientFake.php"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef resource fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef contracts fill:#f3e5f5,stroke:#333,stroke-width:2px;
    classDef transport fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef response fill:#fde2e2,stroke:#333,stroke-width:2px;
    classDef exception fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef testing fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
