# proxynth/payment-sandbox architecture

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

- Interactive diagram: https://gitdiagram.com/proxynth/payment-sandbox
- Repository: https://github.com/proxynth/payment-sandbox

## Overview

Payment Sandbox is a local payment-systems simulator, not a processor. Developers call its HTTP API to create and advance simulated payments, then inspect events, timelines, diagnostics, and asynchronous webhook outcomes; admin routes also support virtual time and scenario replay. The map preserves the payment, provider, durable-workflow, webhook, replay, and administration capabilities documented in the README. Edges are limited to visible calls and wiring; unsampled implementation details are not inferred.

Main entry points: [`internal/app/app.go`](https://github.com/proxynth/payment-sandbox/blob/main/internal/app/app.go) (Application composition), [`internal/payment/application`](https://github.com/proxynth/payment-sandbox/tree/main/internal/payment/application) (Payment use cases), [`internal/payment/adapters/http/handler.go`](https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/http/handler.go) (Payment endpoints), [`internal/administration/adapters/http`](https://github.com/proxynth/payment-sandbox/tree/main/internal/administration/adapters/http) (Admin controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP runtime"]
  node_app["Application composition<br/>[app.go]"]
  node_api["HTTP API server<br/>[server.go]"]
end

subgraph group_payments["Payment simulation"]
  node_payment_http["Payment endpoints<br/>[handler.go]"]
  node_payment_app["Payment use cases"]
  node_payment_domain["Payment lifecycle"]
  node_payment_store[("Payment storage<br/>[repository.go]")]
  node_event_log[("Payment event log<br/>[event_log.go]")]
  node_idempotency[("Idempotency records<br/>[repository.go]")]
  node_providers["Provider profiles"]
end

subgraph group_async["Async execution"]
  node_workflow["Saga orchestration<br/>[orchestrator.go]"]
  node_workflow_store[("Saga state<br/>[repository.go]")]
  node_scheduler["Durable scheduler"]
  node_scheduler_store[("Scheduled jobs<br/>[repository.go]")]
  node_webhook_http["Webhook endpoints<br/>[handler.go]"]
  node_webhook_delivery["Webhook delivery"]
  node_webhook_store[("Webhook records<br/>[repository.go]")]
end

subgraph group_inspection["Replay and administration"]
  node_replay["Scenario replay"]
  node_admin["Admin controls"]
  node_admin_queries["Timeline and diagnostics"]
end

subgraph group_platform["Platform and persistence"]
  node_clock["Virtual clock"]
  node_database[("SQLite database<br/>[database.go]")]
end

node_developer(("Developer"))
node_webhook_target(("Webhook receiver"))

node_developer -->|"calls HTTP"| node_api
node_api -->|"routes requests"| node_payment_http
node_payment_http -->|"executes use cases"| node_payment_app
node_payment_http -->|"records retries"| node_idempotency
node_payment_app -.->|"persists payments"| node_payment_store
node_payment_app -.->|"records events"| node_event_log
node_payment_app -.->|"applies lifecycle"| node_payment_domain
node_app -->|"creates server"| node_api
node_app -->|"registers routes"| node_payment_http
node_app -->|"registers profiles"| node_providers
node_app -->|"builds replay service"| node_replay
node_app -->|"builds executor"| node_workflow
node_app -->|"creates repository"| node_workflow_store
node_app -->|"creates worker"| node_scheduler
node_app -->|"creates repository"| node_scheduler_store
node_app -->|"configures callback"| node_webhook_delivery
node_app -->|"registers routes"| node_webhook_http
node_webhook_http -->|"uses repository"| node_webhook_store
node_admin -->|"advances time"| node_clock
node_admin -->|"lists providers"| node_providers
node_app -->|"registers admin routes"| node_admin
node_app -->|"wires inspection handlers"| node_admin_queries
node_replay -.->|"runs scenarios"| node_providers
node_webhook_delivery -.->|"sends callbacks"| node_webhook_target
node_app -->|"opens SQLite"| node_database
node_app -.->|"wires virtual time"| node_clock

click node_app "https://github.com/proxynth/payment-sandbox/blob/main/internal/app/app.go"
click node_api "https://github.com/proxynth/payment-sandbox/blob/main/internal/api/server.go"
click node_payment_http "https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/http/handler.go"
click node_payment_app "https://github.com/proxynth/payment-sandbox/tree/main/internal/payment/application"
click node_payment_domain "https://github.com/proxynth/payment-sandbox/tree/main/internal/payment/domain"
click node_payment_store "https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/sqlite/repository.go"
click node_event_log "https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/sqlite/event_log.go"
click node_idempotency "https://github.com/proxynth/payment-sandbox/blob/main/internal/idempotency/adapters/sqlite/repository.go"
click node_providers "https://github.com/proxynth/payment-sandbox/tree/main/internal/provider"
click node_workflow "https://github.com/proxynth/payment-sandbox/blob/main/internal/paymentworkflow/application/orchestrator.go"
click node_workflow_store "https://github.com/proxynth/payment-sandbox/blob/main/internal/paymentworkflow/adapters/sqlite/repository.go"
click node_scheduler "https://github.com/proxynth/payment-sandbox/tree/main/internal/scheduler/application"
click node_scheduler_store "https://github.com/proxynth/payment-sandbox/blob/main/internal/scheduler/adapters/sqlite/repository.go"
click node_webhook_http "https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/adapters/http/handler.go"
click node_webhook_delivery "https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/application/deliver_callback.go"
click node_webhook_store "https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/adapters/sqlite/repository.go"
click node_replay "https://github.com/proxynth/payment-sandbox/tree/main/internal/replay/application"
click node_admin "https://github.com/proxynth/payment-sandbox/tree/main/internal/administration/adapters/http"
click node_admin_queries "https://github.com/proxynth/payment-sandbox/tree/main/internal/administration/application"
click node_clock "https://github.com/proxynth/payment-sandbox/tree/main/internal/platform/clock"
click node_database "https://github.com/proxynth/payment-sandbox/blob/main/internal/platform/persistence/sqlite/database.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_app,node_api toneBlue
class node_payment_http,node_payment_app,node_payment_domain,node_payment_store,node_event_log,node_idempotency,node_providers toneAmber
class node_workflow,node_workflow_store,node_scheduler,node_scheduler_store,node_webhook_http,node_webhook_delivery,node_webhook_store,node_webhook_target toneMint
class node_replay,node_admin,node_admin_queries toneRose
class node_clock,node_database,node_developer toneIndigo
```

## Components

### HTTP runtime

- [Application composition](https://github.com/proxynth/payment-sandbox/blob/main/internal/app/app.go): `internal/app/app.go`
- [HTTP API server](https://github.com/proxynth/payment-sandbox/blob/main/internal/api/server.go): `internal/api/server.go`

### Payment simulation

- [Payment endpoints](https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/http/handler.go): `internal/payment/adapters/http/handler.go`
- [Payment use cases](https://github.com/proxynth/payment-sandbox/tree/main/internal/payment/application): `internal/payment/application`
- [Payment lifecycle](https://github.com/proxynth/payment-sandbox/tree/main/internal/payment/domain): `internal/payment/domain`
- [Payment storage](https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/sqlite/repository.go): `internal/payment/adapters/sqlite/repository.go`
- [Payment event log](https://github.com/proxynth/payment-sandbox/blob/main/internal/payment/adapters/sqlite/event_log.go): `internal/payment/adapters/sqlite/event_log.go`
- [Idempotency records](https://github.com/proxynth/payment-sandbox/blob/main/internal/idempotency/adapters/sqlite/repository.go): `internal/idempotency/adapters/sqlite/repository.go`
- [Provider profiles](https://github.com/proxynth/payment-sandbox/tree/main/internal/provider): `internal/provider`

### Async execution

- [Saga orchestration](https://github.com/proxynth/payment-sandbox/blob/main/internal/paymentworkflow/application/orchestrator.go): `internal/paymentworkflow/application/orchestrator.go`
- [Saga state](https://github.com/proxynth/payment-sandbox/blob/main/internal/paymentworkflow/adapters/sqlite/repository.go): `internal/paymentworkflow/adapters/sqlite/repository.go`
- [Durable scheduler](https://github.com/proxynth/payment-sandbox/tree/main/internal/scheduler/application): `internal/scheduler/application`
- [Scheduled jobs](https://github.com/proxynth/payment-sandbox/blob/main/internal/scheduler/adapters/sqlite/repository.go): `internal/scheduler/adapters/sqlite/repository.go`
- [Webhook endpoints](https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/adapters/http/handler.go): `internal/webhook/adapters/http/handler.go`
- [Webhook delivery](https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/application/deliver_callback.go): `internal/webhook/application/deliver_callback.go`
- [Webhook records](https://github.com/proxynth/payment-sandbox/blob/main/internal/webhook/adapters/sqlite/repository.go): `internal/webhook/adapters/sqlite/repository.go`

### Replay and administration

- [Scenario replay](https://github.com/proxynth/payment-sandbox/tree/main/internal/replay/application): `internal/replay/application`
- [Admin controls](https://github.com/proxynth/payment-sandbox/tree/main/internal/administration/adapters/http): `internal/administration/adapters/http`
- [Timeline and diagnostics](https://github.com/proxynth/payment-sandbox/tree/main/internal/administration/application): `internal/administration/application`

### Platform and persistence

- [Virtual clock](https://github.com/proxynth/payment-sandbox/tree/main/internal/platform/clock): `internal/platform/clock`
- [SQLite database](https://github.com/proxynth/payment-sandbox/blob/main/internal/platform/persistence/sqlite/database.go): `internal/platform/persistence/sqlite/database.go`

### Other components

- **Developer**
- **Webhook receiver**

## Connections

- Developer → HTTP API server: calls HTTP (evidence: `README.md`)
- HTTP API server → Payment endpoints: routes requests
- Payment endpoints → Payment use cases: executes use cases (evidence: `internal/payment/adapters/http/handler.go`)
- Payment endpoints → Idempotency records: records retries (evidence: `internal/payment/adapters/http/handler.go`)
- Payment use cases → Payment storage: persists payments
- Payment use cases → Payment event log: records events
- Payment use cases → Payment lifecycle: applies lifecycle
- Application composition → HTTP API server: creates server (evidence: `internal/app/app.go`)
- Application composition → Payment endpoints: registers routes (evidence: `internal/app/app.go`)
- Application composition → Provider profiles: registers profiles (evidence: `internal/app/app.go`)
- Application composition → Scenario replay: builds replay service (evidence: `internal/app/app.go`)
- Application composition → Saga orchestration: builds executor (evidence: `internal/app/app.go`)
- Application composition → Saga state: creates repository (evidence: `internal/app/app.go`)
- Application composition → Durable scheduler: creates worker (evidence: `internal/app/app.go`)
- Application composition → Scheduled jobs: creates repository (evidence: `internal/app/app.go`)
- Application composition → Webhook delivery: configures callback (evidence: `internal/app/app.go`)
- Application composition → Webhook endpoints: registers routes (evidence: `internal/app/app.go`)
- Webhook endpoints → Webhook records: uses repository (evidence: `internal/webhook/adapters/http/handler.go`)
- Admin controls → Virtual clock: advances time (evidence: `internal/administration/adapters/http/handler.go`)
- Admin controls → Provider profiles: lists providers (evidence: `internal/administration/adapters/http/handler.go`)
- Application composition → Admin controls: registers admin routes (evidence: `internal/app/app.go`)
- Application composition → Timeline and diagnostics: wires inspection handlers (evidence: `internal/app/app.go`)
- Scenario replay → Provider profiles: runs scenarios
- Webhook delivery → Webhook receiver: sends callbacks
- Application composition → SQLite database: opens SQLite (evidence: `internal/app/app.go`)
- Application composition → Virtual clock: wires virtual time
