Architecture Overview

Purpose and Scope

This document explains the overall architecture of the Hypervel API Client system, including its layered design, core components, and how they interact to execute HTTP requests. It provides a technical overview of the component relationships, data flow, and architectural patterns used throughout the codebase.

For details on specific components, see:

• ApiClient configuration and entry point: 4.3
• PendingRequest orchestration: 4.4
• Request/response building: 4.5, 4.6, 4.7
• Middleware system: 7.1

For practical usage information, see 5 (Making Requests) and 6 (Response Handling).

---

Layered Architecture

The API client follows a layered architecture pattern with clear separation of concerns:

Sources: src/ApiClient.php1-116 src/PendingRequest.php1-342 src/ApiRequest.php1-241 src/ApiResponse.php1-67 src/ApiResource.php1-147

Layer Responsibilities

Layer	Components	Responsibility
Configuration	ApiClient, DataObject	Stores configuration, middleware definitions, and resource class mappings
Request Building	PendingRequest, ApiRequest	Orchestrates request lifecycle, builds PSR-7 requests with fluent API
Middleware	Pipeline, middleware arrays	Provides interception points for request/response transformation
Transport	ClientPendingRequest, Http facade	Executes HTTP requests via Guzzle, handles connection exceptions
Response Processing	ApiResponse, ApiResource	Wraps PSR-7 responses, provides data access interfaces

Sources: src/ApiClient.php14-116 src/PendingRequest.php22-62 src/ApiRequest.php12-241

---

Core Component Architecture

The following diagram maps system components to their concrete class implementations:

Sources: src/ApiClient.php14-116 src/PendingRequest.php22-342 src/ApiRequest.php12-241 src/ApiResponse.php10-67 src/ApiResource.php18-147

Component Importance Hierarchy

Based on interconnectedness and usage frequency:

1. PendingRequest (Importance: 12.66) - Central orchestrator at src/PendingRequest.php

   • Manages entire request lifecycle
   • Coordinates middleware execution
   • Transforms responses to resources

2. ApiRequest (Importance: 10.44) - Request builder at src/ApiRequest.php

   • Builds PSR-7 compliant requests
   • Provides fluent configuration API
   • Handles content type negotiation

3. ApiClient (Importance: 6.66) - Entry point at src/ApiClient.php

   • Configuration container
   • Factory for PendingRequest instances
   • Middleware configuration hub

4. ApiResource (Importance: 4.70) - Data container at src/ApiResource.php

   • Final response representation
   • Array/object access to data
   • JSON serialization support

5. ApiResponse (Importance: 2.70) - Response wrapper at src/ApiResponse.php

   • Mutable PSR-7 response wrapper
   • Context management support

Sources: High-level system architecture diagrams provided, src/PendingRequest.php1-342 src/ApiRequest.php1-241 src/ApiClient.php1-116

---

Request Lifecycle Flow

The following sequence diagram shows the complete request execution path with specific method calls:

Sources: src/PendingRequest.php175-291 src/ApiClient.php41-45 src/ApiRequest.php218-224 src/ApiResponse.php10-67 src/ApiResource.php87-90

Key Lifecycle Stages

Stage	Entry Point	Exit Point	Key Operations
Method Interception	ApiClient::__call() line 41	PendingRequest::get() line 175	Magic method delegation
Request Building	PendingRequest::sendRequest() line 265	ApiRequest::toPsrRequest() line 218	PSR-7 request construction
Request Middleware	PendingRequest::handleMiddlewareRequest() line 293	Modified ApiRequest	Pipeline execution line 295-298
HTTP Execution	ClientPendingRequest->get() line 278	Raw response	Guzzle HTTP client
Response Wrapping	new ApiResponse() line 284	Wrapped response	PSR-7 response wrapper
Response Middleware	PendingRequest::handleMiddlewareResponse() line 301	Modified ApiResponse	Pipeline execution line 303-306
Resource Creation	ApiResource::make() line 290	ApiResource instance	Static factory method line 87

Sources: src/PendingRequest.php265-291 src/ApiRequest.php218-224 src/ApiResponse.php10-67

---

Component Dependencies

The dependency graph shows how components depend on each other and external packages:

Sources: src/ApiClient.php1-116 src/PendingRequest.php1-342 src/ApiRequest.php1-241 src/ApiResponse.php1-67 src/ApiResource.php1-147

