Cluster Node
A full e-commerce API built the way production services should be: designed for failure, documented and deployed for real on Kubernetes.
In plain words
Cluster Node is the engine behind an online shop: logins, products, orders and stock. It is built to keep working correctly when things go wrong, so a customer is never charged twice and stock never goes negative. It also ships with real cloud infrastructure, so it can grow with traffic.
Interactive preview
How Cluster Node works
Interactive · illustrative sample data
The challenge
Most sample backends stop at CRUD. Real stores need orders that stay correct under concurrent requests, retries that don't double-charge, and services that survive a failing payment provider.
Shipping that safely also needs repeatable infrastructure, health checks and observability, not just `npm run dev`.
Our approach
Pick one domain (e-commerce) and go deep on correctness under concurrency, failure handling and documentation.
Deploy it the way a team would operate it: containerised, orchestrated, provisioned with code and released through GitOps.
Step by step
From first click to finished job
- 1
Customer places an order
The request carries an idempotency key and a correlation ID.
- 2
Inventory is reserved
Stock rows are locked so concurrent orders can't oversell.
- 3
Payment is attempted
Behind a circuit breaker, with clear failure states if the provider is down.
- 4
Domain events fire
Order lifecycle events notify downstream consumers.
- 5
Kubernetes keeps it healthy
Liveness/readiness probes and metrics drive restarts and scaling.
Capabilities
What it does
Auth with refresh tokens
JWT access tokens, rotating refresh tokens and role-based access control.
Idempotent orders
Idempotency keys on order creation so client retries never create duplicates.
Stock-safe inventory
Pessimistic locking on inventory updates; cancelled orders restore stock correctly.
Circuit breaker
External payment calls are wrapped so an outage degrades gracefully instead of cascading.
Observability
Health and readiness endpoints, metrics and correlation IDs across request logs.
OpenAPI docs
Swagger documentation generated from the route definitions, plus a React dashboard.
Engineering
Key decisions
Design for failure first
Idempotency, locking and circuit breaking are core, not afterthoughts.
Infrastructure as code
Terraform provisions the cluster and networking so environments are reproducible.
GitOps delivery
GitHub Actions builds images; ArgoCD syncs the cluster to what's in git.
Architecture
Tech stack
Service
- Node.js
- Express
- TypeScript
Data
- PostgreSQL
- Redis
Platform
- Docker
- Kubernetes
- Terraform
- ArgoCD
Quality
- OpenAPI
- GitHub Actions
Outcome
What it delivers
- Orders stay correct under retries and concurrent checkouts
- Reproducible infrastructure from a single Terraform + GitOps workflow
- Self-documenting API that frontend and partner teams can integrate against
Deep dives
Read the engineering notes
Production Node.js on Kubernetes — Lessons from Cluster Node
Building a portfolio-grade Node.js e-commerce API with JWT auth, idempotency, circuit breakers, OpenAPI docs, and real Docker/Kubernetes/Terraform deployment.
Services behind it