# yousseftamri/openai-php architecture

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

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

## Overview

##### Project Type and Purpose
- This is a PHP SDK (API client library) for OpenAI’s REST API. It is neither a web application nor a microservice but an SDK you embed in user code.

##### Main Architectural Layers and Components
A. Public API Layer (blue)
- Factory (OpenAI\Factory)
- Builder pattern: configures API key, base URI, HTTP client, headers, query params.
- .make() → returns Client.
- Client (OpenAI\Client)
- Façade exposing methods: chat(), completions(), models(), files(), etc.
- Implements ClientContract.
- Resources (OpenAI\Resources\*)
- One class per endpoint group (Chat, Completions, Images, Threads, VectorStores…).
- Expose high-level methods (create(), list(), retrieve(), delete(), createStreamed(), etc).

B. Domain / Contracts Layer (orange)
- Contracts (OpenAI\Contracts\*)
- Interfaces: ClientContract, TransporterContract, ResourceContracts, ResponseContract, ResponseStreamContract, StringableContract.
- Enums (OpenAI\Enums\*)
- Typed constants for content types, HTTP methods, moderation categories, fine-tuning event levels.
- ValueObjects (OpenAI\ValueObjects\*)
- ApiKey, BaseUri, Headers, QueryParams, Payload, Response: encapsulate raw data.

C. Transport / Infrastructure Layer (green)
- Transporter: HttpTransporter (implements TransporterContract)
- Uses PSR-18 HTTP client (e.g. Guzzle).
- Builds PSR-7 Request from ValueObjects.
- Sends HTTP, receives PSR-7 Response.
- Wraps in ValueObjects\Transporter\Response for downstream.
- HTTP Client (external): e.g. GuzzleHttp\Client, injected via PSR-18 Discovery or manually.

D. Response Mapping Layer
- Responses (OpenAI\Responses\*)
- One sub-namespace per resource.
- JSON keys into strongly typed objects (choices, usage, segments, events, etc).
- Support meta-information: rate limits, request IDs.
- Exceptions (OpenAI\Exceptions\*)
- ErrorException, TransporterException, InvalidArgumentException, UnknownEventException, etc.

E. Testing Layer (gray)
- ClientFake (OpenAI\Testing\ClientFake)
- Implements ClientContract, bypasses HTTP, returns prebuilt fakes or fixtures from src/Testing or tests/Fixtures.
- Allows assertions on sent requests.

##### Component Relationships and Data Flow
1. User Code calls OpenAI\Factory → configures and builds an OpenAI\Client.
2. Client.method() delegates to a Resource instance.
3. Resource prepares parameters and invokes Transporter->send().
4. Transporter:
- Assembles PSR-7 Request (ValueObjects: ApiKey, Headers, BaseUri, QueryParams, Payload)
- Calls HTTP client → hits OpenAI REST API endpoint.
- Receives PSR-7 Response → wraps into ValueObjects\Response.
5. Resource decodes JSON → instantiates Response objects (e.g., CreateResponse, ListResponse, StreamedResponse).
6. User code consumes typed response.
7. On error, Exceptions bubble up.

##### Architectural Patterns and Principles
- Dependency Injection: HTTP client, headers, query params injected via Factory.
- Facade Pattern: Client and Resources hide low-level HTTP details.
- Strategy/Adapter: TransporterContract allows swapping HTTP implementations.
- Factory/Builder: Factory for client configuration.
- Interface Segregation: Contracts for each module → clear DIP.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    UserCode["User Code"] 

    %% Public API Layer (blue)
    subgraph "Public API Layer"
        Factory["Factory"]:::publicapi
        Client["Client"]:::publicapi
        Entry["OpenAI\u200b.php (Entry)"]:::publicapi
        ResourcesGroup["Resources"]:::publicapi
    end

    %% Domain / Contracts Layer (orange)
    subgraph "Domain / Contracts Layer"
        Contracts["Contracts"]:::domain
        Enums["Enums"]:::domain
        ValueObjects["Value Objects"]:::domain
    end

    %% Transport / Infrastructure Layer (green)
    subgraph "Transport / Infrastructure Layer"
        Transporter["HttpTransporter"]:::infra
        HttpClient["HTTP Client"]:::infra
    end

    %% Response Mapping Layer (yellow)
    subgraph "Response Mapping Layer"
        Responses["Responses"]:::response
        Exceptions["Exceptions"]:::response
    end

    %% Testing Layer (gray)
    subgraph "Testing Layer"
        ClientFake["ClientFake"]:::testing
    end

    %% External API
    OpenAIAPI(("OpenAI API")):::external

    %% Flows
    UserCode -->|"build() "| Factory -->|"returns Client"| Client -->|"calls methods"| ResourcesGroup -->|"invoke send()"| Transporter -->|"uses PSR-18"| HttpClient -->|"send HTTP"| OpenAIAPI
    OpenAIAPI -->|"response"| HttpClient -->|"wrap in VO"| Transporter -->|"map JSON"| Responses -->|"return object"| Client --> UserCode
    ResourcesGroup --> Contracts
    ResourcesGroup --> ValueObjects
    Transporter --> ValueObjects
    Responses --> ValueObjects
    Exceptions -.-> ResourcesGroup
    ClientFake -.-> Transporter
    ClientFake -.-> HttpClient

    %% Click events
    click Factory "https://github.com/yousseftamri/openai-php/blob/main/src/Factory.php"
    click Client "https://github.com/yousseftamri/openai-php/blob/main/src/Client.php"
    click Entry "https://github.com/yousseftamri/openai-php/blob/main/src/OpenAI.php"
    click ResourcesGroup "https://github.com/yousseftamri/openai-php/tree/main/src/Resources"
    click Contracts "https://github.com/yousseftamri/openai-php/tree/main/src/Contracts"
    click Enums "https://github.com/yousseftamri/openai-php/tree/main/src/Enums"
    click ValueObjects "https://github.com/yousseftamri/openai-php/tree/main/src/ValueObjects"
    click Transporter "https://github.com/yousseftamri/openai-php/blob/main/src/Transporters/HttpTransporter.php"
    click Responses "https://github.com/yousseftamri/openai-php/tree/main/src/Responses"
    click Exceptions "https://github.com/yousseftamri/openai-php/tree/main/src/Exceptions"
    click ClientFake "https://github.com/yousseftamri/openai-php/blob/main/src/Testing/ClientFake.php"

    %% Styles
    classDef publicapi fill:#cce5ff,stroke:#0062cc,color:#000;
    classDef domain fill:#ffe5cc,stroke:#cc6600,color:#000;
    classDef infra fill:#e5ffe5,stroke:#009900,color:#000;
    classDef response fill:#ffffcc,stroke:#cccc00,color:#000;
    classDef testing fill:#eeeeee,stroke:#888888,color:#000;
    classDef external fill:#f0f0f0,stroke:#666666,stroke-dasharray: 5 5,color:#000;
```
