# sg-milad/ton-payment-system architecture

> Architecture diagram of the GitHub repository sg-milad/ton-payment-system, 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/sg-milad/ton-payment-system
- Repository: https://github.com/sg-milad/ton-payment-system

## Overview

##### Main Components
- API / Entry Point: The NestJS application is the central hub, starting at src/main.ts, which loads the application modules.
- Payment Module: Contains payment.controller.ts and payment.service.ts. It is responsible for handling incoming payment requests.
- TON Module: Includes ton.module.ts, ton.service.ts, and support components (DTOs, enums, constants, queues, and types). It encapsulates all TON-related logic including managing payment data and using queues for background processing.
- Wallet Module: Contains wallet.module.ts and wallet.service.ts. This module handles wallet generation and possibly consolidation of funds.
- Config Modules: Under src/configs, these files (app.config.ts, bullmq.config.ts, redis.config.ts, wallet.config.ts) provide configuration details for application settings, BullMQ (for queues), Redis, and wallet-specific parameters.
- Shared Services: The shared folder features helper functions and a Prisma module, which is used for data persistence (via src/shared/prisma). Prisma is critical as an ORM here.
- Infrastructure: Dockerfile, docker-compose.yml, and other environment & CI/CD files (.env.dev, GitHub workflows) define how the application is built and deployed.

##### Out Relationships and Interactions
- The API layer (bootstrapped via main.ts and the app.module.ts) mediates HTTP requests and directs them to respective modules (Payment, Ton, Wallet).
- The Payment Module likely invokes functions from both the Ton and Wallet Modules to handle the process of receiving payment requests, generating a new wallet address, and initiating fund consolidation.
- The TON Module processes blockchain-specific logic. It also handles messages/events using queues (supported by BullMQ configurations and files under src/ton/queues) to asynchronously process transactions.
- The Wallet Module manages wallet creation and may interact with external TON wallet services.
- The Shared Prisma Service ensures that all these modules persist or retrieve data from the database.
- Configuration files ensure that the necessary system parameters are centralized and modifiable (app config, Redis for caching/queueing, etc.).

##### Architectural Patterns/Design Principles
- Modular Architecture: The system is split into discrete modules (Payment, TON, Wallet) which promote separation of concerns.
- Dependency Injection: Standard in NestJS, ensuring that services (like Prisma, BullMQ) are injected where needed.
- Asynchronous Processing: Use of queues (BullMQ) to handle background tasks such as payment transaction processing.
- Containerization: Docker and docker-compose configurations indicate that the service is containerized and can run within a Docker ecosystem.
- API Documentation: Swagger integration (via src/shared/swagger.ts) is included to automatically document API endpoints.

