# xrubin/openexchangerates architecture

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

- Interactive diagram: https://gitdiagram.com/xrubin/openexchangerates
- Repository: https://github.com/xrubin/openexchangerates

## Overview

##### Project Type and Purpose
- This is an **open‐source PHP client library** that implements the [OpenExchangeRates.org REST API](https://docs.openexchangerates.org).
- It is *not* a full‐stack application; rather, it is a reusable tool that developers install via Composer to interact programmatically with the Open Exchange Rates service.

##### File Structure
- Top‐level files:
- `.github/workflows/ci.yml` – CI pipeline
- `composer.json` – defines package metadata & dependencies
- `phpunit.xml` – test runner configuration
- `src/` directory:
- `OpenExchangeRatesApi.php` – core client class, builds & sends HTTP requests
- Model classes (`RatesResponse.php`, `UsageResponse.php`, `PlanInformation.php`, `UsageInformation.php`, `UsageData.php`) – map JSON payloads to PHP objects
- `examples/` directory: sample usage scripts demonstrating common API calls
- `tests/` directory: unit tests for core functionality

##### Extract Key Architectural Insights from the README
- The library wraps endpoints: `/latest`, `/historical`, `/currencies`, `/usage`.
- Users configure the client (app_id, optional parameters: `base`, `symbols`, `show_alternative`).
- Under the hood, the client performs HTTP(S) calls, parses JSON, and returns strongly typed PHP objects.

##### Main Components
a. **Consumer Application**
– The end user’s PHP code or example scripts that `composer require rubin/openexchangerates` and then `new OpenExchangeRatesApi(...)`.
b. **Composer Autoloader**
– Resolves and loads library classes at runtime.
c. **OpenExchangeRatesApi (Client Layer)**
– Exposes public methods: `getLatest()`, `getHistorical()`, `getCurrencies()`, `getUsage()`.
– Manages configuration parameters (`app_id`, `base`, `symbols`, `show_alternative`).
d. **HTTP Transport / PSR‐18 Client**
– The HTTP client (cURL/Guzzle or any PSR‐18 implementation) used by `OpenExchangeRatesApi` to issue REST calls.
e. **JSON Parser / Model Mapper**
– After receiving raw JSON, the library maps payloads into Model objects (`RatesResponse`, `UsageResponse`, etc.).
f. **External OpenExchangeRates Service**
– The remote REST API endpoints hosted by OpenExchangeRates.org.
g. **CI/CD Pipeline** (optional overlay)
– `.github/workflows/ci.yml`, PHPUnit tests, Coveralls integration.

##### Relationships and Data Flows
- **Consumer → Composer Autoloader** (Dependency Injection of classes)
- **Consumer → OpenExchangeRatesApi** (Method calls: e.g., `getLatest()`)
- **OpenExchangeRatesApi → HTTP Transport** (Build URL + parameters → send HTTP request)
- **HTTP Transport → External Service** (HTTPS request to `https://openexchangerates.org/api/latest.json?app_id=...`)
- **External Service → HTTP Transport** (JSON response)
- **HTTP Transport → JSON Parser / Model Mapper** (Decode JSON → instantiate model objects)
- **Model Mapper → Consumer** (Return typed response objects)

##### Architectural Patterns & Principles
- **Single Responsibility**: `OpenExchangeRatesApi` focuses on request orchestration; model classes handle data representation.
- **Dependency Inversion**: Allow injection of HTTP client implementations (PSR‐18) for testability.
- **Adapter Pattern**: The library adapts the raw HTTP/JSON API into a PHP‐centric object API.
- **Test Coverage**: Unit tests in `tests/` enforce correct request construction and response mapping.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Application
    subgraph "Consumer Application"
        EX1["examples/"]:::consumer
    end

    %% Library Internals
    subgraph "Library Internals"
        AL["Composer Autoloader\n(composer.json)"]:::internal
        CLIENT["OpenExchangeRatesApi\n(src/OpenExchangeRatesApi.php)"]:::internal
        HTTPC["HTTP Transport\n(PSR-18 Client)"]:::internal
        MAPPER["JSON Parser / Model Mapper"]:::internal
        subgraph "Model Classes"
            MR1["RatesResponse"]:::models
            MR2["UsageResponse"]:::models
            MR3["UsageData"]:::models
            MR4["UsageInformation"]:::models
            MR5["PlanInformation"]:::models
        end
    end

    %% External Service
    EXT["OpenExchangeRates REST API"]:::external

    %% CI/CD & Tests
    subgraph "CI/CD & Tests"
        CIYML[".github/workflows/ci.yml"]:::pipeline
        PHPUnit["phpunit.xml"]:::pipeline
        TEST["OpenExchangeRatesApiTest.php\n(tests/)"]:::pipeline
    end

    %% Data Flows
    EX1 -->|"requires"| AL
    EX1 -->|"instantiates"| CLIENT
    CLIENT -->|"sends request"| HTTPC
    HTTPC -->|"HTTP request"| EXT
    EXT -->|"JSON response"| HTTPC
    HTTPC -->|"parses JSON"| MAPPER
    MAPPER -->|"returns models"| EX1

    %% Model Mapping Flows
    MAPPER --> MR1
    MAPPER --> MR2
    MAPPER --> MR3
    MAPPER --> MR4
    MAPPER --> MR5

    %% CI/CD Flows
    CIYML --> PHPUnit
    PHPUnit --> TEST

    %% Click Events
    click EX1 "https://github.com/xrubin/openexchangerates/tree/master/examples/"
    click AL "https://github.com/xrubin/openexchangerates/blob/master/composer.json"
    click CLIENT "https://github.com/xrubin/openexchangerates/blob/master/src/OpenExchangeRatesApi.php"
    click MR1 "https://github.com/xrubin/openexchangerates/blob/master/src/RatesResponse.php"
    click MR2 "https://github.com/xrubin/openexchangerates/blob/master/src/UsageResponse.php"
    click MR3 "https://github.com/xrubin/openexchangerates/blob/master/src/UsageData.php"
    click MR4 "https://github.com/xrubin/openexchangerates/blob/master/src/UsageInformation.php"
    click MR5 "https://github.com/xrubin/openexchangerates/blob/master/src/PlanInformation.php"
    click CIYML "https://github.com/xrubin/openexchangerates/blob/master/.github/workflows/ci.yml"
    click PHPUnit "https://github.com/xrubin/openexchangerates/blob/master/phpunit.xml"
    click TEST "https://github.com/xrubin/openexchangerates/blob/master/tests/OpenExchangeRatesApiTest.php"

    %% Styles
    classDef consumer fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef internal fill:#a2d1f2,stroke:#333,stroke-width:1px
    classDef external fill:#f2c79d,stroke:#333,stroke-width:1px
    classDef models fill:#d1f2a2,stroke:#333,stroke-width:1px
    classDef pipeline fill:#f2a2f2,stroke:#333,stroke-width:1px
```
