Skip to main content

Getting Started 🚀

This guide helps you set up ShopVerse – Intelligent Event-Driven E-Commerce Platform locally and understand how to run the system step by step.

ShopVerse is a production-grade, microservices-based, event-driven e-commerce platform, and the setup closely mirrors real-world backend system practices.

📋 Prerequisites​

Before starting, ensure the following tools are installed on your system.

🔹 Required​

  • Java 21
  • Node.js 20+
  • Docker & Docker Compose
  • Git

🔹 Optional (Recommended for Development)​

  • IntelliJ IDEA / VS Code
  • Postman / Thunder Client

📦 Project Repositories​

ShopVerse follows industry-standard repository separation.

🧱 High-Level Setup Flow​

Follow this order for local setup:

  1. Start shared infrastructure (databases, Kafka)
  2. Start backend microservices
  3. Access APIs through the API Gateway
  4. (Optional) Start the frontend application

🐳 Infrastructure Setup (Docker)​

ShopVerse uses Docker to run shared infrastructure locally.

Start infrastructure services​

docker-compose up -d

This starts:

  • PostgreSQL
  • MongoDB
  • Apache Kafka
  • Zookeeper
  • Other supporting services (as configured)

Verify running containers​

docker ps

▶️ Running Backend Microservices​

Each backend component is an independent Spring Boot microservice.

🔢 Recommended Startup Order​

  1. Service Registry (Eureka)
  2. API Gateway
  3. Auth Service
  4. User Service
  5. Product Service
  6. Order Service
  7. Payment Service
  8. Notification / Analytics / Recommendation Services

Start a service​

./mvnw spring-boot:run

or run directly from your IDE.

💡 Once infrastructure is running, services can be started independently.

🌐 Accessing the System​

After services start successfully:

API Gateway​

http://localhost:8080

All external requests must go through the API Gateway.

🔐 Authentication (Quick Test)​

Register a User​

POST /api/auth/register

Login​

POST /api/auth/login

Sample Response​

{
  "token": "JWT_TOKEN"
}

Use the token in subsequent requests:

Authorization: Bearer <JWT_TOKEN>

📡 Event-Driven Components​

Some services work asynchronously using Kafka:

  • Notification Service
  • Analytics Service
  • Recommendation Service

These services:

  • Consume Kafka events
  • Do not require direct API calls
  • Process data asynchronously

This design ensures loose coupling, scalability, and fault tolerance.

⚠️ Common Issues & Fixes​

❌ Kafka not starting​

✔ Ensure Docker has sufficient memory ✔ Check logs:

docker-compose logs kafka

❌ 401 Unauthorized​

✔ Ensure requests go through the API Gateway ✔ Verify JWT token validity

❌ Service not discovered​

✔ Check Eureka dashboard ✔ Verify spring.application.name configuration

🧪 Health Checks​

Each service exposes a health endpoint:

GET /actuator/health

Use this to verify service availability during development.

🧠 Recommended Learning Path​

If you are new to ShopVerse, follow this order:

  1. Architecture Overview
  2. Authentication & Security Flow
  3. Service-by-Service Documentation
  4. Kafka Event Flow
  5. Deployment Strategy

📌 Notes​

  • ShopVerse is modular by design
  • Services scale independently
  • Infrastructure is shared using Docker
  • APIs are documented separately

✅ Next Steps​

Once setup is complete:

  • Explore the Architecture section
  • Review Auth & Security design
  • Dive into Individual Microservices

🎉 You’re now ready to explore ShopVerse in depth.