Real-Time Order Processing System

Go + gRPC + HTTP Gateway + Worker Pool + WebSocket + PostgreSQL

A production-grade backend system built in Go demonstrating:

• Clean architecture
• gRPC microservice communication
• HTTP API Gateway
• Concurrent worker pool
• Real-time updates via WebSockets
• PostgreSQL persistence
• Interceptors (logging, recovery, request tracing)
• Graceful shutdown
• Context propagation
• Dockerized microservice deployment

This project simulates a real-world backend system architecture commonly used in scalable microservice environments.

---

Architecture Overview

Client (HTTP / WebSocket)
        │
        ▼
API Gateway (HTTP :8080)
        │
        ▼
gRPC Order Service (:50051)
        │
        ├── PostgreSQL
        └── Worker Pool (5 goroutines)
                    │
                    ▼
              WebSocket Hub (:8081)
                    │
                    ▼
                 Client

---

Containerized Architecture (Docker)

                +---------------------+
                |    API Gateway      |
                |      (HTTP)         |
                |      :8080          |
                +----------+----------+
                           |
                           v
                +---------------------+
                |     Order Service   |
                |      gRPC Server    |
                |      :50051         |
                |  WebSocket :8081    |
                +----------+----------+
                           |
                           v
                +---------------------+
                |     PostgreSQL      |
                |       :5432         |
                +---------------------+

All services run inside a Docker network and communicate using service names.

Example:

api-gateway → order-service:50051
order-service → postgres:5432

---

Tech Stack

Layer	Technology
Language	Go
Transport	gRPC
API Layer	HTTP (Chi Router)
Real-Time	WebSocket (Melody)
Concurrency	Goroutines + Channels
Database	PostgreSQL
Logging	Zap
Proto	Protocol Buffers
Containerization	Docker + Docker Compose

---

Project Structure

order-system/
│
├── cmd/
│   ├── order-service/        # gRPC + WebSocket service
│   │   └── Dockerfile
│   │
│   ├── api-gateway/          # HTTP gateway
│   │   └── Dockerfile
│   │
│   └── main.go               # standalone application for manual testing
│
├── internal/
│   ├── config/               # Environment configuration loader
│   ├── db/                   # PostgreSQL connection + retry logic
│   ├── order/                # Domain + service + repository
│   ├── worker/               # Worker pool implementation
│   ├── ws/                   # WebSocket hub
│   └── interceptor/          # gRPC interceptors
│
├── proto/
│   ├── order.proto
│   ├── order.pb.go
│   └── order_grpc.pb.go
│
├── migrations/               # DB schema migrations
│
├── pkg/
│   └── logger/               # Zap logger setup
│
├── docker-compose.yml        # container orchestration
│
├── go.mod
└── go.sum

---

System Design Concepts

Clean Architecture

• Business logic is independent of transport layer.
• Repository pattern isolates database access.
• Services depend on abstractions rather than implementations.
• Transport layers (HTTP/gRPC) simply adapt requests to the service layer.

---

Worker Pool Design

• Fixed 5 goroutines
• Buffered job queue
• Context-aware processing
• Graceful shutdown support

---

Real-Time Notification Flow

Order Created
      │
      ▼
Worker Processes Order
      │
      ▼
Order Status Updated in DB
      │
      ▼
WebSocket Hub Publishes Event
      │
      ▼
Subscribed Clients Receive Update

---

Running the System

The system can be run in two ways:

1. Local Development (manual services)
2. Docker Deployment (recommended)

---

Local Development Setup

Install Requirements

• Go 1.21+
• PostgreSQL
• Docker
• protoc
• protoc-gen-go
• protoc-gen-go-grpc

---

Start PostgreSQL

docker run --name order-postgres \
-e POSTGRES_USER=admin \
-e POSTGRES_PASSWORD=admin123 \
-e POSTGRES_DB=orderdb \
-p 5432:5432 \
-d postgres

---

Run Migrations

migrate -path migrations \
-database "postgres://admin:admin123@localhost:5432/orderdb?sslmode=disable" up

---

Run Order Service

go run cmd/order-service/main.go

Runs on:

gRPC      :50051
WebSocket :8081

---

Run API Gateway

go run cmd/api-gateway/main.go

Runs on:

HTTP :8080

---

Docker Deployment (Recommended)

The entire system can be started with one command using Docker Compose.

This launches:

• PostgreSQL container
• Order Service container
• API Gateway container

All connected through a shared Docker network.

---

Start the System

From the project root:

docker compose up --build

Docker will:

1. Build Go binaries
2. Create containers
3. Start PostgreSQL
4. Start order-service
5. Start API gateway

---

Stop the System

docker compose down

---

View Running Containers

docker ps

Expected services:

order-postgres
order-service
api-gateway

---

API Endpoints

Create Order

POST

http://localhost:8080/orders

Body:

{
  "user_id": "user-1",
  "amount": 100
}

---

Get Order

GET

http://localhost:8080/orders/{order_id}

---

WebSocket Testing (Postman)

1. Open Postman
2. Create WebSocket request

Connect to:

ws://localhost:8081/ws

Send the Order ID:

"ORDER_ID_HERE"

When the worker processes the order you will receive:

{
  "order_id": "...",
  "status": "PROCESSED"
}

---

Production Features

gRPC Interceptors

• Logging interceptor
• Panic recovery interceptor
• Request ID tracing

---

Context Propagation

• Database queries use context
• Worker pool supports cancellation
• HTTP requests propagate context to gRPC
• gRPC calls use timeouts

---

Graceful Shutdown

The system safely handles:

• SIGINT / SIGTERM
• Worker shutdown
• gRPC GracefulStop
• Database connection close

---

UML DIAGRAMS

---

Component Diagram

+----------------+
|   API Gateway  |
+----------------+
        |
        v
+----------------+
|  gRPC Service  |
+----------------+
    |        |
    v        v
+--------+  +-------------+
| Worker |  | PostgreSQL  |
+--------+  +-------------+
    |
    v
+--------------+
| WebSocket Hub|
+--------------+

---

Class Diagram

+------------------+
| OrderService     |
|------------------|
| +CreateOrder()   |
| +GetOrder()      |
| +UpdateStatus()  |
+------------------+
         |
         v
+----------------------+
| OrderRepository      |
|----------------------|
| +Create()            |
| +GetByID()           |
| +UpdateStatus()      |
+----------------------+
         |
         v
+----------------------------+
| PostgresOrderRepository    |
+----------------------------+

---

Sequence Diagram

Client → API Gateway → gRPC Service → Database
                                     ↓
                                  Worker Pool
                                     ↓
                               WebSocket Hub
                                     ↓
                                  Client

---

Concurrency Model

                +------------------+
                | Job Channel      |
                +------------------+
                 |   |   |   |   |
                 v   v   v   v   v
                 W1  W2  W3  W4  W5

---

Scalability

Current system:

• Single instance
• In-memory job queue
• In-memory WebSocket subscriptions

Scaling strategy:

• Redis / Kafka job queue
• Redis Pub/Sub for WebSocket notifications
• Horizontal scaling behind load balancer

---

Future Improvements

• Prometheus metrics
• OpenTelemetry tracing
• JWT authentication
• Kubernetes deployment
• Distributed worker queue
• Redis Pub/Sub for notifications

---

Author

Built as a backend systems learning project demonstrating production-ready architecture using Go.

---

Contact

X: https://x.com/i_krsna4
LinkedIn: https://www.linkedin.com/in/krishnathakur1/