Paycore is a payment and subscription platform that starts small — recurring subscriptions and one-off collections in Zambian kwacha through Lipila — and is structured to grow into billing, a ledger, payouts, and multi-provider routing without rewriting the core.
The guiding rule is that money must stay correct when things go wrong: webhooks that arrive twice or before the API response, a provider that is down, a worker that crashes mid-renewal, or two workers renewing the same subscription. The design covers each of these failure scenarios explicitly, alongside 12 written financial safety rules.
The backend is about 11,000 lines of Go, organised as a modular monolith with clear bounded contexts, and built with Bazel alongside protobuf contracts and a native SwiftUI client.
Correctness by Design
- Money is never a float: every amount is an integer count of minor units that always travels with its ISO 4217 currency.
- Explicit state machines for subscriptions (incomplete, trialing, active, past due, canceled, expired) and payments — a failed payment can never be silently rewritten as succeeded.
- Append-only payment attempts, so every retry stays auditable and every refund explicable.
- Every subscription state change is recorded as an event, giving a full audit trail of the lifecycle.
Reliability Under Failure
- Idempotency keys on payment and subscription creation, enforced by a database constraint rather than read-then-write, so concurrent retries can never create a second payment.
- Transactional outbox: events are written in the same transaction as the state change and drained to RabbitMQ by a worker with exponential backoff, so a crash never loses an event.
- Reconciliation job that asks the provider what really happened to every in-flight payment, because webhooks get lost, arrive out of order, or land during downtime.
- Redis distributed locks per aggregate — a worker whose lease expired can never release a lock another worker now holds — so duplicate workers or schedulers are harmless.
- Durable background jobs on Redis (asynq) for renewals, payment retries, grace-period expiry, and cleanup — surviving deploys, crashes, and restarts.
- Grace periods for failed renewals before a subscription stops being entitled.
Payments & Webhooks
- Provider-agnostic PaymentProvider port: everything Lipila-specific lives in one adapter, so adding a provider never touches the business domain.
- Lipila webhooks verified with HMAC-SHA256 over the raw body, compared in constant time, and failing closed when a signature or secret is missing.
- A fixed webhook pipeline — verify, parse, deduplicate, apply in one transaction, publish — that answers 200 to duplicates so the provider stops redelivering.
- A local Lipila stub service for developing the full flow end to end without live credentials.
Architecture
- Modular monolith with bounded contexts — customers, billing, subscriptions, payments, webhooks — each split into domain, ports, services, and adapters; contexts never import each other’s domains.
- Three deployable processes: the API, a worker, and a migrator, with embedded SQL migrations.
- Versioned REST API under /v1 with an OpenAPI contract, and language-neutral protobuf contracts for events and domains (Buf).
- API keys stored only as SHA-256 digests, JWT bearer auth, and scoped permissions recorded on audit trails.
- OpenTelemetry traces and a defined metrics catalog, plus health and readiness probes that check PostgreSQL, Redis, and RabbitMQ.
- Polyglot monorepo built with Bazel (bzlmod), a Go workspace, and bun workspaces.
iOS App
- Native SwiftUI app with onboarding, sign-in, a home screen showing the current billing period and renewal amount, packages, payments, and profile.
- A custom design system — palette, metrics, motion, and components — shared across every screen.
- Built against the platform’s domain model: minor-unit amounts, ZMW, and the subscription statuses and entitlement rule.
- Never calls the payments API directly, since an API key is full-access; it goes through the merchant’s own backend.