# junaidshahzad3/pk-pay architecture

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

- Interactive diagram: https://gitdiagram.com/junaidshahzad3/pk-pay
- Repository: https://github.com/junaidshahzad3/pk-pay

## Overview

1. **Repository shape**
   This is a TypeScript monorepo with two real runtime surfaces: the **core SDK** in `packages/pk-pay` and a **Next.js playground** in `apps/playground`. The rest of the repo is documentation, examples, CI, and release automation.

2. **Primary product boundary: `pk-pay` SDK**
   `packages/pk-pay` is the production library. It exposes a single public entrypoint in `src/index.ts` and is the main abstraction layer for payment integrations. The SDK’s purpose is to normalize multiple gateway-specific implementations behind one API shape.

3. **Provider adapter layer**
   The SDK contains separate provider modules for **JazzCash**, **EasyPaisa**, and **Stripe** under `src/providers/*`. These are the gateway-specific adapters that translate the SDK’s unified operations into provider-specific request/response formats, signatures, and workflow details.

4. **Framework integration layer**
   The `src/middleware` directory provides thin adapters for **Express**, **Fastify**, and **Next.js**. These are integration boundaries, not business logic: they make the SDK usable inside different server runtimes without forcing a single web framework.

5. **Shared utility layer**
   Cross-cutting concerns live in `src/utils`:  
   - `crypto.ts` for security-sensitive signing/verification logic  
   - `date.ts` for time handling  
   - `idempotency.ts` for preventing duplicate operations  
   - `retry.ts` for transient failure handling  
   These utilities support provider consistency and reduce duplicated gateway logic.

6. **Types and contract surface**
   `src/types` defines the shared domain contracts used across providers and middleware. Architecturally, this is the glue that keeps the SDK’s unified API stable while allowing each provider implementation to vary internally.

7. **Playground application**
   `apps/playground` is a separate Next.js 15 app used to exercise the SDK and payment flows in a live, interactive environment. It is not the core library; it is a testing and demonstration surface for real integrations.

8. **Playground request flow**
   Inside the playground, `src/lib` holds UI and server-action helpers, while `src/app/api/events/[id]/route.ts` and `src/app/api/webhook/[id]/route.ts` expose backend endpoints. The intended flow is: user inputs credentials/config in the UI, server-side actions initiate a payment or test handshake, and webhook/event endpoints capture asynchronous gateway callbacks.

9. **Realtime/event delivery**
   The README states the playground has a real-time webhook/event feed backed by **Upstash Redis**. That means the playground includes an external event distribution layer for observing payment callbacks and transaction progress during live testing.

10. **Examples as integration references**
   `examples/full-checkout-demo` and the docs examples in `packages/pk-pay/docs/examples` act as reference implementations. They show how consumers wire the SDK into plain browser code, Express, or Next.js, which helps define the SDK’s integration boundary.

11. **Testing strategy**
   The SDK has a focused test suite under `packages/pk-pay/tests` covering provider behavior, middleware integrations, and utility functions. This indicates the architecture is centered on contract verification across adapters rather than only unit testing isolated helpers.

12. **Build, publish, and deployment**
   The repo includes GitHub Actions for CI and publishing, plus `vercel.json` for deployment configuration of the playground. So the operational model is: library built and published from the monorepo, while the playground is deployed as a separate app for hands-on validation.

13. **How to draw the architecture**
   A good diagram would show:
   - consumers/frameworks on the left
   - middleware adapters as the integration boundary
   - the `pk-pay` core in the center
   - provider adapters branching to JazzCash/EasyPaisa/Stripe on the right
   - shared utilities underneath as cross-cutting dependencies
   - the playground as a parallel app that calls into the SDK and receives webhooks/events through its own API routes and Redis-backed feed.