Dependency Analysis

External Package Dependencies:

• hypervel/http-client - Provides base classes and HTTP execution

  • ClientPendingRequest used at src/PendingRequest.php47
  • Request used at src/PendingRequest.php10
  • Extended by ApiRequest at src/ApiRequest.php12
  • Extended by ApiResponse at src/ApiResponse.php10

• hypervel/support - Provides utilities and infrastructure

  • Pipeline used at src/PendingRequest.php12-61
  • Http facade used at src/PendingRequest.php11-334
  • DataObject used at src/ApiClient.php7-19

• PSR-7 - HTTP message interface standards

  • RequestInterface returned at src/ApiRequest.php217-224
  • ResponseInterface used throughout ApiResponse
  • Ensures interoperability with PSR-7 ecosystem

Sources: src/PendingRequest.php7-12 src/ApiRequest.php7-10 src/ApiResponse.php7-8

---

Architectural Patterns

1. Fluent Interface Pattern

All request and response classes implement method chaining for configuration:

Implementation:

• Methods return static at src/PendingRequest.php71-137
• Methods return static at src/ApiRequest.php28-94
• Enables readable, chainable API calls

Sources: src/PendingRequest.php67-167 src/ApiRequest.php24-213

2. Factory Pattern

Static factory methods create instances with proper initialization:

• ApiResource::make() at src/ApiResource.php87-90
• PendingRequest created by ApiClient::getClient() at src/ApiClient.php112-115

Sources: src/ApiResource.php87-90 src/ApiClient.php112-115

3. Proxy Pattern

Magic methods delegate calls to underlying objects:

• ApiClient::__call() delegates to PendingRequest at src/ApiClient.php41-45
• PendingRequest::__call() delegates to ClientPendingRequest at src/PendingRequest.php257-263
• ApiResource::__call() forwards to ApiResponse at src/ApiResource.php63-72

Sources: src/ApiClient.php41-45 src/PendingRequest.php257-263 src/ApiResource.php63-72

4. Pipeline Pattern

Middleware execution uses pipeline for sequential processing:

Implementation:

• Request pipeline at src/PendingRequest.php295-298
• Response pipeline at src/PendingRequest.php303-306
• Uses Pipeline from hypervel/support at src/PendingRequest.php12-61

Sources: src/PendingRequest.php293-307

5. Template Method Pattern

Generic types ensure type safety across the request lifecycle:

• ApiClient<TConfig, TResource> at src/ApiClient.php10-11
• PendingRequest<TResource> at src/PendingRequest.php19
• Type propagation ensures compile-time safety

Sources: src/ApiClient.php10-14 src/PendingRequest.php19-29

---

PSR-7 Compliance

The architecture maintains PSR-7 compatibility throughout the request/response lifecycle:

Component	PSR-7 Method	Location
ApiRequest	toPsrRequest(): RequestInterface	src/ApiRequest.php217-224
ApiResponse	toPsrResponse(): ResponseInterface	Inherited from HttpClientResponse
Middleware	Receives PSR-7 wrapped objects	src/PendingRequest.php273-284
HTTP Client	Accepts/returns PSR-7	src/PendingRequest.php277

Immutability Pattern:

• PSR-7 objects are immutable
• ApiRequest and ApiResponse provide mutable wrappers
• Changes tracked and applied before conversion at src/ApiRequest.php219-224

Sources: src/ApiRequest.php217-241 src/ApiResponse.php10-67 src/PendingRequest.php272-278

---

Context Management

The HasContext trait provides metadata storage across the lifecycle:

Usage:

• Applied to ApiRequest at src/ApiRequest.php14
• Applied to ApiResponse at src/ApiResponse.php12
• Middleware receives context at src/PendingRequest.php296-304

Sources: src/ApiRequest.php14 src/ApiResponse.php12 src/PendingRequest.php296-304

---

Summary

The Hypervel API Client implements a layered architecture with five distinct layers, orchestrated by the PendingRequest class. The design emphasizes:

1. Clear separation of concerns through layer boundaries
2. PSR-7 compliance for interoperability
3. Extensibility via middleware pipelines
4. Type safety using PHP generics
5. Fluent interfaces for readable API consumption

The architecture enables developers to create custom API clients by extending ApiClient and customizing configuration, middleware, and resource classes while maintaining a consistent request lifecycle.

Sources: All files in src/ directory