# atum-labs/examples architecture

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

- Interactive diagram: https://gitdiagram.com/atum-labs/examples
- Repository: https://github.com/atum-labs/examples
- Video tour (about a minute): https://gitdiagram.com/atum-labs/examples/video

## Overview

Atum Examples demonstrates three payment routes: x402 and MPP each pair a merchant that challenges and fulfills requests with a payer that retries a purchase while settlement is pending; PGC shows direct gateway payment without a merchant. Each route supports local stubs and opt-in real settlement. The graph preserves the separate challenge, payment, settlement, collection, and fulfillment stages. Some merchant internals are unsampled, so those links reflect README descriptions rather than inferred calls.

Main entry points: [`x402-accept-payments/src/merchant.ts`](https://github.com/atum-labs/examples/blob/main/x402-accept-payments/src/merchant.ts) (x402 merchant), [`mpp-accept-payments/src/merchant.ts`](https://github.com/atum-labs/examples/blob/main/mpp-accept-payments/src/merchant.ts) (MPP merchant), [`x402-make-payments/src/client.ts`](https://github.com/atum-labs/examples/blob/main/x402-make-payments/src/client.ts) (x402 payer client), [`mpp-make-payments/src/client.ts`](https://github.com/atum-labs/examples/blob/main/mpp-make-payments/src/client.ts) (MPP payer client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_x402["x402 examples"]
  node_xmerchant["x402 merchant<br/>[merchant.ts]"]
  node_xledger[("Delivery ledger<br/>[payments.ts]")]
  node_xpayer["x402 payer client<br/>[client.ts]"]
  node_xretry["Purchase retries<br/>[purchase.ts]"]
end

subgraph group_mpp["MPP examples"]
  node_mmerchant["MPP merchant<br/>[merchant.ts]"]
  node_mledger[("Delivery ledger<br/>[payments.ts]")]
  node_mpayer["MPP payer client<br/>[client.ts]"]
  node_mretry["Purchase retries<br/>[purchase.ts]"]
end

subgraph group_pgc["Direct PGC"]
  node_pgclient["Gateway payer<br/>[client.ts]"]
  node_pgcollect["Status collection<br/>[purchase.ts]"]
  node_pgstub["Stub gateway<br/>[stub-gateway.ts]"]
end

subgraph group_settlement["Settlement services"]
  node_facilitator["x402 facilitator"]
  node_gateway["Payment Gateway"]
  node_chain["Settlement networks"]
end

node_buyer(("Buyer / payer"))
node_merchant(("Merchant"))
node_resource["Paid resource"]

node_buyer -->|"initiates purchase"| node_xpayer
node_xpayer -->|"drives retries"| node_xretry
node_xretry -->|"invokes attempt"| node_xpayer
node_xpayer -->|"requests resource"| node_xmerchant
node_xmerchant -->|"returns 402 challenge"| node_xpayer
node_xpayer -->|"presents payment"| node_xmerchant
node_xmerchant -->|"facilitates payment"| node_facilitator
node_xmerchant -->|"reads and records delivery"| node_xledger
node_xmerchant -->|"serves fulfillment"| node_resource
node_buyer -->|"initiates purchase"| node_mpayer
node_mpayer -->|"drives retries"| node_mretry
node_mretry -->|"invokes attempt"| node_mpayer
node_mpayer -->|"requests resource"| node_mmerchant
node_mmerchant -->|"returns 402 challenge"| node_mpayer
node_mpayer -->|"submits credential"| node_mmerchant
node_mmerchant -->|"loads corridor and submits"| node_gateway
node_mmerchant -->|"reads and records delivery"| node_mledger
node_mmerchant -->|"serves fulfillment"| node_resource
node_buyer -->|"initiates payment"| node_pgclient
node_pgclient -->|"prepares and submits"| node_gateway
node_pgclient -->|"collects outcome"| node_pgcollect
node_pgcollect -->|"checks payment status"| node_gateway
node_pgclient -.->|"uses in-process stub"| node_pgstub
node_pgstub -.->|"returns payment status"| node_pgclient
node_facilitator -->|"settles payment"| node_chain
node_gateway -->|"settles payment"| node_chain

click node_xmerchant "https://github.com/atum-labs/examples/blob/main/x402-accept-payments/src/merchant.ts"
click node_xledger "https://github.com/atum-labs/examples/blob/main/x402-accept-payments/src/payments.ts"
click node_xpayer "https://github.com/atum-labs/examples/blob/main/x402-make-payments/src/client.ts"
click node_xretry "https://github.com/atum-labs/examples/blob/main/x402-make-payments/src/purchase.ts"
click node_mmerchant "https://github.com/atum-labs/examples/blob/main/mpp-accept-payments/src/merchant.ts"
click node_mledger "https://github.com/atum-labs/examples/blob/main/mpp-accept-payments/src/payments.ts"
click node_mpayer "https://github.com/atum-labs/examples/blob/main/mpp-make-payments/src/client.ts"
click node_mretry "https://github.com/atum-labs/examples/blob/main/mpp-make-payments/src/purchase.ts"
click node_pgclient "https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/client.ts"
click node_pgcollect "https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/purchase.ts"
click node_pgstub "https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/stub-gateway.ts"

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_xmerchant,node_xledger,node_xpayer,node_xretry toneBlue
class node_mmerchant,node_mledger,node_mpayer,node_mretry toneAmber
class node_pgclient,node_pgcollect,node_pgstub toneMint
class node_facilitator,node_gateway,node_chain toneRose
class node_buyer,node_merchant,node_resource toneIndigo
```

## Components

### x402 examples

- [x402 merchant](https://github.com/atum-labs/examples/blob/main/x402-accept-payments/src/merchant.ts): `x402-accept-payments/src/merchant.ts`
- [Delivery ledger](https://github.com/atum-labs/examples/blob/main/x402-accept-payments/src/payments.ts): `x402-accept-payments/src/payments.ts`
- [x402 payer client](https://github.com/atum-labs/examples/blob/main/x402-make-payments/src/client.ts): `x402-make-payments/src/client.ts`
- [Purchase retries](https://github.com/atum-labs/examples/blob/main/x402-make-payments/src/purchase.ts): `x402-make-payments/src/purchase.ts`

### MPP examples

- [MPP merchant](https://github.com/atum-labs/examples/blob/main/mpp-accept-payments/src/merchant.ts): `mpp-accept-payments/src/merchant.ts`
- [Delivery ledger](https://github.com/atum-labs/examples/blob/main/mpp-accept-payments/src/payments.ts): `mpp-accept-payments/src/payments.ts`
- [MPP payer client](https://github.com/atum-labs/examples/blob/main/mpp-make-payments/src/client.ts): `mpp-make-payments/src/client.ts`
- [Purchase retries](https://github.com/atum-labs/examples/blob/main/mpp-make-payments/src/purchase.ts): `mpp-make-payments/src/purchase.ts`

### Direct PGC

- [Gateway payer](https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/client.ts): `pgc-make-payments/src/client.ts`
- [Status collection](https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/purchase.ts): `pgc-make-payments/src/purchase.ts`
- [Stub gateway](https://github.com/atum-labs/examples/blob/main/pgc-make-payments/src/stub-gateway.ts): `pgc-make-payments/src/stub-gateway.ts`

### Settlement services

- **x402 facilitator**
- **Payment Gateway**
- **Settlement networks**

### Other components

- **Buyer / payer**
- **Merchant**
- **Paid resource**

## Connections

- Buyer / payer → x402 payer client: initiates purchase
- x402 payer client → Purchase retries: drives retries
- Purchase retries → x402 payer client: invokes attempt
- x402 payer client → x402 merchant: requests resource
- x402 merchant → x402 payer client: returns 402 challenge
- x402 payer client → x402 merchant: presents payment
- x402 merchant → x402 facilitator: facilitates payment
- x402 merchant → Delivery ledger: reads and records delivery
- x402 merchant → Paid resource: serves fulfillment
- Buyer / payer → MPP payer client: initiates purchase
- MPP payer client → Purchase retries: drives retries
- Purchase retries → MPP payer client: invokes attempt
- MPP payer client → MPP merchant: requests resource
- MPP merchant → MPP payer client: returns 402 challenge
- MPP payer client → MPP merchant: submits credential
- MPP merchant → Payment Gateway: loads corridor and submits
- MPP merchant → Delivery ledger: reads and records delivery
- MPP merchant → Paid resource: serves fulfillment
- Buyer / payer → Gateway payer: initiates payment
- Gateway payer → Payment Gateway: prepares and submits
- Gateway payer → Status collection: collects outcome
- Status collection → Payment Gateway: checks payment status
- Gateway payer → Stub gateway: uses in-process stub
- Stub gateway → Gateway payer: returns payment status
- x402 facilitator → Settlement networks: settles payment
- Payment Gateway → Settlement networks: settles payment