Main entry points: [`packages/pk-pay/src/index.ts`](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/index.ts) (SDK entry), [`apps/playground/src/lib/actions.ts`](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/actions.ts) (Server actions), [`packages/pk-pay/src/types/index.ts`](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/types/index.ts) (Types), [`packages/pk-pay/src/providers/jazzcash/index.ts`](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/jazzcash/index.ts) (JazzCash)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["pk-pay SDK"]
  node_sdk_entry["SDK entry<br/>public API<br/>[index.ts]"]
  node_sdk_types["Types<br/>contracts<br/>[index.ts]"]
  node_sdk_utils_crypto["Crypto<br/>security util<br/>[crypto.ts]"]
  node_sdk_utils_date["Dates<br/>time util<br/>[date.ts]"]
  node_sdk_utils_idempotency["Idempotency<br/>dedupe util<br/>[idempotency.ts]"]
  node_sdk_utils_retry["Retry<br/>resilience util<br/>[retry.ts]"]
  node_sdk_mid_express["Express<br/>middleware adapter<br/>[index.ts]"]
  node_sdk_mid_fastify["Fastify<br/>middleware adapter<br/>[index.ts]"]
  node_sdk_mid_nextjs["Next.js<br/>middleware adapter<br/>[index.ts]"]
  node_sdk_provider_jazzcash["JazzCash<br/>gateway adapter<br/>[index.ts]"]
  node_sdk_provider_easypaisa["EasyPaisa<br/>gateway adapter<br/>[index.ts]"]
  node_sdk_provider_stripe["Stripe<br/>gateway adapter<br/>[index.ts]"]
end

subgraph group_playground["Playground"]
  node_playground_ui["Playground UI<br/>next app UI<br/>[PlaygroundUI.tsx]"]
  node_playground_actions["Server actions<br/>next actions<br/>[actions.ts]"]
  node_playground_schemas["Schemas<br/>[schemas.ts]"]
  node_playground_events_api["Events API<br/>route handler<br/>[route.ts]"]
  node_playground_webhook_api["Webhook API<br/>route handler<br/>[route.ts]"]
  node_redis_feed[("Upstash Redis<br/>event backend")]
end

subgraph group_references["References"]
  node_example_checkout["Checkout demo<br/>browser example<br/>[index.js]"]
  node_doc_express["Express example<br/>usage example<br/>[express.ts]"]
  node_doc_nextjs["Next.js example<br/>usage example<br/>[nextjs.ts]"]
end

subgraph group_ops["Ops"]
  node_ci_workflow["CI<br/>workflow<br/>[ci.yml]"]
  node_publish_workflow["Publish<br/>workflow<br/>[publish.yml]"]
  node_vercel_config["Vercel config<br/>deployment config<br/>[vercel.json]"]
end

node_sdk_entry -->|"uses"| node_sdk_types
node_sdk_entry -->|"depends on"| node_sdk_utils_crypto
node_sdk_entry -->|"depends on"| node_sdk_utils_date
node_sdk_entry -->|"depends on"| node_sdk_utils_idempotency
node_sdk_entry -->|"depends on"| node_sdk_utils_retry
node_sdk_entry -->|"exposes"| node_sdk_mid_express
node_sdk_entry -->|"exposes"| node_sdk_mid_fastify
node_sdk_entry -->|"exposes"| node_sdk_mid_nextjs
node_sdk_entry -->|"routes to"| node_sdk_provider_jazzcash
node_sdk_entry -->|"routes to"| node_sdk_provider_easypaisa
node_sdk_entry -->|"routes to"| node_sdk_provider_stripe
node_sdk_mid_express -->|"uses"| node_sdk_types
node_sdk_mid_fastify -->|"uses"| node_sdk_types
node_sdk_mid_nextjs -->|"uses"| node_sdk_types
node_sdk_provider_jazzcash -->|"uses"| node_sdk_utils_crypto
node_sdk_provider_jazzcash -->|"uses"| node_sdk_utils_retry
node_sdk_provider_easypaisa -->|"uses"| node_sdk_utils_crypto
node_sdk_provider_stripe -->|"uses"| node_sdk_utils_idempotency
node_playground_ui -->|"invokes"| node_playground_actions
node_playground_actions -->|"calls"| node_sdk_entry
node_playground_actions -->|"validates"| node_playground_schemas
node_playground_events_api -->|"publishes"| node_redis_feed
node_playground_webhook_api -->|"publishes"| node_redis_feed
node_playground_actions -->|"observes"| node_playground_events_api
node_playground_actions -->|"observes"| node_playground_webhook_api
node_example_checkout -->|"consumes"| node_sdk_entry
node_doc_express -->|"demonstrates"| node_sdk_mid_express
node_doc_nextjs -->|"demonstrates"| node_sdk_mid_nextjs
node_ci_workflow -->|"builds"| node_sdk_entry
node_ci_workflow -->|"checks"| node_playground_ui
node_publish_workflow -->|"publishes"| node_sdk_entry
node_vercel_config -->|"deploys"| node_playground_ui

