# adnanhjoy/joy-pay architecture

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

- Interactive diagram: https://gitdiagram.com/adnanhjoy/joy-pay
- Repository: https://github.com/adnanhjoy/joy-pay

## Overview

1. **Overall shape**
   - This is a **NestJS backend API** for a payment gateway called **Joy Pay**.
   - The application is organized by feature modules, with **PostgreSQL + Prisma** as the persistence layer and **Swagger/OpenAPI** for API documentation.

2. **Core runtime boundary**
   - `src/main.ts` boots the Nest application.
   - `src/app.module.ts` composes the major modules:
     - auth
     - merchant
     - payment
     - transaction
     - webhook
     - provider
     - database/config
   - `src/config/*` and `src/database/*` are the infrastructure layer that the feature modules depend on.

3. **Persistence and domain model**
   - Prisma is the central data access layer.
   - The schema is split across `prisma/models/*.prisma` and `prisma/enums/*.prisma`, with migrations in `prisma/migrations`.
   - The main persisted entities are:
     - **Merchant**
     - **PaymentSession**
     - **Transaction**
     - **WebhookLog**
   - The committed `prisma/generated/*` client indicates the app uses generated Prisma types directly in the codebase.

4. **Authentication and request security**
   - There are two auth concerns:
     - **JWT auth** in `src/modules/auth` using `jwt.strategy.ts`
     - **HMAC request signing** in `src/common/guards/api-key-auth.guard.ts` and `src/common/utils/hmac.util.ts`
   - The `api-key.decorator.ts` suggests some routes extract or validate API key metadata for signed requests.
   - Architecturally, this means the API supports both **session-style authentication** and **partner/merchant request verification**.

5. **Merchant management subsystem**
   - `src/modules/merchant` owns merchant lifecycle operations.
   - It exposes a controller/service pair and DTOs for creating and returning merchant data.
   - This module is likely the authoritative entry point for onboarding and managing merchants before they can initiate payments.

6. **Payment initiation subsystem**
   - `src/modules/payment` handles payment creation and API-facing payment endpoints.
   - `create-payment.dto.ts` and `payment-response.dto.ts` indicate a request/response boundary around payment initiation.
   - This module likely orchestrates validation, merchant authorization, provider selection, and persistence of the payment session.

7. **Provider abstraction and routing**
   - `src/modules/provider` is the integration boundary for payment rails.
   - `payment-provider.interface.ts` defines the contract, while `provider.factory.ts` selects among implementations.
   - The repo currently includes mock adapters for:
     - **bKash**
     - **Nagad**
     - **Card**
   - This is a clear adapter pattern: the payment flow is decoupled from any one provider implementation.

8. **Transaction tracking**
   - `src/modules/transaction` is the ledger/audit layer for payment state changes.
   - The presence of `create-transaction.dto.ts` and `transaction.service.ts` suggests transactions are persisted separately from the initial payment request.
   - In architecture terms, this module is the system of record for payment lifecycle transitions.

9. **Webhook delivery and event logging**
   - `src/modules/webhook` handles webhook behavior.
   - `webhook.service.ts` and `webhook.controller.ts` indicate both internal processing and an API surface.
   - The persisted `WebhookLog` model suggests webhook attempts/statuses are tracked for reliability and auditability.
   - This module is likely the outbound event boundary after a payment reaches success/failure states.

10. **Cross-cutting infrastructure**
   - `src/common` contains shared concerns used across modules:
     - auth decorators and guards
     - HMAC utilities
   - `src/database/prisma.service.ts` provides the shared database connection/service abstraction.
   - `src/config/app-config.service.ts` and `configuration.ts` centralize runtime configuration such as database and JWT settings.

11. **External/system dependencies**
   - The main external runtime dependency is **PostgreSQL**.
   - The payment-provider layer is designed to represent external payment networks, but in this repo they are currently **mock providers** rather than real integrations.
   - Swagger is a documentation surface, not a runtime dependency, but it affects how the API is consumed.

