# shaxzodbek-uzb/pay-uz architecture

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

- Interactive diagram: https://gitdiagram.com/shaxzodbek-uzb/pay-uz
- Repository: https://github.com/shaxzodbek-uzb/pay-uz

## Overview

##### Project Type and Purpose
- This package is designed to integrate various payment gateways (e.g., Click, Oson, Payme, Paynet, Uzcard, and even Stripe) into an application. Its primary purpose is to simplify payment processing by providing drivers, controllers, models, and services for handling transactions.
- The README highlights how to set up routes for handling payment requests, redirecting users for payment, and handling callbacks from payment systems. There’s clearly an emphasis on a modular design that supports multiple payment providers.

##### File Structure
- Top-level directories and files such as the configuration (config), publishable payment scripts (publishable/Payments), and documentation (README.md) indicate a library/package meant to be integrated into an existing Laravel (or similar) application.
- The src directory is divided into:
- Http: Contains Controllers (e.g., ApiController, PaymentProjectController) and Classes that encapsulate driver implementations for each payment gateway. For instance, under src/Http/Classes you have dedicated folders for Click, Oson, Payme, Paynet, Stripe, and Uzcard.
- Models: Contains Eloquent models representing Payment Projects, Payment Systems, Transactions, etc.
- Services: Encapsulates business logic around payment processing, payment system parameter handling, and transaction management.
- Database: Migrations and seeds define tables for transactions, payment systems, payment system parameters, and payment projects.
- Resources: Contains assets, language files, and views which will be used for the UI portion (e.g., dashboards and merchant interfaces).
- Additional files like the Service Provider, Facade, and Traits indicate that the package is designed to be pluggable and extendable in a Laravel-like environment.

- Payment Gateway Drivers: Represented by the individual classes for Click, Oson, Payme, Paynet, Uzcard, and Stripe. This is the integration layer that communicates with external payment systems.
- Controllers: API/Request handling components such as ApiController, PaymentSystemController, TransactionController, etc.
- Services: Business logic components (PaymentService, TransactionService, and PaymentSystem Services) that process payments and handle business rules.
- Models: Represents the data layer (PaymentProject, PaymentSystem, Transaction, etc.) which interacts with the database.
- Configuration & Setup: The config directory and publishable files that configure the package behavior.
- Database: Migrations and seeds reflect the persistence layer for storing transactions and payment system configurations.
- Resources (Views/Assets): The blade templates, JavaScript, CSS, and other assets that form the customer and admin interfaces.
- Exception Handling: PaymentException and other error-handling classes can be a small but dedicated part of the architecture.

