# crossben/yoonpay architecture

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

- Interactive diagram: https://gitdiagram.com/crossben/yoonpay
- Repository: https://github.com/crossben/yoonpay

## Overview

Yoon is a self-hosted payment gateway: applications submit payment intent, the server routes it to a capable provider, tracks confirmed state, and exposes outcomes and events. The product also supports payouts, refunds, reconciliation, billing, hosted checkout, links, portals, operator tooling, and MCP access. The graph combines README-documented capabilities with sampled service references; many controllers, provider adapters, and other subsystems were not sampled, so their internal call wiring is not asserted.

Main entry points: [`yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java) (Payment orchestration), [`yoon-server/src/main/java/dev/yoonpay/server/api`](https://github.com/crossben/yoonpay/tree/main/yoon-server/src/main/java/dev/yoonpay/server/api) (HTTP API), [`yoon-server/src/main/java/dev/yoonpay/server/provider/ProviderRegistry.java`](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/provider/ProviderRegistry.java) (Provider registry), [`yoon-server/src/main/java/dev/yoonpay/server/checkout/CheckoutController.java`](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/checkout/CheckoutController.java) (Hosted checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway API"]
  node_httpapi["HTTP API"]
  node_auth["API key authentication<br/>[ApiKeyFilter.java]"]
end

subgraph group_payments["Payment Operations"]
  node_payment["Payment orchestration"]
  node_routing["Provider routing<br/>[Router.java]"]
  node_paymentsdb[("Payment records")]
  node_payouts["Payout operations<br/>[PayoutService.java]"]
  node_refunds["Refund operations<br/>[RefundService.java]"]
  node_ledger[("Shadow ledger")]
end

subgraph group_billing["Billing Experience"]
  node_billing["Subscriptions and billing"]
  node_checkout["Hosted checkout"]
  node_links["Payment links"]
  node_portal["Customer portal<br/>[PortalService.java]"]
end

subgraph group_integrations["Providers and Clients"]
  node_providerreg["Provider registry"]
  node_adapters["Provider adapters"]
  node_mcp["MCP integration<br/>[server.ts]"]
  node_clients["SDK clients"]
end

subgraph group_operations["Operations and Events"]
  node_webhooks["Inbound callbacks"]
  node_reconcile["Automatic reconciliation<br/>[Reconciler.java]"]
  node_events["Event delivery"]
  node_status[("Status history<br/>[StatusEvents.java]")]
  node_operator["Operator tooling"]
end

node_merchant(("Merchant application"))
node_customer(("Payer / customer"))
node_provider(("Payment provider"))

node_merchant -->|"submits requests"| node_httpapi
node_httpapi -->|"authenticates with"| node_auth
node_payment -->|"selects providers"| node_routing
node_payment -->|"uses candidates"| node_providerreg
node_providerreg -.->|"configures"| node_adapters
node_payment -.->|"records payments"| node_paymentsdb
node_provider -->|"sends callbacks"| node_webhooks
node_webhooks -->|"confirms status"| node_provider
node_payment -->|"records transitions"| node_status
node_payouts -->|"calls provider"| node_providerreg
node_refunds -->|"calls provider"| node_providerreg
node_customer -->|"pays through"| node_checkout
node_customer -->|"opens link"| node_links
node_links -->|"starts checkout"| node_checkout
node_customer -->|"manages subscription"| node_portal
node_billing -->|"invoices use"| node_checkout
node_billing -.->|"creates payment"| node_payment
node_reconcile -->|"checks status"| node_provider
node_operator -->|"uses admin API"| node_httpapi
node_mcp -->|"reads and writes"| node_httpapi
node_clients -->|"calls gateway"| node_httpapi
node_payment -->|"emits events"| node_events
node_payment -->|"posts ledger entries"| node_ledger

click node_httpapi "https://github.com/crossben/yoonpay/tree/main/yoon-server/src/main/java/dev/yoonpay/server/api"
click node_auth "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/auth/ApiKeyFilter.java"
click node_payment "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java"
click node_routing "https://github.com/crossben/yoonpay/blob/main/yoon-core/src/main/java/dev/yoonpay/core/routing/Router.java"
click node_providerreg "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/provider/ProviderRegistry.java"
click node_adapters "https://github.com/crossben/yoonpay/tree/main/yoon-providers"
click node_paymentsdb "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentRepository.java"
click node_payouts "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payout/PayoutService.java"
click node_refunds "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/refund/RefundService.java"
click node_ledger "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/ledger/LedgerRepository.java"
click node_webhooks "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/webhook/InboundWebhookProcessor.java"
click node_reconcile "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/settlement/Reconciler.java"
click node_events "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/outbox/OutboxDelivery.java"
click node_status "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/lifecycle/StatusEvents.java"
click node_billing "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/billing/SubscriptionService.java"
click node_checkout "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/checkout/CheckoutController.java"
click node_links "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/link/PaymentLinkService.java"
click node_portal "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/portal/PortalService.java"
click node_operator "https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/admin/AdminController.java"
click node_mcp "https://github.com/crossben/yoonpay/blob/main/clients/mcp/src/server.ts"
click node_clients "https://github.com/crossben/yoonpay/tree/main/clients"

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_httpapi,node_auth toneBlue
class node_payment,node_routing,node_paymentsdb,node_payouts,node_refunds,node_ledger toneAmber
class node_billing,node_checkout,node_links,node_portal toneMint
class node_providerreg,node_adapters,node_mcp,node_clients toneRose
class node_webhooks,node_reconcile,node_events,node_status,node_operator,node_merchant,node_customer,node_provider toneIndigo
```

## Components

### Gateway API

- [HTTP API](https://github.com/crossben/yoonpay/tree/main/yoon-server/src/main/java/dev/yoonpay/server/api): `yoon-server/src/main/java/dev/yoonpay/server/api`
- [API key authentication](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/auth/ApiKeyFilter.java): `yoon-server/src/main/java/dev/yoonpay/server/auth/ApiKeyFilter.java`

### Payment Operations

- [Payment orchestration](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java): `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`
- [Provider routing](https://github.com/crossben/yoonpay/blob/main/yoon-core/src/main/java/dev/yoonpay/core/routing/Router.java): `yoon-core/src/main/java/dev/yoonpay/core/routing/Router.java`
- [Payment records](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentRepository.java): `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentRepository.java`
- [Payout operations](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/payout/PayoutService.java): `yoon-server/src/main/java/dev/yoonpay/server/payout/PayoutService.java`
- [Refund operations](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/refund/RefundService.java): `yoon-server/src/main/java/dev/yoonpay/server/refund/RefundService.java`
- [Shadow ledger](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/ledger/LedgerRepository.java): `yoon-server/src/main/java/dev/yoonpay/server/ledger/LedgerRepository.java`

### Billing Experience

- [Subscriptions and billing](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/billing/SubscriptionService.java): `yoon-server/src/main/java/dev/yoonpay/server/billing/SubscriptionService.java`
- [Hosted checkout](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/checkout/CheckoutController.java): `yoon-server/src/main/java/dev/yoonpay/server/checkout/CheckoutController.java`
- [Payment links](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/link/PaymentLinkService.java): `yoon-server/src/main/java/dev/yoonpay/server/link/PaymentLinkService.java`
- [Customer portal](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/portal/PortalService.java): `yoon-server/src/main/java/dev/yoonpay/server/portal/PortalService.java`

### Providers and Clients

- [Provider registry](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/provider/ProviderRegistry.java): `yoon-server/src/main/java/dev/yoonpay/server/provider/ProviderRegistry.java`
- [Provider adapters](https://github.com/crossben/yoonpay/tree/main/yoon-providers): `yoon-providers`
- [MCP integration](https://github.com/crossben/yoonpay/blob/main/clients/mcp/src/server.ts): `clients/mcp/src/server.ts`
- [SDK clients](https://github.com/crossben/yoonpay/tree/main/clients): `clients`

### Operations and Events

- [Inbound callbacks](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/webhook/InboundWebhookProcessor.java): `yoon-server/src/main/java/dev/yoonpay/server/webhook/InboundWebhookProcessor.java`
- [Automatic reconciliation](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/settlement/Reconciler.java): `yoon-server/src/main/java/dev/yoonpay/server/settlement/Reconciler.java`
- [Event delivery](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/outbox/OutboxDelivery.java): `yoon-server/src/main/java/dev/yoonpay/server/outbox/OutboxDelivery.java`
- [Status history](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/lifecycle/StatusEvents.java): `yoon-server/src/main/java/dev/yoonpay/server/lifecycle/StatusEvents.java`
- [Operator tooling](https://github.com/crossben/yoonpay/blob/main/yoon-server/src/main/java/dev/yoonpay/server/admin/AdminController.java): `yoon-server/src/main/java/dev/yoonpay/server/admin/AdminController.java`

### Other components

- **Merchant application**
- **Payer / customer**
- **Payment provider**

## Connections

- Merchant application → HTTP API: submits requests
- HTTP API → API key authentication: authenticates with
- Payment orchestration → Provider routing: selects providers (evidence: `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`)
- Payment orchestration → Provider registry: uses candidates (evidence: `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`)
- Provider registry → Provider adapters: configures
- Payment orchestration → Payment records: records payments (evidence: `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`)
- Payment provider → Inbound callbacks: sends callbacks
- Inbound callbacks → Payment provider: confirms status
- Payment orchestration → Status history: records transitions (evidence: `yoon-server/src/main/java/dev/yoonpay/server/payment/PaymentService.java`)
- Payout operations → Provider registry: calls provider (evidence: `yoon-server/src/main/java/dev/yoonpay/server/payout/PayoutService.java`)
- Refund operations → Provider registry: calls provider (evidence: `yoon-server/src/main/java/dev/yoonpay/server/refund/RefundService.java`)
- Payer / customer → Hosted checkout: pays through
- Payer / customer → Payment links: opens link
- Payment links → Hosted checkout: starts checkout
- Payer / customer → Customer portal: manages subscription
- Subscriptions and billing → Hosted checkout: invoices use
- Subscriptions and billing → Payment orchestration: creates payment (evidence: `yoon-server/src/main/java/dev/yoonpay/server/billing/SubscriptionService.java`)
- Automatic reconciliation → Payment provider: checks status
- Operator tooling → HTTP API: uses admin API
- MCP integration → HTTP API: reads and writes
- SDK clients → HTTP API: calls gateway
- Payment orchestration → Event delivery: emits events
- Payment orchestration → Shadow ledger: posts ledger entries