Architecture Components
Breakdown of the individual components that make up the Payment Gateway application stack.
Architecture & Components
The Payment Gateway is composed of independent services that communicate through HTTP, MongoDB, and a MongoDB-backed background job queue. Caddy owns public TLS and routing; the Go backends own business rules; the React frontends are served by small Node/Express servers that proxy /api/* to the matching backend.
The Services
Here is a breakdown of the core services deployed in the system. Public URLs are deployment-specific; environment variables and hosted vs self-hosted examples are in Hostnames & DNS conventions.
| Service | Purpose | Public access (typical) |
|---|---|---|
| Admin Panel (Admin Frontend) | React management UI for WebAuthn, organizations, settings, invoices, reporting, and system licensing. | ADMIN_FRONTEND_DOMAIN, for example dashboard.*. Browser calls to /api/* on this host are proxied to the Admin Backend. |
| Admin API (Admin Backend) | Go REST API for the dashboard and merchant integrations: API keys, checkout creation, domains, invoices, reporting. | ADMIN_BACKEND_DOMAIN, for example api.*. Caddy also rewrites /v1/* to /api/v1/* for cleaner external API paths. |
| Payment Portal (Main Frontend) | React hosted checkout UI and customer portal. Its Node/Express server proxies /api/* to the Main Backend. | MAIN_FRONTEND_DOMAIN, for example secure.* or pay.*. Custom checkout hostnames also fall through Caddy's :443 catch-all to this frontend. |
| Payment runtime (Main Backend) | Go API for checkout session reads, transaction creation/status, billing requests, customer portal APIs, and provider hooks. | MAIN_BACKEND_DOMAIN, for example webhook.*; provider callbacks use /hooks/{type}/{providerId} without the /api/v1 prefix. |
Worker (payment-gateway-main-worker) | Processes MongoDB-backed jobs: PDF generation, email, Slack, and SMS. Also serves cached PDFs/e-invoice artifacts over HTTP. | Internal only, default port 8090. Backends proxy document downloads to the worker. |
| Gotenberg | Stateless HTML-to-PDF service used only by the Worker. | Internal only, default port 3000. |
| Database (MongoDB) | Primary datastore for application collections, the jobs queue, and Caddy certificate storage through the MongoDB Caddy module. | Internal only; TLS is enabled by default in the deployment templates when certificates are present. |
| Cache (Garnet/Redis) | Redis-compatible cache used by backend services. It is not the background job queue. | Internal only. |
| Reverse Proxy (Caddy) | Public TLS termination, security headers, domain routing, ACME HTTP challenge forwarding, and on-demand TLS ask checks. | Host ports 80, 443/tcp, and 443/udp; see Caddy reverse proxy. |
| Mongo Express | Optional database inspection UI protected by Caddy IP allow-listing and its own basic auth settings. | Optional MONGO_EXPRESS_DOMAIN; should remain restricted. |
| MGOB | Scheduled MongoDB backup container. | Internal only. |
PDF Generation & Storage Architecture
One of the complex subsystems is PDF generation for invoices and receipts, designed so the API containers do not need a shared filesystem.
- Backends enqueue work into the MongoDB
jobscollection with task types such aspdf:generate,email:send,slack:send, andsms:send. - The Worker service claims jobs from MongoDB. For PDFs it calls Gotenberg; notification jobs 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 cached PDFs and e-invoice artifacts. - The Admin and Main Backends proxy PDF requests directly to the Worker, meaning no shared volumes are necessary between them.
- If no verified durable document-storage provider is active for the organization, the temporary worker cache is the delivery source. Operators should keep their own accounting archive and verify any configured object-storage provider before treating it as durable retention.
Database & Caching
The system relies on MongoDB as its primary datastore. It stores operational data, configuration, license state cached by the self-hosted installation, Caddy TLS storage, and background jobs.
For high performance, a Redis-compatible cache engine (Garnet) handles cache data. Background jobs are not stored in Garnet; they are persisted in MongoDB so workers can retry, requeue stale jobs, and survive container restarts.
Shared Backend Capabilities
The backend services share common validation, notification, tax, address, document-numbering, field-encryption, DEK storage, KMS, and credential-protection capabilities.