# whatarmy/fedexrest architecture

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

- Interactive diagram: https://gitdiagram.com/whatarmy/fedexrest
- Repository: https://github.com/whatarmy/fedexrest

## Overview

The project is a PHP library that provides a convenient wrapper for FedEx’s new Rest API services. It is not a full application per se but rather an integration library meant to simplify interaction with FedEx endpoints. The library is structured to support multiple service domains such as Shipping, Pickup, Tracking, Address Validation, Rates, and more. It is built using standard PHP project conventions (composer, PHPUnit for testing, and GitHub actions for CI), and uses object‐oriented design to encapsulate different functionalities.

##### Main Components
- Authorization Module – Found under src/FedexRest/Authorization, this handles the oAuth process (authorizing the client and caching the token).
- Entities – Located in src/FedexRest/Entity and subdirectories (e.g., Address, CustomerReference, DangerousGoodsDetail, etc.), these represent data structures exchanged among services.
- Services – The core function of the library is implemented here; each service group (like AddressValidation, LocationSearch, Pickup, Ship, Track, Rates) has its own set of classes and subcomponents.
– Each service is built upon a common abstraction (see AbstractRequest and RequestInterface) to standardize operations.
- Exceptions – Organized in src/FedexRest/Exceptions and under certain services (for example, in the Ship service), these define error conditions specific to each API.
- Utility and Traits – Additional helper classes in src (Utils.php) and traits (rawable.php; switchableEnv.php) provide shared functionality.
- Testing – The tests directory mirrors the structure of the src directory and clearly shows how each component is tested.

##### Relationships and Interactions
- The Authorization component is called by the service classes to obtain an access token (which is needed for every API request).
- Service classes use the Entity classes to build request payloads and parse responses.
- The AbstractRequest (and RequestInterface) defines common behavior and enforces consistency across different service implementations.
- Error-handling is done via dedicated Exception classes which are thrown when required parameters (like access token, account number, etc.) are missing.
- The library’s clients (e.g., user code) interact with each service by instantiating service classes and using setter methods that accept Entity objects.
- Testing modules in the tests directory show integration points and confirm the behavior of these interactions.

##### Architectural Patterns/Design Principles
- Encapsulation – Different API components (Ship, Track, Pickup, etc.) are encapsulated individually.
- Builder/Fluent Interfaces – Observe how the library uses a fluent interface (chainable setter methods) to configure requests.
- Inheritance/Abstraction – AbstractRequest and interface definitions ensure that services share common request behaviors.
- Dependency Inversion – The services depend on common contracts (RequestInterface) rather than concrete implementations.

##### Relevant Technologies and Frameworks
- PHP (object-oriented PHP, composer for dependency management)
- PHPUnit for testing of components
- GitHub Actions (via the workflow files in .github/workflows) for CI/CD
- The library connects with external FedEx Rest API endpoints.

