---

📋 Overview

ecommerce-microservices is a production-grade, cloud-native e-commerce platform built with a microservice architecture. It consists of 13 Spring Boot 3 backend services, an Apache APISIX API Gateway, a Next.js 16 frontend, and a full suite of infrastructure — all deployable on Kubernetes (k3d) with a single command.

⚡ Backend	13 microservices · Java 21 · Spring Boot 3.3.5
🚪 Gateway	Apache APISIX 3.9 · Rate limiting · JWT validation
🗄️ Databases	PostgreSQL 16 · Redis 7 · Elasticsearch 8
📨 Messaging	Apache Kafka 3.9 (KRaft mode, no Zookeeper)
🔐 Auth	Keycloak 26 · OAuth2 / OIDC · JWT
☁️ Storage	RustFS (S3-compatible)
🐳 Deploy	Docker Compose · k3d / Kubernetes · ArgoCD

---

🛠️ Technology Stack

Backend

Runtime	Java 21 (Virtual Threads)
Framework	Spring Boot 3.3.5, Spring Security 6, Spring Data JPA
Database	PostgreSQL 16, Liquibase migrations
Search	Elasticsearch 8, Spring Data Elasticsearch
Messaging	Apache Kafka 3.9 (KRaft), Spring Kafka
Security	Keycloak 26, OAuth2 / OIDC, JWT, Spring Security Resource Server
Gateway	Apache APISIX 3.9 (OpenID Connect, rate limiting, CORS)
Storage	RustFS (S3-compatible), AWS SDK v2
Observability	Micrometer, Prometheus, Spring Boot Actuator
API Docs	Springdoc OpenAPI 3, Swagger UI w/ PKCE
Resilience	Resilience4j (circuit breaker, retry)
Build	Maven, Jib (Dockerless containerization)

Frontend

Framework	Next.js 16.2, React 19.2
State	Zustand 5, TanStack Query 5
Styling	Tailwind CSS 4, Lucide icons
HTTP	Axios

Infrastructure

Local K8s	k3d (K3s in Docker), NGINX Ingress Controller
Production	Kubernetes, ArgoCD (GitOps)
Registry	GitHub Container Registry (ghcr.io)
CI	GitHub Actions, SonarCloud

---

🚀 Quick Start

Prerequisites

• Docker Desktop (macOS / Windows) or Docker Engine (Linux)
• 8 GB+ RAM allocated to Docker

One-Command Setup (k3d)

git clone https://github.com/hoangtien2k3/ecommerce-microservices.git
cd ecommerce-microservices
bash start-ecommerce.sh

The script automatically:

1. Installs k3d and kubectl (if missing)
2. Creates a local Kubernetes cluster
3. Deploys NGINX Ingress Controller
4. Applies secrets, config maps, and infrastructure (PostgreSQL, Redis, Kafka, Elasticsearch, RustFS, Keycloak)
5. Deploys APISIX gateway + all 13 backend services + frontend
6. Updates /etc/hosts

Wait ~5 minutes for all pods to become ready:

kubectl get pods -n ecommerce -w

URLs

Service	URL
🏠 Frontend	http://ecommerce.local
🚪 API Gateway	http://api.ecommerce.local
🔐 Keycloak Admin	http://keycloak.ecommerce.local
📦 RustFS Console	http://rustfs.ecommerce.local/rustfs/console

---

📁 Project Structure

ecommerce-microservices/
├── auth-service/                   # Port 8088
├── common-lib/                     # Shared library
│   ├── common-core/                #   Contracts, exceptions, i18n
│   ├── common-spring/              #   Auto-configurations
│   ├── common-security/            #   JWT / OAuth2 security
│   ├── common-keycloak/            #   Keycloak admin client
│   ├── common-kafka/               #   Kafka / CDC helpers
│   ├── common-logging/             #   AOP performance logging
│   └── common-storage/             #   S3 object storage abstraction
├── deploy/
│   └── apisix/                     # APISIX standalone config
├── docker/
│   ├── keycloak/import/            # Keycloak realm configuration
│   └── postgres/init/              # Database creation scripts
├── docker-compose.yml              # Full-stack local orchestration
├── favourite-service/              # Port 8081
├── frontend/                       # Next.js 16 application
├── inventory-service/              # Port 8082
├── k3d-config.yaml                 # k3d cluster definition
├── k3d-setup.sh                    # One-shot K8s deployment script
├── k8s/                            # Kubernetes manifests
│   ├── argocd/                     # ArgoCD GitOps configurations
│   ├── backend/                    # 13 service deployments
│   ├── frontend/                   # Frontend deployment
│   ├── gateway/                    # APISIX Ingress CRDs
│   ├── infra/                      # Infrastructure deployments
│   ├── ingress/                    # NGINX Ingress rules
│   ├── configmap.yaml
│   ├── namespace.yaml
│   └── secrets.yaml
├── Makefile                        # Build & deploy automation
├── media-service/                  # Port 8083
├── notification-service/           # Port 8090
├── order-service/                  # Port 8084
├── payment-service/                # Port 8085
├── pom.xml                         # Parent POM
├── product-service/                # Port 8086
├── promotion-service/              # Port 8093
├── rating-service/                 # Port 8089
├── search-service/                 # Port 8094
├── shipping-service/               # Port 8087
├── start-ecommerce.sh              # Entry point
└── tax-service/                    # Port 8091

---

📊 Observability

Every service exposes:

• Health: /actuator/health (liveness + readiness on port 9000)
• Metrics: /actuator/prometheus (Micrometer + Prometheus)
• Distributed Tracing: Correlation ID (X-Correlation-Id) propagated across all services
• APISIX Metrics: Prometheus metrics on port 9091

---

📈 Stats

Contributing

If you would like to contribute to the development of this project, please follow our contribution guidelines.

---

📄 License

MIT License
Copyright (c) 2026 Hoàng Anh Tiến