Architecture Components
Breakdown of the individual components that make up the Payment Gateway application stack.
Architecture & Components
The Payment Gateway is composed of several independent but cooperating services. By using a microservices architecture, the system is reliable, scalable, and secure.
The Services
Here is a breakdown of the core services deployed in the system. Public URLs are deployment-specific — env variables and hosted vs self-hosted examples are in Hostnames & DNS conventions.
| Service | Purpose | Public access (typical) |
|---|---|---|
| Admin Panel (Admin Frontend) | Management UI (WebAuthn, orgs, settings). | ADMIN_FRONTEND_DOMAIN — e.g. dashboard.* (hosted: dashboard.payment-gateway.app). Browser calls to /api/* on this host are proxied to the Admin Backend. |
| Admin API (Admin Backend) | REST API for the dashboard and merchant integrations (API keys, checkouts, etc.). | ADMIN_BACKEND_DOMAIN — e.g. api.* (hosted: api.payment-gateway.app). |
| Payment Portal (Main Frontend) | Hosted checkout pages and customer portal. | MAIN_FRONTEND_DOMAIN — e.g. secure.* or pay.* (hosted: secure.payment-gateway.app). |
| Payment runtime (Main Backend) | Checkout session API, provider webhooks (/hooks/...), Apple Pay domain file, health. | MAIN_BACKEND_DOMAIN — e.g. webhook.* (hosted: webhook.payment-gateway.app). |
| Database (MongoDB) | Primary datastore for transactions and configuration. TLS recommended. | Internal only |
| Cache (Garnet/Redis) | Redis-compatible cache and session data. | Internal only |
Worker (payment-gateway-main-worker) | Job queue: invoice PDF generation (via Gotenberg), outbound email/SMS/Slack; serves PDF cache over HTTP (default 8090). | Internal only (backends proxy PDF requests to the worker). |
| Gotenberg | Stateless HTML→PDF API used by the Worker. | Internal only |
| Reverse Proxy (Caddy) | TLS, routing, on-demand TLS for custom checkout domains. | Ports 80/443 — Caddy reverse proxy. |
PDF Generation & Storage Architecture
One of the complex subsystems is the PDF generation for invoices and receipts, designed for horizontal scalability.
- The Worker service consumes queued jobs: for PDFs it calls Gotenberg; notification jobs (email, SMS, Slack) use the same worker process.
- The generated PDF is stored in a local temporary cache (defaulting to
/tmp/pdf-cache). The worker automatically cleans up PDFs older than 24 hours. - The Worker acts as an HTTP server (default port 8090) to serve these cached PDFs.
- The Admin and Main Backends proxy PDF requests directly to the Worker, meaning no shared volumes are necessary between them.
- If an organization configures cloud storage (S3, Azure, or GCS) via settings, the PDFs are eventually stored there permanently instead of being dropped after 24 hours.
Database & Caching
The system relies on MongoDB as its primary datastore. While it operates on an internal network, enabling MongoDB TLS encryption is highly recommended for production deployments to secure the internal traffic.
For high performance, a Redis-compatible cache engine (Garnet) handles temporary data and session caching.
Shared Packages
Under the hood, the backend services share common Go code:
lib-common: Contains shared utilities, notification templates (Email, Slack, SMS), and models.lib-crypto: A dedicated library for cryptographic operations and secure data handling.