🛒 Marketplace Microservices

A microservices-based marketplace platform with an API gateway, business services, and a RabbitMQ, Prometheus, and Grafana observability layer.

---

📃 About  •   🏗️ Architecture  •   🛠️ Microservices  •   🧠 Key Concepts & Patterns  •   ⚙️ Tech Stack  •   📡 Communication  •   🚀 Getting Started

---

📃 About

Marketplace Microservices is a service-oriented marketplace implemented as a monorepo of independently deployable NestJS services. The repository organizes the customer-facing API, business workflows, authentication and users, catalog management, payment orchestration, checkout and ordering, and the observability tooling around a consistent event-driven architecture.

Instead of a single process handling all concerns, the codebase separates responsibilities into service folders such as the API gateway, users service, products service, checkout service, payments service, messaging infrastructure, and observability stack. The design enables isolated database ownership, asynchronous messaging, and focused operational monitoring.

🏗️ Architecture

The repository follows a layered deployment model in which the API gateway receives client traffic, service modules own their business responsibilities, RabbitMQ carries asynchronous payment events, and Prometheus and Grafana provide the observability and metrics layer.

flowchart TB
    subgraph ClientBoundary[Client / External Access]
        Client[Client]
    end

    subgraph GatewayBoundary[Gateway Boundary]
        Gateway[api-gateway\nProxyService + route controllers]
    end

    subgraph DomainServices[Business Services]
        Users[users-service]
        Products[products-service]
        Checkout[checkout-service]
        Payments[payments-service]
    end

    subgraph IntegrationBoundary[Async Event Boundary]
        Broker[RabbitMQ\nMessaging Service]
    end

    subgraph ObservabilityBoundary[Observability Boundary]
        Prometheus[Prometheus]
        Grafana[Grafana]
    end

    Client --> Gateway
    Gateway --> Users
    Gateway --> Products
    Gateway --> Checkout
    Gateway --> Payments

    Checkout -->|payment.order| Broker
    Broker -->|payment.order| Payments
    Payments -->|payment.result| Broker
    Broker -->|result propagation| Checkout

    Gateway -. metrics .-> Prometheus
    Users -. metrics .-> Prometheus
    Products -. metrics .-> Prometheus
    Checkout -. metrics .-> Prometheus
    Payments -. metrics .-> Prometheus

    Prometheus --> Grafana

Loading

🛠️ Microservices

Service	Responsibility	README
api-gateway	Single entry point for the marketplace and route proxying for users, products, checkout and payment traffic.	README
checkout-service	Cart, orders, checkout orchestration, and RabbitMQ event publication for payment processing.	README
messaging-service	RabbitMQ broker and management interface for asynchronous event exchange.	README
observability-stack	Prometheus metrics collection and Grafana dashboard provisioning for service observability.	README
payments-service	Payment processing, fake gateway simulation, payment result publication, DLQ inspection and metrics.	README
products-service	Product catalog, product listing, and product-owned data access.	README
users-service	Registration, login, authentication flows, and user profile logic.	README

🧠 Key Concepts & Patterns

• API Gateway Pattern — the repository exposes a single API entry point in the gateway service that routes incoming traffic to the correct internal service.
• Proxy Pattern — the gateway implements a reusable ProxyService component that forwards requests to the downstream services while applying fallback, retry, timeout, and circuit-breaker policies.
• Database per Service — the services keep ownership boundaries around their own databases in their code and configuration patterns.
• Event-Driven Architecture — the checkout and payments services exchange payment-related events through RabbitMQ instead of synchronous direct calls.
• Messaging Patterns — the repository uses publish/subscribe and point-to-point queue patterns across the payment and event transaction flow.
• Dead Letter Queue (DLQ) — the payments service includes DLQ inspection, reprocessing, discard, and purge facilities for failed messages.
• Circuit Breaker — resilience patterns are represented by the project's gateway proxy and retry/fallback strategy patterns in the infrastructure layer.
• Rate Limiting — the gateway and proxy layers show request control patterns that restrict call intensity and protect downstream services.
• Idempotency — payment records store order-level processing state, and the payment event model supports repeated order dispatch without duplicate accounting semantics.

⚙️ Tech Stack

The repository is mainly implemented in TypeScript through the NestJS framework. Shared technical foundations across the services include:

• 🟦 TypeScript — primary implementation language.
• ⚙️ NestJS — modular service framework for the application services.
• 🌐 Express — HTTP runtime used by the NestJS application runtime.
• 🐘 PostgreSQL — relational database technology used across the services.
• 🐇 RabbitMQ — asynchronous event broker used for payment and checkout integration flows.
• 🐳 Docker Compose — local developer and infrastructure orchestration for the messaging and observability services.
• 📊 Prometheus — metrics collection and alert evaluation layer.
• 📈 Grafana — dashboard and visualization layer.
• 🧪 Jest — automated test framework used by the services.
• 🐼 TypeORM — object-relational mapping pattern applied across the repository's database-backed services.

📡 Communication

The repository uses two communication styles:

• Synchronous HTTP — the API gateway receives requests and proxies them to the internal services via configured routes and controller patterns.
• Asynchronous messaging — the checkout and payments services exchange payment order and payment result events over RabbitMQ exchanges and queues.

This combination enables the gateway to keep a clean external interface while the internal services communicate through durable events for the payment lifecycle.

🚀 Getting Started

Prerequisites

• Node.js 18+ or 22+
• npm
• Docker and Docker Compose
• An available Postgres and RabbitMQ instance for the service configuration files

Local development

From the repository root:

git clone https://github.com/joschonarth/marketplace-microservices.git
cd marketplace-microservices

Then run the required infrastructure services:

cd messaging-service
docker compose up -d

cd ../observability-stack
docker compose up -d

Finally, start each NestJS service separately:

cd ../api-gateway
npm install
npm run start:dev

Repeat the same shape of command for the other service folders:

cd ../users-service && npm run start:dev
cd ../products-service && npm run start:dev
cd ../checkout-service && npm run start:dev
cd ../payments-service && npm run start:dev

The repository's environment examples define ports and credentials such as 3000, 3001, 3003, 3004, 3005, and RABBITMQ_URL=amqp://admin:admin@localhost:5672.

---

⭐ Support this Project

If this marketplace microservices architecture helps you understand how a service-oriented commerce platform is organized, consider giving the repository a star on GitHub.

---

Made with ♥ by João Otávio Schonarth