click node_sdk_entry "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/index.ts"
click node_sdk_types "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/types/index.ts"
click node_sdk_utils_crypto "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/crypto.ts"
click node_sdk_utils_date "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/date.ts"
click node_sdk_utils_idempotency "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/idempotency.ts"
click node_sdk_utils_retry "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/retry.ts"
click node_sdk_mid_express "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/express/index.ts"
click node_sdk_mid_fastify "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/fastify/index.ts"
click node_sdk_mid_nextjs "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/nextjs/index.ts"
click node_sdk_provider_jazzcash "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/jazzcash/index.ts"
click node_sdk_provider_easypaisa "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/easypaisa/index.ts"
click node_sdk_provider_stripe "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/stripe/index.ts"
click node_playground_ui "https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/PlaygroundUI.tsx"
click node_playground_actions "https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/actions.ts"
click node_playground_schemas "https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/schemas.ts"
click node_playground_events_api "https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/app/api/events/[id]/route.ts"
click node_playground_webhook_api "https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/app/api/webhook/[id]/route.ts"
click node_example_checkout "https://github.com/junaidshahzad3/pk-pay/blob/main/examples/full-checkout-demo/index.js"
click node_doc_express "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/docs/examples/express.ts"
click node_doc_nextjs "https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/docs/examples/nextjs.ts"
click node_ci_workflow "https://github.com/junaidshahzad3/pk-pay/blob/main/.github/workflows/ci.yml"
click node_publish_workflow "https://github.com/junaidshahzad3/pk-pay/blob/main/.github/workflows/publish.yml"
click node_vercel_config "https://github.com/junaidshahzad3/pk-pay/blob/main/vercel.json"

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_sdk_entry,node_sdk_types,node_sdk_utils_crypto,node_sdk_utils_date,node_sdk_utils_idempotency,node_sdk_utils_retry,node_sdk_mid_express,node_sdk_mid_fastify,node_sdk_mid_nextjs,node_sdk_provider_jazzcash,node_sdk_provider_easypaisa,node_sdk_provider_stripe toneBlue
class node_playground_ui,node_playground_actions,node_playground_schemas,node_playground_events_api,node_playground_webhook_api,node_redis_feed toneAmber
class node_example_checkout,node_doc_express,node_doc_nextjs toneMint
class node_ci_workflow,node_publish_workflow,node_vercel_config toneRose
```

## Components

### pk-pay SDK

Production payment library and its adapters

- [SDK entry](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/index.ts): public API · Single export surface for the payment SDK · `packages/pk-pay/src/index.ts`
- [Types](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/types/index.ts): contracts · Shared domain contracts and API shapes · `packages/pk-pay/src/types/index.ts`
- [Crypto](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/crypto.ts): security util · Signing and verification helpers · `packages/pk-pay/src/utils/crypto.ts`
- [Dates](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/date.ts): time util · Time and date handling helpers · `packages/pk-pay/src/utils/date.ts`
- [Idempotency](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/idempotency.ts): dedupe util · Duplicate-operation protection · `packages/pk-pay/src/utils/idempotency.ts`
- [Retry](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/utils/retry.ts): resilience util · Transient-failure retry helpers · `packages/pk-pay/src/utils/retry.ts`
- [Express](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/express/index.ts): middleware adapter · Express integration boundary · `packages/pk-pay/src/middleware/express/index.ts`
- [Fastify](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/fastify/index.ts): middleware adapter · Fastify integration boundary · `packages/pk-pay/src/middleware/fastify/index.ts`
- [Next.js](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/middleware/nextjs/index.ts): middleware adapter · Next.js integration boundary · `packages/pk-pay/src/middleware/nextjs/index.ts`
- [JazzCash](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/jazzcash/index.ts): gateway adapter · Provider-specific payment implementation · `packages/pk-pay/src/providers/jazzcash/index.ts`
- [EasyPaisa](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/easypaisa/index.ts): gateway adapter · Provider-specific payment implementation · `packages/pk-pay/src/providers/easypaisa/index.ts`
- [Stripe](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/src/providers/stripe/index.ts): gateway adapter · Provider-specific payment implementation · `packages/pk-pay/src/providers/stripe/index.ts`

### Playground

Next.js app for live integration testing and demos

- [Playground UI](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/PlaygroundUI.tsx): next app UI · Interactive UI for configuring and exercising flows · `apps/playground/src/lib/PlaygroundUI.tsx`
- [Server actions](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/actions.ts): next actions · Server-side helpers that initiate playground flows · `apps/playground/src/lib/actions.ts`
- [Schemas](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/lib/schemas.ts): validation schemas · Shared input and payload schemas · `apps/playground/src/lib/schemas.ts`
- [Events API](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/app/api/events/[id]/route.ts): route handler · Event ingestion endpoint for callback tracking · `apps/playground/src/app/api/events/[id]/route.ts`
- [Webhook API](https://github.com/junaidshahzad3/pk-pay/blob/main/apps/playground/src/app/api/webhook/[id]/route.ts): route handler · Webhook endpoint for asynchronous gateway callbacks · `apps/playground/src/app/api/webhook/[id]/route.ts`
- **Upstash Redis**: event backend · Realtime event distribution backing the playground feed

### References

Examples and docs that show intended usage

- [Checkout demo](https://github.com/junaidshahzad3/pk-pay/blob/main/examples/full-checkout-demo/index.js): browser example · Standalone browser checkout reference implementation · `examples/full-checkout-demo/index.js`
- [Express example](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/docs/examples/express.ts): usage example · SDK usage example for Express integrations · `packages/pk-pay/docs/examples/express.ts`
- [Next.js example](https://github.com/junaidshahzad3/pk-pay/blob/main/packages/pk-pay/docs/examples/nextjs.ts): usage example · SDK usage example for Next.js integrations · `packages/pk-pay/docs/examples/nextjs.ts`

### Ops

CI, publishing, and deployment configuration

- [CI](https://github.com/junaidshahzad3/pk-pay/blob/main/.github/workflows/ci.yml): workflow · Continuous integration checks · `.github/workflows/ci.yml`
- [Publish](https://github.com/junaidshahzad3/pk-pay/blob/main/.github/workflows/publish.yml): workflow · Library publishing pipeline · `.github/workflows/publish.yml`
- [Vercel config](https://github.com/junaidshahzad3/pk-pay/blob/main/vercel.json): deployment config · Deployment configuration for the playground · `vercel.json`

## Connections

- SDK entry → Types: uses · Public API is shaped by shared contracts
- SDK entry → Crypto: depends on · Core API relies on signing and verification helpers
- SDK entry → Dates: depends on · Core API relies on time handling helpers
- SDK entry → Idempotency: depends on · Core API relies on duplicate-operation protection
- SDK entry → Retry: depends on · Core API relies on retry helpers
- SDK entry → Express: exposes · Public SDK exports Express integration
- SDK entry → Fastify: exposes · Public SDK exports Fastify integration
- SDK entry → Next.js: exposes · Public SDK exports Next.js integration
- SDK entry → JazzCash: routes to · Unified API dispatches to JazzCash adapter
- SDK entry → EasyPaisa: routes to · Unified API dispatches to EasyPaisa adapter
- SDK entry → Stripe: routes to · Unified API dispatches to Stripe adapter
- Express → Types: uses · Middleware shares SDK contracts
- Fastify → Types: uses · Middleware shares SDK contracts
- Next.js → Types: uses · Middleware shares SDK contracts
- JazzCash → Crypto: uses · Provider-specific signatures and verification
- JazzCash → Retry: uses · Provider calls are retried when needed
- EasyPaisa → Crypto: uses · Provider-specific signatures and verification
- Stripe → Idempotency: uses · Provider operations are deduplicated
- Playground UI → Server actions: invokes · User input triggers server-side actions
- Server actions → SDK entry: calls · Playground actions exercise the SDK
- Server actions → Schemas: validates · Actions use shared request schemas
- Events API → Upstash Redis: publishes · Events endpoint feeds the realtime stream
- Webhook API → Upstash Redis: publishes · Webhook callbacks feed the realtime stream
- Server actions → Events API: observes · Actions are reflected in the event feed
- Server actions → Webhook API: observes · Actions are reflected in webhook handling
- Checkout demo → SDK entry: consumes · Browser demo integrates the SDK directly
- Express example → Express: demonstrates · Docs show Express integration
- Next.js example → Next.js: demonstrates · Docs show Next.js integration
- CI → SDK entry: builds · CI validates the SDK surface
- CI → Playground UI: checks · CI validates the playground app
- Publish → SDK entry: publishes · Release workflow publishes the library
- Vercel config → Playground UI: deploys · Vercel config targets the playground app