Hebron Heights
Freelance Full-Stack Backend
HHG Commerce — a two-sided transactional commerce backend for retail users and merchants: checkout via Paystack or Stripe, real-time order status over SSE, merchant stores and inventory, media uploads and store analytics, with an outbox-driven event bus guaranteeing every order side-effect runs exactly once.
stack
01 · Requirement Analysis
A two-sided commerce backend serving retail users and merchants: browse and buy, manage stores and inventory, pay with Paystack or Stripe, get live order status in the browser, upload product media, and see store analytics — all without losing or duplicating a single business event. The platform had to guarantee that every order side-effect (stock deduction, email, notification row, payment follow-up) runs exactly once even if the process crashes mid-flight, while keeping sensitive flows (webhooks, auth, uploads) verifiable and auditable.
02 · Architecture Discovery
Split the system into decoupled planes: identity (better-auth + argon2 hashing), catalog (products, categories, merchants), the transactional core (cart → order → payment, all committed inside Drizzle transactions), a media pipeline (Cloudinary signed uploads with webhook feedback), and a real-time notification channel. Every domain write first lands in a durable PostgreSQL outbox table, then an RxJS event bus dispatches typed contracts (event_type, userId, payload) to autonomous consumers (email, inventory, notification, payment). Validated that write-first + guarded-update consume gives at-least-once delivery with replay for recovery.
03 · Software Architecture
An Express 5 API federating Paystack and Stripe behind one checkout dispatcher, rewiring signature-verified webhook payloads (Paystack, Stripe, Cloudinary) into domain events, and serving role-protected endpoints (user / merchant / admin) enforced by auth + role-guard middleware. A catalog layer manages products, categories, merchants, carts and merchant analytics with soft-delete and stock thresholds; a media layer issues signed Cloudinary uploads for single and bulk streaming with webhook confirmation. Cross-cutting: Zod validation at the edge, a centralized error contract (typed error codes → global handler), and a real-time channel where a singleton in-memory NotificationBroker feeds userId-filtered SSE streams with heartbeat keepalives — keeping the database out of the hot push path.
04 · Development Principles
Outbox-first writes for at-least-once guarantees, consumed exactly once per user-visible stream; userId kept at the top of the event contract so streaming never parses business payloads; a central broker instead of per-request bus subscriptions to bound fan-out and eliminate per-user DB work; replay of unprocessed outbox rows for crash recovery; graceful degradation — events without a resolvable recipient still persist as DB notifications for pull-based recovery; signed webhook verification, request-rate limiting and hardened headers (helmet) on every ingress; and an API-first contract (Swagger docs) with structured Pino logging for observability.
05 · Impact
A full-commerce backend where identity, catalog, ordering, payment, media and real-time notification cooperate under one reliability model: order → inventory → email → notification flows execute observably (Pino logs, Swagger docs, rate-limited, helmet-secured), live delivery is memory-only so latency stays low, and the outbox guarantees mean no lost emails, no double stock deductions, and no drifting payment states — even when webhooks and transactions interleave.