# paulobrazilian/payment-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/paulobrazilian/payment-management-system
- Repository: https://github.com/paulobrazilian/payment-management-system

## Overview

##### Inventory Service ("inventory")
- Purpose: Handles products and inventory management.
- Key components: Controllers (products_controller.ts), models (product.ts), services (product_service.ts), validators, and migrations related to products.
- Observations: Separation of concerns is evident with dedicated middleware, exception handling, and configuration files.

##### People Management Service ("peopleManagement")
- Purpose: Manages client data and operations associated with customers.
- Key components: Controllers (clients_controller.ts), models (client.ts), services (client_service.ts), validators, and migrations for client tables.
- Observations: Similar infrastructure to the inventory module indicates a design pattern keeping business domains decoupled.

##### Payment Tools Service ("tools")
- Purpose: Acts as the core payment management functionality by processing transactions using various payment gateways and coordinating integrations with the inventory and people management services.
- Key components: Controllers (payments_controller.ts, transactions_controller.ts), models (gateways.ts, transactions.ts, transaction_products.ts), and services that integrate with both the inventory and people management systems (gateway_service.ts, inventory_service.ts, people_management_service.ts).
- Observations: Contains enums, validators, and dedicated configuration files that facilitate gateway prioritization and transaction processing.

The README explicitly outlines that the API supports a multi-gateway approach where, if one payment gateway fails, the system will automatically fall back to another. This multi-gateway integration is most prominently handled by the tools service and is central to the system’s purpose.

A. Identify the Main Components:
- Inventory Service: Represent this as a microservice integrating with a MySQL database (using Lucid ORM) for managing products.
- Payment Tools Service: This is the orchestration layer for transactions that works with multiple external payment gateways. It includes payment, transaction, and gateway-related logic.
- Shared MySQL Database: Although the services might be using the same underlying database or separate ones, show the connection and how each service interacts with database components, including their migrations.

B. Define Relationships and Interactions:
- Sequential fallback logic by indicating that the Payment Tools Service will try one gateway and, on failure, proceed to the next.
- Optionally, include API endpoints or controllers as sub-components of each service to denote the entry points (e.g., /products, /clients, /payments).

C. Highlight Architectural Patterns:
- Microservices architecture: each major domain (inventory, people management, payments) is encapsulated in its own module.
- Use of AdonisJS conventions (controllers, middleware, services) that promote a clean, layered approach to request handling and business logic separation.
- Fallback mechanism for payment gateways as an important design principle built into the Payment Tools Service.

D. Include Relevant Technologies & Libraries:
- AdonisJS 5: Mark each service with the label “AdonisJS” to denote the framework.
- MySQL and Lucid ORM: Clearly label database interactions.
- TypeScript/JavaScript: Optionally note that each service leverages TypeScript for type safety.
- Testing frameworks (indicated by tests directories) and Postman integration, which supports quality assurance and API validation.

E. Diagramming Guidelines:
- Use clear labels for each component (e.g., “Inventory Service”, “People Management Service”, “Payment Tools Service”, “External Payment Gateway”).

