go‑grpc‑micro

A lightweight micro‑service playground written in Go that demonstrates how to combine gRPC, GraphQL, WebSockets, Docker, and Elasticsearch. It contains four independent services:

Service	Responsibility	Port	How to start
Account	Manage user accounts (PostgreSQL)	8080	docker-compose up account
Catalog	Store product catalogue (Elasticsearch)	8080	docker-compose up catalog
Order	Create & retrieve orders (PostgreSQL)	8080	docker-compose up order
GraphQL	Aggregated API for the above services (gRPC + WebSocket)	8000	docker-compose up graphql

The GraphQL API is the entry point for most consumers (http://localhost:8000). All services are network‑isolated inside Docker, so no local ports are required except for the GraphQL endpoint.

NOTE

• The repository does not ship a license. Please contact the maintainer before commercial use.
• Author, version, and description are not defined in the repo. Use the information above to get started.

---

✨ Features

• Micro‑service architecture – each domain is an isolated Docker container.
• gRPC services – fast binary APIs for internal communication.
• GraphQL façade – a single HTTP endpoint that aggregates data from all services.
• WebSocket support – real‑time subscriptions through GraphQL (currently not used, but wired).
• Containerised databases – PostgreSQL for account/order data, Elasticsearch for catalog.
• Automated build – docker-compose manages build contexts and dependencies.
• Simple authentication – (placeholder) environment variables; extend with JWT if needed.

---

🛠 Tech Stack

Category	Tool / Library
Language	Go 1.24.3
GraphQL	(https://github.com/99designs/gqlgen)
gRPC	google.golang.org/grpc
Database	PostgreSQL (account & order), Elasticsearch 6.2.4
Containerisation	Docker / docker‑compose
Utilities	envconfig, retry, ksuid, vektah gqlparser

---

🚀 Getting Started

Prerequisites

Item	Version	How to install
Git	2.17+	https://git-scm.com
Docker Engine	20.10+	https://docs.docker.com/engine/install/
Docker Compose	1.29+	https://docs.docker.com/compose/install/
Go	1.24.3	https://golang.org/doc/install
Make	4.3+	(optional, for convenience)

Tip – On macOS you can install Docker Desktop which bundles Docker Engine and Compose.

Installation

# 1️⃣  Clone the repo
git clone https://github.com/Adityaadpandey/go-grpc-micro.git
cd go-grpc-micro

# 2️⃣  Install Go dependencies
go mod tidy

The Go modules will pull the required packages for the services.

Configuration

All services read configuration from environment variables. The docker-compose.yaml file already sets them, but if you run a service manually you need to provide the following:

Service	Variable	Example
Account / Order	DATABASE_URL	postgres://user:pass@host:5432/dbname?sslmode=disable
Catalog	DATABASE_URL	http://elasticsearch:9200
GraphQL	ACCOUNT_SERVICE_URL, CATALOG_SERVICE_URL, ORDER_SERVICE_URL	account:8080 (Docker internal hostname)

When using Docker Compose, these are set automatically.

---

🎯 Usage

Development Mode

# Start all services in the background
docker-compose up -d

# Tail logs of all containers
docker-compose logs -f

The GraphQL API will be reachable at http://localhost:8000. The gRPC services are listening on account:8080, catalog:8080, and order:8080 inside the Docker network.

Production Mode

For a production‑grade deployment you should:

1. Build the images ahead of time (docker-compose build).
2. Use a reverse proxy (NGINX, Traefik) in front of the GraphQL endpoint.
3. Persist PostgreSQL data using named volumes or an external database.
4. Secure the gRPC endpoints with TLS (not currently configured).

---

📚 API Documentation

GraphQL API

The GraphQL schema is generated by gqlgen and lives in graphql/schema.graphqls. Typical queries/mutations:

# Query all products from the catalog
query {
  products {
    id
    name
    description
    price
  }
}

# Create an order
mutation {
  createOrder(accountId: "acct_123", products: [
    { productId: "p_001", quantity: 2 },
    { productId: "p_003", quantity: 1 }
  ]) {
    id
    createdAt
    totalPrice
    accountId
  }
}

# Fetch orders for an account
query {
  ordersByAccount(accountId: "acct_123") {
    id
    createdAt
    totalPrice
  }
}

Note: The GraphQL server also exposes a WebSocket endpoint (/graphql) for subscriptions (future‑proofed).

gRPC API

The Order service gRPC definition is in order/pb/order.proto. A minimal client in Go:

package main

import (
    "context"
    "log"
    "time"

    "github.com/adityaadpandey/go-grpc-micro/order"
    "github.com/adityaadpandey/go-grpc-micro/order/pb"
)

func main() {
    c, err := order.NewClient("localhost:8080") // replace with actual host:port
    if err != nil { log.Fatal(err) }
    defer c.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    // Create an order
    resp, err := c.PostOrder(ctx, "acct_123", order.OrderedProduct{
        {ID: "p_001", Quantity: 2},
        {ID: "p_003", Quantity: 1},
    })
    if err != nil { log.Fatal(err) }

    log.Printf("Order created: %+v", resp)
}

For the other services (Account, Catalog) you would similarly use the generated protobuf client.

---

🐳 Docker Deployment

# Build all images
docker-compose build

# Bring up everything
docker-compose up

# Stop
docker-compose down

If you want to run a single service:

docker-compose up account          # Account service only
docker-compose up order account catalog  # Order + dependencies

Persisting Data

• PostgreSQL containers expose a named volume (account_db / order_db) that stores the data on the host.
• Elasticsearch stores data in its own data directory; you can add a volume mapping if you want to keep it outside the container.

---

👨‍💻 Development

Project Structure

go-grpc-micro/
├── account/        # Account service (Go + PostgreSQL)
├── catalog/        # Catalog service (Elasticsearch)
├── graphql/        # GraphQL façade (gqlgen)
├── order/          # Order service (Go + PostgreSQL)
├── docker-compose.yaml
├── go.mod
├── go.sum
└── README.md

Building & Running Locally

You can run each service directly with go run (requires Docker‑enabled database locally).

# Account
cd account
go run ./cmd/account

# Order
cd order
go run ./cmd/order

# Catalog
cd catalog
go run ./cmd/catalog

# GraphQL
cd graphql
go run ./cmd/graphql

Ensure the environment variables are set as described in Configuration.

Testing

No automated tests are included in this repository. If you add tests, run them with:

go test ./...

Linting & Formatting

go fmt ./...
go vet ./...

---

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/awesome-feature).
3. Commit your changes (git commit -m "Add awesome feature").
4. Push the branch (git push origin feature/awesome-feature).
5. Open a Pull Request.

Please follow Go conventions (gofmt) and keep the Docker configuration minimal.

---

📄 License

This project does not include an explicit license. If you plan to use or distribute this code, please contact the author for clarification.

---

🆘 Support

• Check the Issues tab on GitHub for known bugs or feature requests.
• If you encounter a new issue, open a detailed ticket with logs and environment details.
• For community help, join relevant Go or gRPC discussion forums.

---

Project Complexity: Medium • Setup Time: 15‑30 min • Maintenance: Stable (no active tests)

---

🛠️ Built with passion by NOVA 💙 — a product by Aditya

sudo docker compose logs frontend --tail=50 sudo docker compose logs graphql --tail=20 sudo docker compose logs account --tail=20