##### Detailed Data Flow
- Start from when a user initiates a payment request which is handled by the Payment Controller.
- How the Payment Service coordinates this by calling:
- The TON Module to handle TON-specific computations/queues.
- The Wallet Module to generate or access wallet data.
- Finally, interactions with the database via the Prisma Service are depicted.
- How responses and asynchronous events (through BullMQ queues) are managed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        API["NestJS API / Entry"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        subgraph "Payment Module"
            PaymentController["Payment Controller"]:::payment
            PaymentService["Payment Service"]:::payment
            PaymentModule["Payment Module"]:::payment
        end
        subgraph "TON Module"
            TonService["TON Service"]:::ton
            TonModule["TON Module"]:::ton
            TonSupport["TON Supporting Components (DTOs,Enums,Constants,Queues,Types)"]:::ton
        end
        subgraph "Wallet Module"
            WalletService["Wallet Service"]:::wallet
            WalletModule["Wallet Module"]:::wallet
        end
    end

    %% Shared Services
    subgraph "Shared Services"
        Prisma["Prisma Service"]:::shared
        Helper["Helper Functions"]:::shared
        Swagger["Swagger Docs"]:::shared
    end

    %% Configurations
    subgraph "Configurations"
        AppConfig["App Config"]:::config
        BullMQConfig["BullMQ Config"]:::config
        RedisConfig["Redis Config"]:::config
        WalletConfig["Wallet Config"]:::config
        AdditionalConfig["Additional Config Options"]:::config
    end

    %% Infrastructure & External Dependencies
    subgraph "Infrastructure & External"
        Docker["Dockerfile & Container"]:::infra
        Env[".env.dev & Workflows"]:::infra
        QueueManager["Queue Manager (BullMQ)"]:::external
        Database["Database (via Prisma ORM)"]:::external
    end

    %% Connections - API & Business Logic
    API -->|"HTTP_Request"| PaymentController
    PaymentController -->|"calls"| PaymentService
    PaymentService -->|"delegates_to"| PaymentModule
    PaymentModule -->|"initiates"| TonModule
    PaymentModule -->|"initiates"| WalletModule

    %% Business Logic to Shared Services (Database Interactions)
    PaymentService -->|"saves_data"| Prisma
    TonService -->|"saves_data"| Prisma
    WalletService -->|"saves_data"| Prisma

    %% TON Module Asynchronous Processing
    TonService -->|"queues_transaction"| QueueManager

    %% API to API Documentation
    API -->|"generates_docs"| Swagger

    %% Shared Prisma to External Database
    Prisma -->|"DB_access"| Database

    %% Configuration injections
    AppConfig --> API
    AppConfig --> PaymentModule
    AppConfig --> TonModule
    AppConfig --> WalletModule

    BullMQConfig --> TonModule
    RedisConfig --> TonModule
    WalletConfig --> WalletModule
    AdditionalConfig --> PaymentModule
    AdditionalConfig --> TonModule
    AdditionalConfig --> WalletModule

    %% Styling Classes
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef payment fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef ton fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef wallet fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef shared fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef config fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef infra fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#333,stroke-width:2px;

    %% Click Events for API / Entry Point
    click API "https://github.com/sg-milad/ton-payment-system/blob/master/src/main.ts"

    %% Click Events for Payment Module
    click PaymentController "https://github.com/sg-milad/ton-payment-system/blob/master/src/payment/payment.controller.ts"
    click PaymentService "https://github.com/sg-milad/ton-payment-system/blob/master/src/payment/payment.service.ts"
    click PaymentModule "https://github.com/sg-milad/ton-payment-system/blob/master/src/payment/payment.module.ts"

    %% Click Events for TON Module
    click TonModule "https://github.com/sg-milad/ton-payment-system/blob/master/src/ton/ton.module.ts"
    click TonService "https://github.com/sg-milad/ton-payment-system/blob/master/src/ton/ton.service.ts"
    click TonSupport "https://github.com/sg-milad/ton-payment-system/tree/master/src/ton/dto"

    %% Click Events for Wallet Module
    click WalletModule "https://github.com/sg-milad/ton-payment-system/blob/master/src/wallet/wallet.module.ts"
    click WalletService "https://github.com/sg-milad/ton-payment-system/blob/master/src/wallet/wallet.service.ts"

    %% Click Events for Configurations
    click AppConfig "https://github.com/sg-milad/ton-payment-system/blob/master/src/configs/app.config.ts"
    click BullMQConfig "https://github.com/sg-milad/ton-payment-system/blob/master/src/configs/bullmq.config.ts"
    click RedisConfig "https://github.com/sg-milad/ton-payment-system/blob/master/src/configs/redis.config.ts"
    click WalletConfig "https://github.com/sg-milad/ton-payment-system/blob/master/src/configs/wallet.config.ts"
    click AdditionalConfig "https://github.com/sg-milad/ton-payment-system/blob/master/src/configs/config.module.options.ts"

    %% Click Events for Shared Services
    click Helper "https://github.com/sg-milad/ton-payment-system/blob/master/src/shared/helper/helper.ts"
    click Prisma "https://github.com/sg-milad/ton-payment-system/tree/master/src/shared/prisma"
    click Swagger "https://github.com/sg-milad/ton-payment-system/blob/master/src/shared/swagger.ts"

    %% Click Events for Infrastructure
    click Docker "https://github.com/sg-milad/ton-payment-system/tree/master/Dockerfile"
    click Env "https://github.com/sg-milad/ton-payment-system/blob/master/.env.dev"
    click QueueManager "https://github.com/sg-milad/ton-payment-system/tree/master/src/ton/queues"
```
