# dev-marker/payments architecture

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

- Interactive diagram: https://gitdiagram.com/dev-marker/payments
- Repository: https://github.com/dev-marker/payments

## Overview

This is a six-service payments backend. A client enters through the gateway, which authenticates and routes requests to service APIs; transfers proceed as sagas using wallet holds and capture or release. The wallet maintains the double-entry ledger, while supporting services handle identity, event-driven notifications, and outbound webhooks. The README documents the broader capabilities, including FX, risk review, reconciliation, and observability. Some internals are unsampled, so edges between those subsystems are limited to documented relationships.

Main entry points: [`cmd/wallet/main.go`](https://github.com/dev-marker/payments/blob/main/cmd/wallet/main.go) (Wallet service), [`internal/gateway/gateway.go`](https://github.com/dev-marker/payments/blob/main/internal/gateway/gateway.go) (API gateway), [`cmd/transfer/main.go`](https://github.com/dev-marker/payments/blob/main/cmd/transfer/main.go) (Transfer service), [`internal/transfer/saga.go`](https://github.com/dev-marker/payments/blob/main/internal/transfer/saga.go) (Transfer saga)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Public access and identity"]
  node_gateway["API gateway<br/>[gateway.go]"]
  node_auth["Auth service<br/>[service.go]"]
  node_authdb[("Auth database")]
end

subgraph group_money["Transfers and wallet"]
  node_transfer["Transfer service<br/>[main.go]"]
  node_saga["Transfer saga<br/>[saga.go]"]
  node_risk["Risk checks<br/>[risk.go]"]
  node_transferstore["Transfer store<br/>[store.go]"]
  node_wallet["Wallet service<br/>[main.go]"]
  node_walletapi["Wallet API<br/>[http.go]"]
  node_ledger["Double-entry ledger<br/>[ledger.go]"]
  node_walletstore["Wallet store<br/>[store.go]"]
  node_fx["FX conversion<br/>[convert.go]"]
  node_reconcile["Reconciliation and reports<br/>[reconcile.go]"]
end

subgraph group_async["Events and delivery"]
  node_events["NATS JetStream<br/>[natsx.go]"]
  node_outbox["Outbox relay<br/>[relay.go]"]
  node_notification["Notification service<br/>[consume.go]"]
  node_email["Email sender<br/>[sender.go]"]
  node_webhook["Webhook service<br/>[worker.go]"]
  node_webhookdb[("Webhook delivery store<br/>[webhooks.sql.go]")]
end

subgraph group_shared["Platform services"]
  node_platform["Shared platform"]
  node_audit[("Audit log<br/>[audit.go]")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes requests"| node_auth
node_gateway -->|"routes requests"| node_transfer
node_gateway -->|"routes requests"| node_wallet
node_gateway -->|"routes requests"| node_webhook
node_auth -->|"stores credentials"| node_authdb
node_transfer -->|"runs transfers"| node_saga
node_saga -->|"screens transfers"| node_risk
node_saga -->|"requests holds"| node_wallet
node_saga -->|"requests capture or release"| node_wallet
node_transfer -->|"persists state"| node_transferstore
node_wallet -->|"registers handler"| node_walletapi
node_walletapi -.->|"posts entries"| node_ledger
node_wallet -.->|"persists ledger"| node_walletstore
node_wallet -->|"supports conversion"| node_fx
node_wallet -->|"runs reconciliation"| node_reconcile
node_wallet -->|"relays events"| node_outbox
node_transfer -->|"relays events"| node_outbox
node_outbox -->|"publishes events"| node_events
node_events -->|"delivers events"| node_notification
node_notification -->|"sends email"| node_email
node_events -->|"delivers events"| node_webhook
node_webhook -->|"stores deliveries"| node_webhookdb
node_transfer -->|"records review"| node_audit
node_platform -.->|"provides shared middleware"| node_gateway

click node_gateway "https://github.com/dev-marker/payments/blob/main/internal/gateway/gateway.go"
click node_auth "https://github.com/dev-marker/payments/blob/main/internal/auth/service.go"
click node_authdb "https://github.com/dev-marker/payments/tree/main/internal/auth/authdb"
click node_transfer "https://github.com/dev-marker/payments/blob/main/cmd/transfer/main.go"
click node_saga "https://github.com/dev-marker/payments/blob/main/internal/transfer/saga.go"
click node_risk "https://github.com/dev-marker/payments/blob/main/internal/transfer/risk/risk.go"
click node_transferstore "https://github.com/dev-marker/payments/blob/main/internal/transfer/store.go"
click node_wallet "https://github.com/dev-marker/payments/blob/main/cmd/wallet/main.go"
click node_walletapi "https://github.com/dev-marker/payments/blob/main/internal/wallet/http.go"
click node_ledger "https://github.com/dev-marker/payments/blob/main/internal/wallet/ledger.go"
click node_walletstore "https://github.com/dev-marker/payments/blob/main/internal/wallet/store.go"
click node_fx "https://github.com/dev-marker/payments/blob/main/internal/fx/convert.go"
click node_reconcile "https://github.com/dev-marker/payments/blob/main/internal/wallet/reconcile.go"
click node_events "https://github.com/dev-marker/payments/blob/main/internal/platform/natsx/natsx.go"
click node_outbox "https://github.com/dev-marker/payments/blob/main/internal/platform/outbox/relay.go"
click node_notification "https://github.com/dev-marker/payments/blob/main/internal/notification/consume.go"
click node_email "https://github.com/dev-marker/payments/blob/main/internal/notification/sender.go"
click node_webhook "https://github.com/dev-marker/payments/blob/main/internal/webhook/worker.go"
click node_webhookdb "https://github.com/dev-marker/payments/blob/main/internal/webhook/webhookdb/webhooks.sql.go"
click node_platform "https://github.com/dev-marker/payments/tree/main/internal/platform"
click node_audit "https://github.com/dev-marker/payments/blob/main/internal/platform/audit/audit.go"

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_gateway,node_auth,node_authdb,node_client toneBlue
class node_transfer,node_saga,node_risk,node_transferstore,node_wallet,node_walletapi,node_ledger,node_walletstore,node_fx,node_reconcile toneAmber
class node_events,node_outbox,node_notification,node_email,node_webhook,node_webhookdb toneMint
class node_platform,node_audit toneRose
```

## Components

### Public access and identity

- [API gateway](https://github.com/dev-marker/payments/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`
- [Auth service](https://github.com/dev-marker/payments/blob/main/internal/auth/service.go): `internal/auth/service.go`
- [Auth database](https://github.com/dev-marker/payments/tree/main/internal/auth/authdb): `internal/auth/authdb`

### Transfers and wallet

- [Transfer service](https://github.com/dev-marker/payments/blob/main/cmd/transfer/main.go): `cmd/transfer/main.go`
- [Transfer saga](https://github.com/dev-marker/payments/blob/main/internal/transfer/saga.go): `internal/transfer/saga.go`
- [Risk checks](https://github.com/dev-marker/payments/blob/main/internal/transfer/risk/risk.go): `internal/transfer/risk/risk.go`
- [Transfer store](https://github.com/dev-marker/payments/blob/main/internal/transfer/store.go): `internal/transfer/store.go`
- [Wallet service](https://github.com/dev-marker/payments/blob/main/cmd/wallet/main.go): `cmd/wallet/main.go`
- [Wallet API](https://github.com/dev-marker/payments/blob/main/internal/wallet/http.go): `internal/wallet/http.go`
- [Double-entry ledger](https://github.com/dev-marker/payments/blob/main/internal/wallet/ledger.go): `internal/wallet/ledger.go`
- [Wallet store](https://github.com/dev-marker/payments/blob/main/internal/wallet/store.go): `internal/wallet/store.go`
- [FX conversion](https://github.com/dev-marker/payments/blob/main/internal/fx/convert.go): `internal/fx/convert.go`
- [Reconciliation and reports](https://github.com/dev-marker/payments/blob/main/internal/wallet/reconcile.go): `internal/wallet/reconcile.go`

### Events and delivery

- [NATS JetStream](https://github.com/dev-marker/payments/blob/main/internal/platform/natsx/natsx.go): `internal/platform/natsx/natsx.go`
- [Outbox relay](https://github.com/dev-marker/payments/blob/main/internal/platform/outbox/relay.go): `internal/platform/outbox/relay.go`
- [Notification service](https://github.com/dev-marker/payments/blob/main/internal/notification/consume.go): `internal/notification/consume.go`
- [Email sender](https://github.com/dev-marker/payments/blob/main/internal/notification/sender.go): `internal/notification/sender.go`
- [Webhook service](https://github.com/dev-marker/payments/blob/main/internal/webhook/worker.go): `internal/webhook/worker.go`
- [Webhook delivery store](https://github.com/dev-marker/payments/blob/main/internal/webhook/webhookdb/webhooks.sql.go): `internal/webhook/webhookdb/webhooks.sql.go`

### Platform services

- [Shared platform](https://github.com/dev-marker/payments/tree/main/internal/platform): `internal/platform`
- [Audit log](https://github.com/dev-marker/payments/blob/main/internal/platform/audit/audit.go): `internal/platform/audit/audit.go`

### Other components

- **API client**

## Connections

- API client → API gateway: sends requests (evidence: `README.md`)
- API gateway → Auth service: routes requests (evidence: `README.md`)
- API gateway → Transfer service: routes requests (evidence: `README.md`)
- API gateway → Wallet service: routes requests (evidence: `README.md`)
- API gateway → Webhook service: routes requests (evidence: `README.md`)
- Auth service → Auth database: stores credentials (evidence: `internal/auth/service.go`)
- Transfer service → Transfer saga: runs transfers (evidence: `README.md`)
- Transfer saga → Risk checks: screens transfers (evidence: `README.md`)
- Transfer saga → Wallet service: requests holds (evidence: `README.md`)
- Transfer saga → Wallet service: requests capture or release (evidence: `README.md`)
- Transfer service → Transfer store: persists state (evidence: `internal/transfer/store.go`)
- Wallet service → Wallet API: registers handler (evidence: `cmd/wallet/main.go`)
- Wallet API → Double-entry ledger: posts entries
- Wallet service → Wallet store: persists ledger
- Wallet service → FX conversion: supports conversion (evidence: `README.md`)
- Wallet service → Reconciliation and reports: runs reconciliation (evidence: `README.md`)
- Wallet service → Outbox relay: relays events (evidence: `cmd/wallet/main.go`)
- Transfer service → Outbox relay: relays events (evidence: `cmd/transfer/main.go`)
- Outbox relay → NATS JetStream: publishes events (evidence: `README.md`)
- NATS JetStream → Notification service: delivers events (evidence: `README.md`)
- Notification service → Email sender: sends email (evidence: `README.md`)
- NATS JetStream → Webhook service: delivers events (evidence: `README.md`)
- Webhook service → Webhook delivery store: stores deliveries (evidence: `internal/webhook/worker.go`)
- Transfer service → Audit log: records review
- Shared platform → API gateway: provides shared middleware (evidence: `internal/gateway/gateway.go`)