b. Relationships and Interactions:
- Incoming requests are routed via routes file (src/routes/web.php) to Controllers.
- Controllers then utilize Services to process payment requests.
- Services make use of Models to persist/retrieve data.
- Depending on the payment method selected, the system routes the call to the appropriate Gateway Driver (found in src/Http/Classes/*) where each driver encapsulates its specific requests/responses.
- Responses or callbacks from payment providers are routed back through defined endpoints, processed, and then trigger updates in the Models and database.
- The configuration files and publishable assets link into the workflow to provide customizable parameters.

c. Architectural Patterns and Design Principles:
- Modularity: Each payment gateway is implemented as a separate driver, implementing a common interface (indicated by BaseGateway.php and shared methods across drivers).
- MVC/MVCS: The separation between Controllers (for routing), Services (business logic), and Models (database abstraction) follows the typical MVC layout.
- Dependency Injection & Service Providers: The PayUzServiceProvider and Facade implementation ensure that components are injected and used in a decoupled way.
- Exception Handling: The PaymentException in the Http/Classes directory enforces proper error handling across payment processing workflows.

d. Relevant Technologies/Frameworks:
- PHP and Laravel (or Laravel-like structure) are central.
- Composer is used for package management.
- Testing with phpunit (as seen in the tests directory).
- Frontend assets (Blade, CSS, JavaScript) for view rendering.

◦ Controllers (API, Payment, Transaction)
◦ Services (PaymentService, TransactionService, PaymentSystemService)
◦ Models (PaymentProject, PaymentSystem, Transaction, etc.)
◦ Payment Gateway Drivers (Click, Oson, etc. with a common BaseGateway if needed)
◦ Configuration/Settings (config files, publishable assets)
◦ Database (migrations, seeds)
◦ Resources (Views, Assets)
◦ Data flow from HTTP requests → Controllers → Services → Models/Database.
◦ Outgoing calls from Services to external Payment Gateway Drivers.
◦ Callback flows from Payment Providers back to Controllers.
◦ Business Logic (Services and Models)
◦ Integration/Driver Layer (Payment Gateway classes)
◦ UI/Frontend (Views and Assets)
◦ Configuration and infrastructure (Config, Database, Publishing scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Routing Layer
    R["Routes"]:::routing

    %% Controller Layer
    subgraph "Controller Layer"
        C1["ApiController"]:::controller
        C2["PaymentProjectController"]:::controller
        C3["PaymentSystemController"]:::controller
        C4["TransactionController"]:::controller
        C5["PageController"]:::controller
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        %% Services
        S1["PaymentService"]:::service
        S2["PaymentSystemParamService"]:::service
        S3["PaymentSystemService"]:::service
        S4["TransactionService"]:::service
        %% Models
        M1["PaymentProject"]:::model
        M2["PaymentSystem"]:::model
        M3["PaymentSystemParam"]:::model
        M4["Transaction"]:::model
    end

    %% Integration Layer
    subgraph "Integration Layer"
        BG["BaseGateway"]:::gateway
        D1["Click"]:::gateway
        D2["Oson"]:::gateway
        D3["Payme"]:::gateway
        D4["Paynet"]:::gateway
        D5["Stripe"]:::gateway
        D6["Uzcard"]:::gateway
        E["PaymentException"]:::exception
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        CF["Config Files"]:::config
        PP["Publishable Payments"]:::config
        DP["Migrations"]:::database
        DS["Seeds"]:::database
        Rsc["Views & Assets"]:::resource
        SP["Service Provider"]:::provider
        F["Facade"]:::provider
        T["Payable Trait"]:::trait
    end

    %% Relationships - Routing to Controllers
    R -->|"routes_to"| C1
    R -->|"routes_to"| C2
    R -->|"routes_to"| C3
    R -->|"routes_to"| C4
    R -->|"routes_to"| C5

    %% Controllers call Services
    C1 -->|"calls"| S1
    C2 -->|"calls"| S2
    C3 -->|"calls"| S3
    C4 -->|"calls"| S4

    %% Controllers render UI from Resources
    C5 -->|"renders"| Rsc

    %% Services use Models
    S1 -->|"persists"| M1
    S2 -->|"persists"| M3
    S3 -->|"persists"| M2
    S4 -->|"persists"| M4

    %% Models connect to Database
    M1 -->|"stores_in"| DP
    M2 -->|"stores_in"| DP
    M3 -->|"stores_in"| DP
    M4 -->|"stores_in"| DP
    DP ---|"seeded_by"| DS

    %% Services call Integration (Payment Gateway Drivers)
    S1 -->|"calls"| BG
    BG -->|"delegates_to"| D1
    BG -->|"delegates_to"| D2
    BG -->|"delegates_to"| D3
    BG -->|"delegates_to"| D4
    BG -->|"delegates_to"| D5
    BG -->|"delegates_to"| D6
    BG -->|"handles_errors_with"| E

    %% Infrastructure: Service Provider and Facade integration
    SP -->|"injects_into"| C1
    SP -->|"injects_into"| S1
    F -->|"abstracts"| S1

    %% Infrastructure: Configuration used by Services and Controllers
    CF -->|"configures"| S1
    PP -->|"customizes"| C5

    %% Traits used by Controllers and Services
    T ---|"used_by"| C1
    T ---|"used_by"| S1

    %% Click Events for Component Mapping
    click R "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/routes/web.php"
    click C1 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Controllers/ApiController.php"
    click C2 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Controllers/PaymentProjectController.php"
    click C3 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Controllers/PaymentSystemController.php"
    click C4 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Controllers/TransactionController.php"
    click C5 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Controllers/PageController.php"
    click S1 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Services/PaymentService.php"
    click S2 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Services/PaymentSystemParamService.php"
    click S3 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Services/PaymentSystemService.php"
    click S4 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Services/TransactionService.php"
    click M1 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Models/PaymentProject.php"
    click M2 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Models/PaymentSystem.php"
    click M3 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Models/PaymentSystemParam.php"
    click M4 "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Models/Transaction.php"
    click CF "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/config/config.php"
    click PP "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/publishable/Payments"
    click DP "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/database/migrations"
    click DS "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/database/seeds"
    click Rsc "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/resources"
    click BG "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Classes/BaseGateway.php"
    click D1 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Click"
    click D2 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Oson"
    click D3 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Payme"
    click D4 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Paynet"
    click D5 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Stripe"
    click D6 "https://github.com/shaxzodbek-uzb/pay-uz/tree/master/src/Http/Classes/Uzcard"
    click E "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Http/Classes/PaymentException.php"
    click SP "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/PayUzServiceProvider.php"
    click F "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/PayUzFacade.php"
    click T "https://github.com/shaxzodbek-uzb/pay-uz/blob/master/src/Traits/Payable.php"

    %% Class Styles
    classDef routing fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef controller fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef model fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef gateway fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef exception fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef config fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef database fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef resource fill:#ede7f6,stroke:#5e35b1,stroke-width:2px;
    classDef provider fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px;
    classDef trait fill:#fce4ec,stroke:#d81b60,stroke-width:2px;
```
