# fontis/auspost-api-php architecture

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

- Interactive diagram: https://gitdiagram.com/fontis/auspost-api-php
- Repository: https://github.com/fontis/auspost-api-php

## Overview

##### Project Type Analysis
This is a PHP API client library that interfaces with Australia Post's web services, specifically focusing on postage calculation and postcode search services. It's built using Guzzle (HTTP client) and follows a well-structured object-oriented approach.

##### Main Components

A. Core Components:
- Main Client (Auspost.php)
- HTTP Client Layer
- API Services Layer
- Models Layer
- Exception Handling

B. Service Domains:
- Domestic Postage Services
- Letter Services
- Parcel Services
- Postcode Services
- International Postage Services
- Letter Services
- Parcel Services
- Country Services

##### Top Level (Client Interface)
- [External Application] → [Auspost Main Client]

##### Middle Layer (Service Layer)
- [HTTP Client Layer]
- Configurator
- RequestBuilder
- HttpApi

- [Domestic Services]          [International Services]
- Letter Services         ├── Letter Services
- Parcel Services         ├── Parcel Services
- Postcode Services       └── Country Services

##### Model Layer (Bottom)
- [Model Layer]
- Collections
- Enums
- Entity Models

##### Specific Elements
- External API endpoint connection
- Guzzle HTTP client integration
- Service calculation flow
- Model relationships
- Exception handling paths

##### Client Flow
- External App → Auspost Client → HTTP Client → Australia Post API

##### Service Pattern
- Service Request → Validation → HTTP Client → Response Processing → Model Hydration

##### Error Handling
- Exception Layer
- EmptyCollection
- EmptyServiceResponse
- EndpointServiceError
- InvalidArgument
- ParseJsonError

Level of Detail:
- Keep high-level components visible at first glance
- Use expandable/collapsible sections for service details
- Notes for important configuration requirements

## Diagram (Mermaid)

```mermaid
graph TB
    %% Main Client Interface
    Client["External Application"]
    AusPost["Auspost Client"]:::client
    click AusPost "https://github.com/fontis/auspost-api-php/blob/master/src/Auspost.php"

    %% HTTP Layer
    subgraph HTTP["HTTP Client Layer"]
        Config["Configurator"]:::http
        ReqBuilder["Request Builder"]:::http
        HttpApi["HTTP API"]:::http
    end
    click Config "https://github.com/fontis/auspost-api-php/blob/master/src/HttpClient/Configurator.php"
    click ReqBuilder "https://github.com/fontis/auspost-api-php/blob/master/src/HttpClient/RequestBuilder.php"
    click HttpApi "https://github.com/fontis/auspost-api-php/blob/master/src/HttpClient/HttpApi.php"

    %% Service Domains
    subgraph Services["Service Layer"]
        subgraph Domestic["Domestic Services"]
            DLetter["Letter Services"]
            DParcel["Parcel Services"]
            DPostcode["Postcode Services"]
        end
        subgraph International["International Services"]
            ILetter["Letter Services"]
            IParcel["Parcel Services"]
            ICountry["Country Services"]
        end
    end
    click DLetter "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/Domestic/Letter"
    click DParcel "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/Domestic/Parcel"
    click DPostcode "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/Domestic/Postcode"
    click ILetter "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/International/Letter"
    click IParcel "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/International/Parcel"
    click ICountry "https://github.com/fontis/auspost-api-php/tree/master/src/Api/Postage/International/Country"

    %% Model Layer
    subgraph Models["Model Layer"]
        BaseEnum["Base Enum"]:::model
        Collections["Collections"]:::model
        Entities["Entity Models"]:::model
        ServiceEnums["Service Enums"]:::model
    end
    click BaseEnum "https://github.com/fontis/auspost-api-php/blob/master/src/Model/Enum.php"
    click Collections "https://github.com/fontis/auspost-api-php/blob/master/src/Model/Postage/CostCollection.php"
    click Entities "https://github.com/fontis/auspost-api-php/blob/master/src/Model/Postage/Service.php"
    click ServiceEnums "https://github.com/fontis/auspost-api-php/blob/master/src/Model/Postage/Enum/ServiceCode.php"

    %% Exception Handling
    subgraph Exceptions["Exception Layer"]
        EmptyCol["Empty Collection"]:::error
        EmptyResp["Empty Service Response"]:::error
        EndpointErr["Endpoint Service Error"]:::error
        InvalidArg["Invalid Argument"]:::error
        ParseErr["Parse JSON Error"]:::error
    end
    click EmptyCol "https://github.com/fontis/auspost-api-php/blob/master/src/Exception/EmptyCollection.php"
    click EmptyResp "https://github.com/fontis/auspost-api-php/blob/master/src/Exception/EmptyServiceResponse.php"
    click EndpointErr "https://github.com/fontis/auspost-api-php/blob/master/src/Exception/EndpointServiceError.php"
    click InvalidArg "https://github.com/fontis/auspost-api-php/blob/master/src/Exception/InvalidArgument.php"
    click ParseErr "https://github.com/fontis/auspost-api-php/blob/master/src/Exception/ParseJsonError.php"

    %% Validation
    Validation["Validation Helper"]:::helper
    click Validation "https://github.com/fontis/auspost-api-php/blob/master/src/Helper/Validation.php"

    %% External API
    AusPostAPI["Australia Post API"]:::external

    %% Relationships
    Client --> AusPost
    AusPost --> HTTP
    HTTP --> AusPostAPI
    HTTP --> Services
    Services --> Models
    Services --> Exceptions
    Services --> Validation
    Models --> Exceptions

    %% Styling
    classDef client fill:#2374ab
    classDef http fill:#48a9a6
    classDef service fill:#e4572e
    classDef model fill:#ffc914
    classDef error fill:#db3a34
    classDef helper fill:#8789c0
    classDef external fill:#c0c0c0

    %% Legend
    subgraph Legend
        L1["Client Interface"]:::client
        L2["HTTP Layer"]:::http
        L3["Services"]:::service
        L4["Models"]:::model
        L5["Exceptions"]:::error
        L6["Helpers"]:::helper
        L7["External"]:::external
    end
```
