# mamangrust/payment-gateway-grpc architecture

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

- Interactive diagram: https://gitdiagram.com/mamangrust/payment-gateway-grpc
- Repository: https://github.com/mamangrust/payment-gateway-grpc

## Overview

##### Main System Components

a) Client-Facing Layer:
- REST API (Echo Framework)
- gRPC Server
- Authentication/Authorization Middleware

b) Core Services Layer:
- Auth Service
- User Service
- Card Service
- Merchant Service
- Transaction Service
- Transfer Service
- TopUp Service
- Withdraw Service
- Saldo Service

c) Data Layer:
- PostgreSQL Database
- Migration System

##### Architectural Patterns to Highlight

The project follows a clean architecture pattern with clear separation of concerns:
- Handler Layer (internal/handler/api and internal/handler/gapi)
- Service Layer (internal/service)
- Repository Layer (internal/repository)
- Domain Layer (internal/domain)

**┌─────────────────────────────────────────────────────────┐**
- Client Applications                   │
- (Mobile Apps, Frontend Apps, External Integrations)   │
- ┘
- ↓ ↑
**┌─────────────────────────────────────────────────────────┐**
- Gateway Layer                        │
- ┌───────────────┐              ┌──────────────────┐   │
- REST API    │              │   gRPC Server    │   │
- (Echo)       │              │                  │   │
- ┘              └──────────────────┘   │
- ┘
- ↓ ↑
**┌─────────────────────────────────────────────────────────┐**
- Middleware Layer                      │
- Auth Middleware | Role Middleware | API Key          │
- ┘
- ↓ ↑
**┌─────────────────────────────────────────────────────────┐**
- Service Layer                        │
- ┌────────────┐ ┌────────────┐ ┌────────────────────┐  │
- Auth Service│ │User Service│ │Transaction Service │  │
- ┘ └────────────┘ └────────────────────┘  │
- ┌────────────┐ ┌────────────┐ ┌────────────────────┐  │
- Card Service│ │Merchant Svc│ │Transfer Service    │  │
- ┘ └────────────┘ └────────────────────┘  │
- ┘
- ↓ ↑
**┌─────────────────────────────────────────────────────────┐**
- Repository Layer                      │
- (Database Access Layer with SQL Queries)         │
- ┘
- ↓ ↑
**┌─────────────────────────────────────────────────────────┐**
- Database Layer                        │
- PostgreSQL                         │
- ┘

##### Additional Elements

a) External Components:
- Authentication system (JWT)
- API Key validation
- Database migrations

b) Cross-Cutting Concerns:
- Logging system
- Error handling
- Data validation

##### Important Relationships
- Client → API Gateway (REST/gRPC)
- API Gateway → Middleware → Services
- Services → Repositories
- Repositories → Database
- Cross-service communication patterns

##### Technical Details to Note
- Protocol Buffers definitions (pkg/proto)
- Database migrations (pkg/database/migrations)
- Test coverage (tests/integration_test, tests/unit_test)
- Configuration management (.env, docker.env)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Clients
        C1[Mobile Apps]:::client
        C2[Frontend Apps]:::client
        C3[External Integrations]:::client
    end

    subgraph Gateway
        REST["REST API (Echo)"]:::gateway
        GRPC["gRPC Server"]:::gateway
    end

    subgraph Middleware
        AUTH_MID[Authentication Middleware]:::middleware
        ROLE_MID[Role Middleware]:::middleware
        APIKEY_MID[API Key Middleware]:::middleware
    end

    subgraph Services
        AUTH_SVC[Auth Service]:::service
        USER_SVC[User Service]:::service
        CARD_SVC[Card Service]:::service
        MERCH_SVC[Merchant Service]:::service
        TRANS_SVC[Transaction Service]:::service
        TRANSFER_SVC[Transfer Service]:::service
        TOPUP_SVC[TopUp Service]:::service
        WITHDRAW_SVC[Withdraw Service]:::service
        SALDO_SVC[Saldo Service]:::service
    end

    subgraph "Data Access"
        REPO[Repository Layer]:::repo
        DOMAIN[Domain Models]:::domain
        QUERIES[Database Queries]:::queries
        SCHEMA[Database Schema]:::schema
    end

    subgraph Database
        POSTGRES[(PostgreSQL)]:::database
        MIGRATIONS[Migration System]:::database
    end

    C1 & C2 & C3 --> REST & GRPC
    REST & GRPC --> AUTH_MID & ROLE_MID & APIKEY_MID
    AUTH_MID & ROLE_MID & APIKEY_MID --> AUTH_SVC & USER_SVC & CARD_SVC & MERCH_SVC & TRANS_SVC & TRANSFER_SVC & TOPUP_SVC & WITHDRAW_SVC & SALDO_SVC
    AUTH_SVC & USER_SVC & CARD_SVC & MERCH_SVC & TRANS_SVC & TRANSFER_SVC & TOPUP_SVC & WITHDRAW_SVC & SALDO_SVC --> REPO
    REPO --> DOMAIN
    REPO --> QUERIES
    QUERIES --> SCHEMA
    SCHEMA --> POSTGRES
    MIGRATIONS --> POSTGRES

    %% Click Events
    click REST "https://github.com/MamangRust/payment-gateway-grpc/tree/main/internal/handler/api/"
    click GRPC "https://github.com/MamangRust/payment-gateway-grpc/tree/main/internal/handler/gapi/"
    click AUTH_MID "https://github.com/MamangRust/payment-gateway-grpc/tree/main/internal/middlewares/"
    click AUTH_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/authService.go"
    click USER_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/userService.go"
    click CARD_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/cardService.go"
    click MERCH_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/merchantService.go"
    click TRANS_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/transactionService.go"
    click TRANSFER_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/transferService.go"
    click TOPUP_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/topupService.go"
    click WITHDRAW_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/withdrawService.go"
    click SALDO_SVC "https://github.com/MamangRust/payment-gateway-grpc/blob/main/internal/service/saldoService.go"
    click POSTGRES "https://github.com/MamangRust/payment-gateway-grpc/tree/main/pkg/database/"
    click MIGRATIONS "https://github.com/MamangRust/payment-gateway-grpc/tree/main/pkg/database/migrations/"
    click DOMAIN "https://github.com/MamangRust/payment-gateway-grpc/tree/main/internal/domain/"
    click REPO "https://github.com/MamangRust/payment-gateway-grpc/tree/main/internal/repository/"
    click QUERIES "https://github.com/MamangRust/payment-gateway-grpc/tree/main/pkg/database/query/"
    click SCHEMA "https://github.com/MamangRust/payment-gateway-grpc/tree/main/pkg/database/schema/"

    classDef client fill:#2374AB,stroke:#000,stroke-width:2px,color:#fff
    classDef gateway fill:#147BD1,stroke:#000,stroke-width:2px,color:#fff
    classDef middleware fill:#FFB800,stroke:#000,stroke-width:2px,color:#000
    classDef service fill:#0A8754,stroke:#000,stroke-width:2px,color:#fff
    classDef repo fill:#6B4E71,stroke:#000,stroke-width:2px,color:#fff
    classDef domain fill:#935FA7,stroke:#000,stroke-width:2px,color:#fff
    classDef queries fill:#8B728E,stroke:#000,stroke-width:2px,color:#fff
    classDef schema fill:#7A6B7E,stroke:#000,stroke-width:2px,color:#fff
    classDef database fill:#B33951,stroke:#000,stroke-width:2px,color:#fff
```