##### Instructing the Principal Software Engineer
– Authorization (oAuth workflow)
– Entities (all data models, e.g., Address, Weight, etc.)
– Service Modules (group them by API, such as Ship, Track, Rate, Address Validation, etc.)
– Abstract Components (AbstractRequest, RequestInterface)
– Exception Handling (list the exception classes logically related to services)
– External FedEx Rest API (as an external system the library interacts with)
– From client code into the Library’s API service component.
– From Services to Authorization to obtain tokens.
– From Services to Entities as they build the payloads.
– From Services to external FedEx API (HTTP calls/response).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client Code"):::client

    subgraph "Library Core"
        Authorization("Authorization Module"):::internal
        Entities("Entities"):::internal

        subgraph "Common Components"
            AbsReq("AbstractRequest"):::internal
            ReqInt("RequestInterface"):::internal
        end

        subgraph "Utility & Helpers"
            Utility("Utility Functions"):::internal
            Traits("Traits"):::internal
        end

        subgraph "Exception Handling"
            GenEx("General Exceptions"):::internal
            ShipEx("Ship Service Exceptions"):::internal
        end

        subgraph "Services"
            AddressValid("Address Validation Service"):::service
            LocSearch("Location Search Service"):::service
            Pickup("Pickup Service"):::service
            Rates("Rates Service"):::service
            Ship("Ship Service"):::service
            Track("Track Service"):::service
        end
    end

    ExternalFedEx("FedEx Rest API"):::external

    subgraph "Testing & CI"
        Testing("Testing (PHPUnit)"):::testing
        CI("CI (GitHub Actions)"):::testing
    end

    %% Client calls service modules
    Client -->|"calls"| AddressValid
    Client -->|"calls"| LocSearch
    Client -->|"calls"| Pickup
    Client -->|"calls"| Rates
    Client -->|"calls"| Ship
    Client -->|"calls"| Track

    %% Service modules obtain token from Authorization Module
    AddressValid -->|"auth_token"| Authorization
    LocSearch -->|"auth_token"| Authorization
    Pickup -->|"auth_token"| Authorization
    Rates -->|"auth_token"| Authorization
    Ship -->|"auth_token"| Authorization
    Track -->|"auth_token"| Authorization

    %% Service modules use Entities to build payloads
    AddressValid -->|"payload"| Entities
    LocSearch -->|"payload"| Entities
    Pickup -->|"payload"| Entities
    Rates -->|"payload"| Entities
    Ship -->|"payload"| Entities
    Track -->|"payload"| Entities

    %% Service modules extend and implement common abstractions
    AddressValid -->|"inherits"| AbsReq
    LocSearch -->|"inherits"| AbsReq
    Pickup -->|"inherits"| AbsReq
    Rates -->|"inherits"| AbsReq
    Ship -->|"inherits"| AbsReq
    Track -->|"inherits"| AbsReq

    AddressValid -->|"implements"| ReqInt
    LocSearch -->|"implements"| ReqInt
    Pickup -->|"implements"| ReqInt
    Rates -->|"implements"| ReqInt
    Ship -->|"implements"| ReqInt
    Track -->|"implements"| ReqInt

    %% Service modules throw exceptions for error conditions
    AddressValid -->|"throws"| GenEx
    LocSearch -->|"throws"| GenEx
    Pickup -->|"throws"| GenEx
    Rates -->|"throws"| GenEx
    Ship -->|"throws"| ShipEx
    Track -->|"throws"| GenEx

    %% Service modules call external FedEx API
    AddressValid -->|"requests"| ExternalFedEx
    LocSearch -->|"requests"| ExternalFedEx
    Pickup -->|"requests"| ExternalFedEx
    Rates -->|"requests"| ExternalFedEx
    Ship -->|"requests"| ExternalFedEx
    Track -->|"requests"| ExternalFedEx

    %% Testing validates Library Core components
    Testing -->|"tests"| Authorization
    Testing -->|"tests"| Entities
    Testing -->|"tests"| AbsReq
    Testing -->|"tests"| ReqInt
    Testing -->|"tests"| AddressValid
    Testing -->|"tests"| LocSearch
    Testing -->|"tests"| Pickup
    Testing -->|"tests"| Rates
    Testing -->|"tests"| Ship
    Testing -->|"tests"| Track
    Testing -->|"tests"| GenEx
    Testing -->|"tests"| ShipEx

    %% CI runs the tests
    CI -->|"runs"| Testing

    %% Click Events
    click Authorization "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Authorization/Authorize.php"
    click Entities "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Entity"
    click AddressValid "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Services/AddressValidation/AddressValidation.php"
    click LocSearch "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Services/LocationSearch"
    click Pickup "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Services/Pickup"
    click Rates "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Services/Rates/CreateRatesRequest.php"
    click Ship "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Services/Ship"
    click Track "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Services/Track/TrackByTrackingNumberRequest.php"
    click AbsReq "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Services/AbstractRequest.php"
    click ReqInt "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Services/RequestInterface.php"
    click GenEx "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Exceptions"
    click ShipEx "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Services/Ship/Exceptions"
    click Utility "https://github.com/whatarmy/fedexrest/blob/develop/src/FedexRest/Utils.php"
    click Traits "https://github.com/whatarmy/fedexrest/tree/develop/src/FedexRest/Traits"
    click Testing "https://github.com/whatarmy/fedexrest/tree/develop/tests"
    click CI "https://github.com/whatarmy/fedexrest/blob/develop/.github/workflows/ci.yml"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fbb,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffc,stroke:#333,stroke-width:2px;
```
