Architecture & Concepts

GetPaidHQ is a billing backend with a REST API, Postgres storage, durable workflows, and pluggable adapters for payment processors and infrastructure.

Runtime shape

• API server: Go HTTP API mounted under /api.
• Core domain: products, variants, prices, orders, subscriptions, payments, meters, usage events, dunning campaigns, and payment-update tokens.
• Storage: Postgres for operational data. Usage events can use the same database or a separate usage database.
• Workflows: Hatchet by default; Temporal support exists behind the same workflow ports.
• Pub/sub: NATS for events and optional async usage ingestion.
• Cache/rate limits: Redis when configured; in-memory fallback for local single-instance use.
• Payment adapters: processor implementations behind a gateway interface. Current adapters include Paystack and Checkout.com.

Domain flow

1. A Product contains Variants.
2. A Variant has one or more Prices.
3. An Order records what a customer bought.
4. Completing an order activates recurring lines as Subscriptions.
5. A subscription billing cycle computes fixed and metered lines.
6. The resulting Payment is attempted through the selected gateway.
7. Failed recurring charges can open a Dunning Campaign.

Billing concepts

• Order: purchase record. One-time.
• Subscription: recurring agreement for one billing cadence.
• Meter: defines what usage to count and how to aggregate it.
• Usage event: one customer usage measurement.
• Metered price: price linked to a meter.
• Dunning campaign: failed-payment recovery workflow.

Boundaries

Business rules live in core services. Adapters handle persistence, HTTP, workflows, pub/sub, cache, authorization, and gateways. New processors should be added as gateway adapters, not by branching billing logic.