# homeruntech/closeio-api-wrapper architecture

> Architecture diagram of the GitHub repository homeruntech/closeio-api-wrapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/homeruntech/closeio-api-wrapper
- Repository: https://github.com/homeruntech/closeio-api-wrapper

## Overview

##### Main system type and purpose
- This project is a **PHP SDK** / **API client library** for the Close.io REST services.
- Its goal is to let PHP applications instantiate API classes, send HTTP requests, and receive hydrated domain models.

##### Main components
a. **Client Configuration**
- `Configuration` holds API key, base URL, default headers.
b. **HTTP Transport Layer**
- **Httplug Client (PSR-18 / PSR-7 implementation)** (e.g., nyholm/psr7 + php-http/curl-client)
- `ClientInterface` and its concrete `Client` implementation use Httplug to send PSR-7 `Requests` and receive PSR-7 `Responses`.
c. **Facade / Wrapper**
- `CloseIoApiWrapper` exposes top-level `getXxxApi()` methods (LeadApi, OpportunityApi, ActivityApi, etc.).
d. **API Modules** (`src/Api`)
- Each API class (e.g., `LeadApi`, `OpportunityApi`, etc.) extends `Library\Api\AbstractApi`.
- These modules build HTTP requests, call the `Client`, and wrap raw responses.
e. **Domain Models** (`src/Model`)
- Plain PHP objects (`Lead`, `Contact`, `Task`, etc.) with getters/setters.
f. **Hydration & Utilities** (`src/Library`)
- Traits and helpers (`JsonSerializableHelperTrait`, `ObjectHydrateHelperTrait`, `UrlUtils`, `InflectorSingleton`) that translate raw JSON into Model instances.
g. **Exception Hierarchy** (`src/Exception`)
- Custom exceptions (authentication, throttling, bad request, not found, etc.) thrown by the HTTP layer or API modules.
h. **External Service**
- The Close.io REST API (an external HTTP endpoint).

##### Relationships and data flows
- **External App** calls → `CloseIoApiWrapper` → chooses an `Api` module
- `Api` module uses → `Client` via `ClientInterface` → constructs a PSR-7 `Request` using `Configuration`
- `Client` sends → HTTP request over the network via Httplug → receives PSR-7 `Response`
- `Api` module inspects status code → throws mapped exceptions if needed → extracts JSON body
- JSON is passed to → Hydration helpers → produces PHP `Model` objects
- `Api` returns hydrated `Model` or a wrapper (`CloseIoResponse`) to External App

##### Architectural patterns and principles
- **Facade Pattern:** `CloseIoApiWrapper` unifies all API modules.
- **Adapter Pattern:** Httplug decouples HTTP client implementations.
- **Single Responsibility:** Separate layers for configuration, transport, API logic, model hydration, and exceptions.
- **PSR-7 / PSR-18 Compliance:** Interfaces standardize HTTP messages and clients.

##### Essential elements to capture
- Clear separation: **Facade** vs. **Api modules** vs. **Transport** vs. **Model/Hydration** vs. **Exceptions**
- PSR interfaces as boundaries
- Configuration’s role in building requests
- The external service as the system’s sink/source

## Diagram (Mermaid)