- Since this is a full-stack RESTful API with a microservices flavor, make sure to emphasize the clear boundaries between services and the separation of concerns.
- Detail how the Payment Tools Service orchestrates communication between the inventory and people management services to process transactions, and how it interacts with multiple external payment gateways.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    DB["MySQL Database (Lucid ORM)"]:::database
    Gateway["External Payment Gateway"]:::external

    %% Inventory Service (AdonisJS)
    subgraph "Inventory Service (AdonisJS)"
        INV_CTRL["Products Controller"]:::controller
        INV_MODEL["Product Model"]:::model
        INV_SERVICE["Product Service"]:::service
        INV_VALIDATOR["Product Validator"]:::validator
        INV_MIGRATION["Products Migration"]:::migration
    end

    %% People Management Service (AdonisJS)
    subgraph "People Management Service (AdonisJS)"
        PM_CTRL["Clients Controller"]:::controller
        PM_MODEL["Client Model"]:::model
        PM_SERVICE["Client Service"]:::service
        PM_VALIDATOR["Client Validator"]:::validator
        PM_MIGRATION["Clients Migration"]:::migration
    end

    %% Payment Tools Service (AdonisJS)
    subgraph "Payment Tools Service (AdonisJS)"
        PT_CTRL1["Payments Controller"]:::controller
        PT_CTRL2["Transactions Controller"]:::controller
        PT_MODEL1["Gateways Model"]:::model
        PT_MODEL2["Transactions Model"]:::model
        PT_MODEL3["Transaction Products Model"]:::model
        PT_SERVICE1["Gateway Service"]:::service
        PT_SERVICE2["Inventory Service (Internal)"]:::service
        PT_SERVICE3["People Management Service (Internal)"]:::service
        PT_VALIDATOR1["Cart Validator"]:::validator
        PT_VALIDATOR2["Gateway Validator"]:::validator
        PT_VALIDATOR3["Process Payment Validator"]:::validator
        PT_VALIDATOR4["Transactions Validator"]:::validator
        PT_MIGRATION1["Gateways Migration"]:::migration
        PT_MIGRATION2["Transactions Migration"]:::migration
        PT_MIGRATION3["Transaction Products Migration"]:::migration
    end

    %% Relationships among components
    %% Internal communications within Inventory and People services
    INV_CTRL -->|"calls"| INV_SERVICE
    PM_CTRL -->|"calls"| PM_SERVICE
    PT_CTRL1 -->|"calls"| PT_SERVICE1
    PT_CTRL2 -->|"calls"| PT_SERVICE1

    %% Payment Tools orchestrates communication with Inventory and People Management
    PT_SERVICE2 -->|"validates"| INV_SERVICE
    PT_SERVICE3 -->|"verifies"| PM_SERVICE

    %% Payment Tools interacts with external payment gateway with fallback logic
    PT_SERVICE1 -->|"tries"| Gateway
    Gateway -->|"fallback"| PT_SERVICE1

    %% Database connections (shared MySQL)
    INV_MIGRATION --- DB
    PM_MIGRATION --- DB
    PT_MIGRATION1 --- DB
    PT_MIGRATION2 --- DB
    PT_MIGRATION3 --- DB

    %% Click Events for Inventory Service components
    click INV_CTRL "https://github.com/paulobrazilian/payment-management-system/blob/main/inventory/app/controllers/products_controller.ts"
    click INV_MODEL "https://github.com/paulobrazilian/payment-management-system/blob/main/inventory/app/models/product.ts"
    click INV_SERVICE "https://github.com/paulobrazilian/payment-management-system/blob/main/inventory/app/services/product_service.ts"
    click INV_VALIDATOR "https://github.com/paulobrazilian/payment-management-system/blob/main/inventory/app/validators/product_validator.ts"
    click INV_MIGRATION "https://github.com/paulobrazilian/payment-management-system/blob/main/inventory/database/migrations/1740519006864_create_products_table.ts"

    %% Click Events for People Management Service components
    click PM_CTRL "https://github.com/paulobrazilian/payment-management-system/blob/main/peopleManagement/app/controllers/clients_controller.ts"
    click PM_MODEL "https://github.com/paulobrazilian/payment-management-system/blob/main/peopleManagement/app/models/client.ts"
    click PM_SERVICE "https://github.com/paulobrazilian/payment-management-system/blob/main/peopleManagement/app/service/client_service.ts"
    click PM_VALIDATOR "https://github.com/paulobrazilian/payment-management-system/blob/main/peopleManagement/app/validators/client_validator.ts"
    click PM_MIGRATION "https://github.com/paulobrazilian/payment-management-system/blob/main/peopleManagement/database/migrations/1741035830723_create_clients_table.ts"

    %% Click Events for Payment Tools Service components
    click PT_CTRL1 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/controllers/payments_controller.ts"
    click PT_CTRL2 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/controllers/transactions_controller.ts"
    click PT_MODEL1 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/models/gateways.ts"
    click PT_MODEL2 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/models/transactions.ts"
    click PT_MODEL3 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/models/transaction_product.ts"
    click PT_SERVICE1 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/services/gateway_service.ts"
    click PT_SERVICE2 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/services/inventory_service.ts"
    click PT_SERVICE3 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/services/people_management_service.ts"
    click PT_VALIDATOR1 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/validators/cart_validator.ts"
    click PT_VALIDATOR2 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/validators/gateway_validator.ts"
    click PT_VALIDATOR3 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/validators/process_payment.ts"
    click PT_VALIDATOR4 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/app/validators/transactions_validator.ts"
    click PT_MIGRATION1 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/database/migrations/1741392420320_create_gateways_table.ts"
    click PT_MIGRATION2 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/database/migrations/1741392441393_create_transactions_table.ts"
    click PT_MIGRATION3 "https://github.com/paulobrazilian/payment-management-system/blob/main/tools/database/migrations/1741392452602_create_transaction_products_table.ts"

    %% Styles
    classDef controller fill:#f9a,stroke:#333,stroke-width:2px;
    classDef model fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#bfb,stroke:#333,stroke-width:2px;
    classDef validator fill:#ffb,stroke:#333,stroke-width:2px;
    classDef migration fill:#fdb,stroke:#333,stroke-width:2px;
    classDef database fill:#ddd,stroke:#333,stroke-width:2px,shape:cylinder;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px,shape:cloud;
```
