E-Commerce Microservices Platform

A scalable, cloud-native e-commerce platform built with microservices architecture using Go, gRPC, GraphQL, and Docker.

What is it?

This is a production-ready e-commerce microservices application that demonstrates modern backend architecture patterns. The system is composed of four independent services that communicate via gRPC, unified behind a GraphQL API gateway:

• Account Service: Manages user account creation and retrieval
• Catalog Service: Handles product management with advanced search capabilities
• Order Service: Processes and manages customer orders
• GraphQL Gateway: Provides a unified API endpoint for client applications

Each microservice is independently deployable, scalable, and maintains its own database following the database-per-service pattern.

Why are we using it?

Architecture Benefits

1. Microservices Architecture

   • Independent service deployment and scaling
   • Fault isolation - failure in one service doesn't crash the entire system
   • Technology flexibility - each service can use optimal technologies
   • Easier maintenance and testing of smaller codebases

2. Polyglot Persistence

   • PostgreSQL for transactional data (Account & Order services)
   • Elasticsearch for product search and catalog (Catalog service)
   • Each service uses the database best suited for its needs

3. API Gateway Pattern

   • Single entry point for clients via GraphQL
   • Reduces client complexity by aggregating multiple service calls
   • Provides flexible querying capabilities with GraphQL

4. Service Communication

   • gRPC for efficient inter-service communication
   • Protocol Buffers for strongly-typed contracts
   • High performance with HTTP/2 and binary serialization

How are we using it?

Prerequisites

• Docker & Docker Compose
• Go 1.25.1 or higher (for local development)
• Protocol Buffer compiler (for modifying .proto files)

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd ecom-microservice

2. Start all services with Docker Compose

   docker-compose up --build

3. Access the GraphQL Playground

   Open your browser and navigate to: http://localhost:8000/playground

Architecture Overview

┌─────────────┐
│   Clients   │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ GraphQL Gateway │ :8000
│ (Port 8080)     │
└────────┬────────┘
         │
    ┌────┴─────┬──────────┐
    ▼          ▼          ▼
┌─────────┐ ┌──────────┐ ┌────────┐
│ Account │ │ Catalog  │ │ Order  │
│ Service │ │ Service  │ │Service │
│ :8080   │ │ :8080    │ │ :8080  │
└────┬────┘ └────┬─────┘ └───┬────┘
     │           │           │
     ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │Elastic-  │ │PostgreSQL│
│ DB       │ │ search   │ │ DB       │
└──────────┘ └──────────┘ └──────────┘

Service Endpoints

Service	Internal Port	External Port	Protocol
GraphQL Gateway	8080	8000	HTTP/GraphQL
Account Service	8080	-	gRPC
Catalog Service	8080	-	gRPC
Order Service	8080	-	gRPC

Example GraphQL Operations

Create an Account

mutation {
  createAccount(account: { name: "John Doe" }) {
    id
    name
  }
}

Create a Product

mutation {
  createProduct(product: {
    name: "Laptop"
    description: "High-performance laptop"
    price: 999.99
  }) {
    id
    name
    price
  }
}

Create an Order

mutation {
  createOrder(order: {
    accountId: "account-id-here"
    products: [
      { id: "product-id-here", quantity: 2 }
    ]
  }) {
    id
    totalPrice
    createdAt
    products {
      name
      quantity
      price
    }
  }
}

Query Products with Search

query {
  products(query: "laptop", pagination: { skip: 0, take: 10 }) {
    id
    name
    description
    price
  }
}

Query Account with Orders

query {
  accounts(id: "account-id-here") {
    id
    name
    orders {
      id
      totalPrice
      createdAt
      products {
        name
        quantity
      }
    }
  }
}

Technologies Used

Core Technologies

Technology	Purpose	Version
Go	Primary programming language	1.25.1
gRPC	Inter-service communication	v1.75.1
Protocol Buffers	Service contract definitions	v1.36.6
GraphQL	Client-facing API	-
Docker	Containerization	Latest
Docker Compose	Multi-container orchestration	Latest

Databases

Database	Service	Purpose
PostgreSQL	Account, Order	Relational data storage
Elasticsearch	Catalog	Product search and indexing

Go Libraries & Frameworks

