# mewebstudio/pos architecture

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

- Interactive diagram: https://gitdiagram.com/mewebstudio/pos
- Repository: https://github.com/mewebstudio/pos

## Overview

##### Main Components of the System
- Client / Application Layer: Represents the consumer code that calls the library to “create” a POS gateway, send payment requests, receive and process responses.
- Factory & Configuration: The factories (e.g., PosFactory, AccountFactory, CryptFactory, Request/Response DataMapper Factories) together with the configuration files (pos_production.php, pos_test.php) encapsulate the instantiation of bank-specific gateway implementations.
- Data Mapping: Divided into RequestDataMapper and ResponseDataMapper – these components transform the request/response data between the standardized format used by the library and the proprietary formats expected or returned by each bank.
- Cryptography: Located in “src/Crypt”, this subsystem provides hashing and encryption mechanisms using various algorithms. It implements interfaces (like CryptInterface) and concrete classes (e.g., EstPosCrypt, GarantiPosCrypt) to correctly sign or verify transaction data.
- Entity: Classes under “src/Entity” (for Account and Card) are used to encapsulate the information needed to perform operations and store payment related data.
- HTTP Client: Although the library does not mandate a specific one, it makes use of PSR-18 implementations (with a Client under “src/Client/HttpClient.php”) to submit HTTP requests to the bank gateways.
- Event Dispatching and Logging: The library supports PSR-3 for logging and PSR-14 for event dispatching (see “src/Event” and the README’s discussion of event-driven hooks, such as the “Before3DFormHashCalculatedEvent”). This allows additional functionality or debugging across the transaction lifecycle.
- Exception Handling: “src/Exceptions” captures a variety of custom exceptions ensuring robust error handling throughout the payment process.
- Test & Examples: The “tests” directory confirms the unit and functional testing approach, while the “examples” folder shows practical implementations and how to integrate the library with different bank endpoints in real-world scenarios.

##### Relationships and Interactions
- The Client (or consuming application) first loads the configuration, then uses the Factory (PosFactory) to create a specific Gateway instance by injecting the appropriate Account (from “src/Entity/Account”) and configuration data.
- Once a Gateway is instantiated (e.g., GarantiPos, EstV3Pos), it processes a payment request. Here, the Gateway calls upon the appropriate Request Data Mapper to format the request properly and uses the Crypt module to generate any necessary signatures or hash values.
- After building the request, the library uses an HTTP Client (via PSR-18) to communicate with the bank’s API endpoints (which might be defined in the configuration).
- When a response is received, it flows back through a Response Data Mapper for normalization before being passed back (or converted) into a common format that the client application understands.
- During these processes, events may be dispatched (for example, to log or modify requests/responses), and exceptions may be thrown if something goes wrong. Factories and abstract base classes help ensure that any bank-specific differences are encapsulated in their respective components.

##### Architectural Patterns and Design Principles
- Use of the Factory Design Pattern to instantiate bank-specific gateway classes through one common interface.
- Strategy/Polymorphism: The implementation of multiple Crypt classes, DataMappers, and Gateways follows a polymorphic design allowing one to easily switch strategies (or payment models) without changing the client code.
- Separation of Concerns: The project cleanly separates concerns among configuration, HTTP communication, data mapping, cryptography, and error handling.
- Compliance with PSR Standards (PSR-3, PSR-14, PSR-18) demonstrates adherence to common PHP best practices for interoperability and extensibility.

##### Additional Notes Specific to This Project
- That the “examples” and “tests” directories serve as practical verification points and confirm that the implementations follow the unified API.
- That the system encapsulates both request and response normalization so that client code remains the same regardless of which bank is being used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    C["Client / Application Layer"]:::client

    %% Factory & Configuration Cluster
    subgraph "Factory & Configuration"
        F["Factory (PosFactory,AccountFactory,CryptFactory)"]:::factory
        CP["Configuration: Production"]:::factory
        CT["Configuration: Test"]:::factory
    end

    %% Library Core Components
    G["Gateway Implementations"]:::gateway
    RDM["Request Data Mapper"]:::data
    CRY["Cryptography"]:::crypt
    PR["Prepare Request"]:::data
    HTTP["HTTP Client"]:::http
    RSPD["Response Data Mapper"]:::data
    ENT_ACC["Entity: Account"]:::entity
    ENT_CARD["Entity: Card"]:::entity
    EVT["Event Dispatching&Logging"]:::events
    EXC["Exception Handling"]:::exception

    %% Test & Examples Cluster
    subgraph "Test & Examples"
        E["Examples"]:::test
        T["Tests"]:::test
    end

    %% Connections / Data Flow
    C --> F
    F --> CP
    F --> CT
    F --> G
    G --> RDM
    G --> CRY
    RDM --> PR
    CRY --> PR
    PR --> HTTP
    HTTP --> RSPD
    RSPD --> G
    G --> ENT_ACC
    G --> ENT_CARD
    G --> EVT
    G --> EXC
    C -->|"runs"| E
    C -->|"runs"| T

    %% Click Events
    click C "https://github.com/mewebstudio/pos/tree/master/examples"
    click F "https://github.com/mewebstudio/pos/tree/master/src/Factory"
    click CP "https://github.com/mewebstudio/pos/blob/master/config/pos_production.php"
    click CT "https://github.com/mewebstudio/pos/blob/master/config/pos_test.php"
    click G "https://github.com/mewebstudio/pos/tree/master/src/Gateways"
    click RDM "https://github.com/mewebstudio/pos/tree/master/src/DataMapper/RequestDataMapper"
    click RSPD "https://github.com/mewebstudio/pos/tree/master/src/DataMapper/ResponseDataMapper"
    click CRY "https://github.com/mewebstudio/pos/tree/master/src/Crypt"
    click ENT_ACC "https://github.com/mewebstudio/pos/tree/master/src/Entity/Account"
    click ENT_CARD "https://github.com/mewebstudio/pos/tree/master/src/Entity/Card"
    click HTTP "https://github.com/mewebstudio/pos/blob/master/src/Client/HttpClient.php"
    click EVT "https://github.com/mewebstudio/pos/tree/master/src/Event"
    click EXC "https://github.com/mewebstudio/pos/tree/master/src/Exceptions"
    click E "https://github.com/mewebstudio/pos/tree/master/examples"
    click T "https://github.com/mewebstudio/pos/tree/master/tests"

    %% Styles
    classDef client fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef factory fill:#a2d2ff,stroke:#333,stroke-width:2px;
    classDef gateway fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef data fill:#ffcb77,stroke:#333,stroke-width:2px;
    classDef crypt fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef entity fill:#ffc6ff,stroke:#333,stroke-width:2px;
    classDef http fill:#ffafcc,stroke:#333,stroke-width:2px;
    classDef events fill:#fdffb6,stroke:#333,stroke-width:2px;
    classDef exception fill:#d0efff,stroke:#333,stroke-width:2px;
    classDef test fill:#cdb4db,stroke:#333,stroke-width:2px;
```