```mermaid
flowchart TB
    ExternalApp["External Application"]:::external
    ExternalApp -->|"calls"| Wrapper

    subgraph "Facade Layer"
        Wrapper["CloseIoApiWrapper"]:::api
    end

    Wrapper -->|"getXxxApi()"| ApiModules

    subgraph "API Modules"
        direction TB
        AbstractApi["AbstractApi"]:::api
        subgraph "Modules"
            LeadApi["LeadApi"]:::api
            OpportunityApi["OpportunityApi"]:::api
            ContactApi["ContactApi"]:::api
            ActivityApi["ActivityApi"]:::api
            CallActivityApi["CallActivityApi"]:::api
            CustomFieldApi["CustomFieldApi"]:::api
            EmailActivityApi["EmailActivityApi"]:::api
            NoteActivityApi["NoteActivityApi"]:::api
            OpportunityStatusApi["OpportunityStatusApi"]:::api
            LeadStatusApi["LeadStatusApi"]:::api
            SmsActivityApi["SmsActivityApi"]:::api
            TaskApi["TaskApi"]:::api
            UserApi["UserApi"]:::api
        end
        Modules --> AbstractApi
    end

    AbstractApi -->|"uses"| ClientInterface
    ClientInterface["ClientInterface"]:::transport
    ClientInterface -->|"implemented by"| Client
    Client["Client"]:::transport

    Configuration["Configuration"]:::transport
    Client -->|"requires Config"| Configuration

    Client -->|"sends PSR-7 Request"| CloseIoRequest
    CloseIoRequest["CloseIoRequest"]:::transport
    CloseIoRequest -->|"to Httplug"| ExternalService

    ExternalService["Close.io REST API"]:::external

    ExternalService -->|"responds PSR-7 Response"| CloseIoResponse
    CloseIoResponse["CloseIoResponse"]:::transport

    AbstractApi -->|"handles Response"| CloseIoResponse
    AbstractApi -->|"extracts JSON"| JSONBody

    subgraph "Hydration & Utilities"
        JsonTrait["JsonSerializableHelperTrait"]:::util
        ObjectTrait["ObjectHydrateHelperTrait"]:::util
        UrlUtils["UrlUtils"]:::util
        Inflector["InflectorSingleton"]:::util
    end

    JSONBody((JSON body)):::transport
    JSONBody --> JsonTrait
    JSONBody --> ObjectTrait
    JSONBody --> UrlUtils
    JSONBody --> Inflector
    JSONBody --> Models

    subgraph "Domain Models"
        direction TB
        Activity["Activity"]:::model
        Address["Address"]:::model
        CallActivity["CallActivity"]:::model
        Contact["Contact"]:::model
        CustomField["CustomField"]:::model
        Email["Email"]:::model
        EmailActivity["EmailActivity"]:::model
        Lead["Lead"]:::model
        LeadStatus["LeadStatus"]:::model
        NoteActivity["NoteActivity"]:::model
        Opportunity["Opportunity"]:::model
        OpportunityStatus["OpportunityStatus"]:::model
        Phone["Phone"]:::model
        SmsActivity["SmsActivity"]:::model
        Task["Task"]:::model
        Url["Url"]:::model
        User["User"]:::model
    end

    Models -->|"Model instances"| ExternalApp

    subgraph "Exceptions"
        direction TB
        AuthEx["CloseIoAuthenticationException"]:::exception
        BadRequestEx["CloseIoBadRequestException"]:::exception
        ResponseEx["CloseIoResponseException"]:::exception
        NotFoundEx["CloseIoResourceNotFoundException"]:::exception
        ThrottleEx["CloseIoThrottleException"]:::exception
        GenericEx["CloseIoException"]:::exception
        InvalidMethodEx["InvalidHttpMethodException"]:::exception
        JsonEx["JsonException"]:::exception
        LibInvalidLeadEx["InvalidNewLeadPropertyException"]:::exception
        LibInvalidParamEx["InvalidParamException"]:::exception
        LibInvalidUrlEx["InvalidUrlException"]:::exception
    end

    Client -->|"throws Exceptions"| AuthEx
    Client --> BadRequestEx
    Client --> ResponseEx
    Client --> NotFoundEx
    Client --> ThrottleEx
    Client --> GenericEx
    Client --> InvalidMethodEx
    Client --> JsonEx
    AbstractApi --> LibInvalidLeadEx
    AbstractApi --> LibInvalidParamEx
    AbstractApi --> LibInvalidUrlEx

    click Configuration "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Configuration.php"
    click ClientInterface "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/ClientInterface.php"
    click Client "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Client.php"
    click CloseIoRequest "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/CloseIoRequest.php"
    click CloseIoResponse "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/CloseIoResponse.php"
    click Wrapper "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/CloseIoApiWrapper.php"
    click ActivityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/ActivityApi.php"
    click CallActivityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/CallActivityApi.php"
    click ContactApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/ContactApi.php"
    click CustomFieldApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/CustomFieldApi.php"
    click EmailActivityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/EmailActivityApi.php"
    click LeadApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/LeadApi.php"
    click LeadStatusApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/LeadStatusApi.php"
    click NoteActivityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/NoteActivityApi.php"
    click OpportunityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/OpportunityApi.php"
    click OpportunityStatusApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/OpportunityStatusApi.php"
    click SmsActivityApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/SmsActivityApi.php"
    click TaskApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/TaskApi.php"
    click UserApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Api/UserApi.php"
    click AbstractApi "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/Api/AbstractApi.php"
    click JsonTrait "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/JsonSerializableHelperTrait.php"
    click ObjectTrait "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/ObjectHydrateHelperTrait.php"
    click UrlUtils "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/UrlUtils.php"
    click Inflector "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/Doctrine/InflectorSingleton.php"
    click AuthEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoAuthenticationException.php"
    click BadRequestEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoBadRequestException.php"
    click ResponseEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoResponseException.php"
    click NotFoundEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoResourceNotFoundException.php"
    click ThrottleEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoThrottleException.php"
    click GenericEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/CloseIoException.php"
    click InvalidMethodEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/InvalidHttpMethodException.php"
    click JsonEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Exception/JsonException.php"
    click LibInvalidLeadEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/Exception/InvalidNewLeadPropertyException.php"
    click LibInvalidParamEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/Exception/InvalidParamException.php"
    click LibInvalidUrlEx "https://github.com/homeruntech/closeio-api-wrapper/blob/develop/src/Library/Exception/InvalidUrlException.php"

    classDef transport fill:#d0e7ff,stroke:#007acc,stroke-width:1px
    classDef api fill:#dff4d8,stroke:#2f8f00,stroke-width:1px
    classDef model fill:#ffe5b4,stroke:#ff9900,stroke-width:1px
    classDef util fill:#f2f2f2,stroke:#888888,stroke-width:1px
    classDef exception fill:#f2f2f2,stroke:#cc0000,stroke-width:1px
    classDef external fill:#f3e5f5,stroke:#9c27b0,stroke-width:1px
```