12. **Primary data flow**
   - A typical flow is:
     - merchant authenticates / is validated
     - merchant submits a payment request
     - payment module creates a payment session
     - provider factory routes to the chosen provider adapter
     - transaction records are written to PostgreSQL
     - webhook events are logged/sent after status changes
   - This makes the system a **payment orchestration backend**, not just a CRUD API.

13. **Testing and delivery**
   - `test/app.e2e-spec.ts` and `test/test-helpers.ts` indicate the repo includes **end-to-end API tests**.
   - The project uses standard Nest/TypeScript tooling (`nest-cli.json`, `tsconfig*`, ESLint, Prettier), so the architecture is optimized for a conventional server-side deployment pipeline.

14. **What to draw in an architecture diagram**
   - Place **NestJS API** in the center with feature modules around it.
   - Show **PostgreSQL/Prisma** as the persistence boundary.
   - Show **merchant clients** entering through authenticated API routes.
   - Show **provider adapters** as an internal abstraction layer between payment orchestration and payment networks.
   - Show **webhooks** as an outbound event channel with logging/audit storage.

Main entry points: [`src/app.module.ts`](https://github.com/adnanhjoy/joy-pay/blob/main/src/app.module.ts) (App module), [`src/database/prisma.service.ts`](https://github.com/adnanhjoy/joy-pay/blob/main/src/database/prisma.service.ts) (Prisma service), [`src/modules/payment/payment.module.ts`](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/payment/payment.module.ts) (Payment), [`src/modules/provider/provider.module.ts`](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/provider/provider.module.ts) (Provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Bootstrap<br/>NestJS entrypoint<br/>[main.ts]"))
  node_app["App module<br/>module composition<br/>[app.module.ts]"]
end

subgraph group_features["Feature modules"]
  node_auth["Auth<br/>jwt module<br/>[auth.module.ts]"]
  node_merchant["Merchant<br/>[merchant.module.ts]"]
  node_payment["Payment<br/>[payment.module.ts]"]
  node_provider["Provider<br/>adapter layer<br/>[provider.module.ts]"]
  node_transaction["Transaction<br/>ledger module"]
  node_webhook["Webhook<br/>event module<br/>[webhook.module.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_config["Config<br/>[configuration.ts]"]
  node_appconfig["App config<br/>config service"]
  node_dbmodule["Database<br/>[database.module.ts]"]
  node_prisma[("Prisma service<br/>db access<br/>[prisma.service.ts]")]
  node_security{{"API security<br/>guard/decorator"}}
  node_hmac["HMAC util<br/>crypto helper<br/>[hmac.util.ts]"]
end

subgraph group_data["Data layer"]
  node_schema["Prisma schema<br/>data model<br/>[schema.prisma]"]
  node_client["Prisma client<br/>generated client<br/>[client.ts]"]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_external["External"]
  node_clients(("Merchant clients<br/>API consumers"))
  node_rails(("Payment rails<br/>external networks"))
  node_docs["API docs"]
end

node_main -->|"boots"| node_app
node_app -->|"loads"| node_config
node_app -->|"imports"| node_dbmodule
node_app -->|"composes"| node_auth
node_app -->|"composes"| node_merchant
node_app -->|"composes"| node_payment
node_app -->|"composes"| node_provider
node_app -->|"composes"| node_transaction
node_app -->|"composes"| node_webhook
node_app -.->|"shares"| node_security
node_dbmodule -->|"provides"| node_prisma
node_prisma -->|"maps"| node_schema
node_schema -.->|"generates"| node_client
node_client -->|"queries"| node_postgres
node_auth -->|"uses"| node_appconfig
node_security -->|"verifies"| node_hmac
node_merchant -->|"persists"| node_prisma
node_payment -->|"persists"| node_prisma
node_payment -->|"dispatches"| node_provider
node_payment -->|"records"| node_transaction
node_payment -->|"emits"| node_webhook
node_provider -->|"adapts"| node_rails
node_transaction -->|"persists"| node_prisma
node_webhook -->|"logs"| node_prisma
node_clients -->|"calls"| node_security
node_docs -.->|"describes"| node_app

click node_main "https://github.com/adnanhjoy/joy-pay/blob/main/src/main.ts"
click node_app "https://github.com/adnanhjoy/joy-pay/blob/main/src/app.module.ts"
click node_config "https://github.com/adnanhjoy/joy-pay/blob/main/src/config/configuration.ts"
click node_appconfig "https://github.com/adnanhjoy/joy-pay/blob/main/src/config/app-config.service.ts"
click node_dbmodule "https://github.com/adnanhjoy/joy-pay/blob/main/src/database/database.module.ts"
click node_prisma "https://github.com/adnanhjoy/joy-pay/blob/main/src/database/prisma.service.ts"
click node_security "https://github.com/adnanhjoy/joy-pay/blob/main/src/common/guards/api-key-auth.guard.ts"
click node_hmac "https://github.com/adnanhjoy/joy-pay/blob/main/src/common/utils/hmac.util.ts"
click node_auth "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/auth/auth.module.ts"
click node_merchant "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/merchant/merchant.module.ts"
click node_payment "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/payment/payment.module.ts"
click node_provider "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/provider/provider.module.ts"
click node_transaction "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/transaction/transaction.module.ts"
click node_webhook "https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/webhook/webhook.module.ts"
click node_schema "https://github.com/adnanhjoy/joy-pay/blob/main/prisma/schema.prisma"
click node_client "https://github.com/adnanhjoy/joy-pay/blob/main/prisma/generated/client.ts"
click node_docs "https://github.com/adnanhjoy/joy-pay/blob/main/API_DOCUMENTATION.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app toneBlue
class node_auth,node_merchant,node_payment,node_provider,node_transaction,node_webhook toneAmber
class node_config,node_appconfig,node_dbmodule,node_prisma,node_security,node_hmac toneMint
class node_schema,node_client,node_postgres toneRose
class node_clients,node_rails,node_docs toneIndigo
```

## Components

### Runtime

NestJS bootstrap and application composition

- [Bootstrap](https://github.com/adnanhjoy/joy-pay/blob/main/src/main.ts): NestJS entrypoint · Starts the application from src/main.ts · `src/main.ts`
- [App module](https://github.com/adnanhjoy/joy-pay/blob/main/src/app.module.ts): module composition · Composes the main feature and infrastructure modules · `src/app.module.ts`

### Feature modules

API modules that implement the business flow

- [Auth](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/auth/auth.module.ts): jwt module · JWT-based authentication boundary · `src/modules/auth/auth.module.ts`
- [Merchant](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/merchant/merchant.module.ts): merchant module · Merchant onboarding and management API · `src/modules/merchant/merchant.module.ts`
- [Payment](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/payment/payment.module.ts): payment module · Creates payment sessions and exposes payment endpoints · `src/modules/payment/payment.module.ts`
- [Provider](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/provider/provider.module.ts): adapter layer · Routes payment requests to a provider implementation · `src/modules/provider/provider.module.ts`
- [Transaction](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/transaction/transaction.module.ts): ledger module · Persists lifecycle changes and payment audit records · `src/modules/transaction/transaction.module.ts`
- [Webhook](https://github.com/adnanhjoy/joy-pay/blob/main/src/modules/webhook/webhook.module.ts): event module · Handles outbound webhook delivery and logging · `src/modules/webhook/webhook.module.ts`

### Infrastructure

Shared config, security, and database wiring

- [Config](https://github.com/adnanhjoy/joy-pay/blob/main/src/config/configuration.ts): runtime config · Centralized application configuration values · `src/config/configuration.ts`
- [App config](https://github.com/adnanhjoy/joy-pay/blob/main/src/config/app-config.service.ts): config service · Reads and exposes app settings such as JWT and database config · `src/config/app-config.service.ts`
- [Database](https://github.com/adnanhjoy/joy-pay/blob/main/src/database/database.module.ts): database module · Wires Prisma into the NestJS app · `src/database/database.module.ts`
- [Prisma service](https://github.com/adnanhjoy/joy-pay/blob/main/src/database/prisma.service.ts): db access · Shared Prisma connection and query access · `src/database/prisma.service.ts`
- [API security](https://github.com/adnanhjoy/joy-pay/blob/main/src/common/guards/api-key-auth.guard.ts): guard/decorator · HMAC request signing and API key metadata handling · `src/common/guards/api-key-auth.guard.ts`
- [HMAC util](https://github.com/adnanhjoy/joy-pay/blob/main/src/common/utils/hmac.util.ts): crypto helper · Shared signing and verification logic for partner requests · `src/common/utils/hmac.util.ts`

### Data layer

Prisma schema, generated client, and PostgreSQL boundary

- [Prisma schema](https://github.com/adnanhjoy/joy-pay/blob/main/prisma/schema.prisma): data model · Defines enums and models for merchants, payments, transactions, and webhooks · `prisma/schema.prisma`
- [Prisma client](https://github.com/adnanhjoy/joy-pay/blob/main/prisma/generated/client.ts): generated client · Committed generated client types used by the codebase · `prisma/generated/client.ts`
- **PostgreSQL**: database · Primary persistence store behind Prisma

### External

Consumers and outside systems

- **Merchant clients**: API consumers · External callers that authenticate and initiate payments
- **Payment rails**: external networks · bKash, Nagad, and card providers represented through adapters
- [API docs](https://github.com/adnanhjoy/joy-pay/blob/main/API_DOCUMENTATION.md): OpenAPI docs · Swagger/OpenAPI description of the API surface · `API_DOCUMENTATION.md`

## Connections

- Bootstrap → App module: boots · Application starts by creating the Nest app and loading the root module
- App module → Config: loads · Root composition depends on centralized runtime configuration
- App module → Database: imports · Application includes the database infrastructure module
- App module → Auth: composes · Root module wires the authentication feature
- App module → Merchant: composes · Root module wires merchant operations
- App module → Payment: composes · Root module wires payment initiation flows
- App module → Provider: composes · Root module wires provider abstraction and adapters
- App module → Transaction: composes · Root module wires transaction tracking
- App module → Webhook: composes · Root module wires webhook handling
- App module → API security: shares · Cross-cutting request verification is used across modules
- Database → Prisma service: provides · Database module exports the shared Prisma service
- Prisma service → Prisma schema: maps · Prisma service operates on the defined schema models
- Prisma schema → Prisma client: generates · Schema produces the committed Prisma client
- Prisma client → PostgreSQL: queries · Generated client is the access layer to PostgreSQL
- Auth → App config: uses · JWT auth reads runtime settings from config service
- API security → HMAC util: verifies · Guard relies on HMAC utilities for request signing checks
- Merchant → Prisma service: persists · Merchant lifecycle operations read and write through Prisma
- Payment → Prisma service: persists · Payment creation stores payment session data
- Payment → Provider: dispatches · Payment flow selects and invokes a provider adapter
- Payment → Transaction: records · Successful or failed payment steps are captured as transactions
- Payment → Webhook: emits · Payment state changes trigger webhook handling and logging
- Provider → Payment rails: adapts · Provider layer represents the external payment networks
- Transaction → Prisma service: persists · Transaction records are stored in the database
- Webhook → Prisma service: logs · Webhook attempts and status are persisted for auditability
- Merchant clients → API security: calls · Merchant-facing requests enter through authenticated and signed routes
- API docs → App module: describes · API documentation documents the NestJS endpoints