junaidshahzad3/pk-pay

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.