• gqlgen (v0.17.78) - GraphQL server generation
• lib/pq (v1.10.9) - PostgreSQL driver
• go-elasticsearch (v9.1.0) - Elasticsearch client
• kelseyhightower/envconfig (v1.4.0) - Environment variable configuration
• segmentio/ksuid (v1.0.4) - Unique ID generation
• tinrab/retry (v1.0.0) - Retry logic for database connections

Development Tools

• Protocol Buffer Compiler (protoc) - Generate Go code from .proto files
• gqlgen - Generate GraphQL resolvers and models

Project Structure

ecom-microservice/
├── account/ # Account microservice
│ ├── account.proto # gRPC service definition
│ ├── cmd/account/ # Service entry point
│ ├── pb/ # Generated protobuf code
│ ├── repository.go # Database layer
│ ├── service.go # Business logic
│ ├── server.go # gRPC server
│ ├── client.go # gRPC client
│ ├── up.sql # Database schema
│ └── .Dockerfile # Container definitions
│
├── catalog/ # Catalog microservice
│ ├── catalog.proto # gRPC service definition
│ ├── cmd/catalog/ # Service entry point
│ ├── pb/ # Generated protobuf code
│ ├── repository.go # Elasticsearch layer
│ ├── service.go # Business logic
│ ├── server.go # gRPC server
│ └── client.go # gRPC client
│
├── order/ # Order microservice
│ ├── order.proto # gRPC service definition
│ ├── cmd/order/ # Service entry point
│ ├── pb/ # Generated protobuf code
│ ├── repository.go # Database layer
│ ├── service.go # Business logic
│ ├── server.go # gRPC server
│ ├── client.go # gRPC client
│ └── up.sql # Database schema
│
├── graphql/ # GraphQL API Gateway
│ ├── schema.graphql # GraphQL schema
│ ├── main.go # Gateway entry point
│ ├── graph.go # GraphQL server setup
│ ├── _resolver.go # Resolver implementations
│ └── models.go # GraphQL models
│
├── docker-compose.yml # Development environment
├── docker-compose.prod.yml # Production environment
└── go.mod # Go dependencies

Development

Regenerate Protocol Buffers

When you modify .proto files:

cd account
protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    account.proto

Regenerate GraphQL Code

When you modify schema.graphql:

cd graphql
go run github.com/99designs/gqlgen generate

Running Services Locally

Each service can be run independently:

# Account Service
cd account/cmd/account
DATABASE_URL=postgres://postgres:admin@localhost:5432/postgres?sslmode=disable go run main.go

# Catalog Service
cd catalog/cmd/catalog
ELASTICSEARCH_URL=http://localhost:9200 go run main.go

# Order Service
cd order/cmd/order
DATABASE_URL=postgres://postgres:admin@localhost:5432/postgres?sslmode=disable \
ACCOUNT_SERVICE_URL=localhost:8080 \
CATALOG_SERVICE_URL=localhost:8080 go run main.go

# GraphQL Gateway
cd graphql
ACCOUNT_SERVICE_URL=localhost:8080 \
CATALOG_SERVICE_URL=localhost:8080 \
ORDER_SERVICE_URL=localhost:8080 go run main.go

Environment Variables

Account Service

• DATABASE_URL - PostgreSQL connection string

Catalog Service

• ELASTICSEARCH_URL - Elasticsearch endpoint

Order Service

• DATABASE_URL - PostgreSQL connection string
• ACCOUNT_SERVICE_URL - Account service gRPC endpoint
• CATALOG_SERVICE_URL - Catalog service gRPC endpoint

GraphQL Gateway

• ACCOUNT_SERVICE_URL - Account service gRPC endpoint
• CATALOG_SERVICE_URL - Catalog service gRPC endpoint
• ORDER_SERVICE_URL - Order service gRPC endpoint

Features

• ✅ Microservices architecture with domain-driven design
• ✅ gRPC for efficient inter-service communication
• ✅ GraphQL API with playground for easy testing
• ✅ Database per service pattern
• ✅ Full-text search with Elasticsearch
• ✅ Docker containerization
• ✅ Automatic retry logic for database connections
• ✅ Environment-based configuration
• ✅ Unique ID generation with KSUID
• ✅ Pagination support for listing operations

Author

Aditya Pandey