GoMicro - Go Microservices Architecture

Production-Ready Microservices with Kong Gateway & NATS

A complete microservices implementation using GoServe framework, Kong API Gateway, NATS messaging, PostgreSQL, MongoDB, and Redis.

---

Overview

This project demonstrates a production-ready microservices architecture built with the GoServe framework. It breaks down a monolithic blogging platform into independent services using Kong as API Gateway and NATS for inter-service communication. Each service maintains its own database and cache, showcasing true microservices best practices with service isolation, independent scaling, and fault tolerance.

The architecture implements authentication, authorization, and API key validation across distributed services while maintaining clean separation of concerns and independent deployability.

Features

• GoServe Micro Framework - Built on production-ready GoServe v2 with microservices support
• Kong API Gateway - Single entry point with custom Go plugin for API key validation
• NATS Messaging - Asynchronous inter-service communication with request/reply patterns
• Service Isolation - Each service with dedicated database and Redis instance
• PostgreSQL & MongoDB - Auth service with PostgreSQL, Blog service with MongoDB
• JWT Authentication - Token-based authentication with refresh token support
• Role-Based Authorization - Fine-grained access control across services
• Custom Kong Plugin - Go-based API key validation plugin
• Docker Compose Ready - Multiple configurations for development, testing, and production
• Load Balancing - Pre-configured setup for horizontal scaling
• Health Checks - Service health monitoring and dependency management
• Auto Migrations - Database schema migrations on startup
• Development Tools - pgAdmin, Mongo Express, Redis Commander included

Technology Stack

Component	Technology
Language	Go 1.21+
Framework	GoServe v2
API Gateway	Kong
Message Broker	NATS
Web Framework	Gin
Auth Database	PostgreSQL (pgx)
Blog Database	MongoDB (mongo-driver)
Cache	Redis (go-redis)
Migrations	golang-migrate
Authentication	JWT tokens
Validation	validator
Configuration	Environment variables

Quick Start

Prerequisites

• Docker & Docker Compose (Installation Guide)
• Go 1.21+ (for local development)

Installation

1. Clone the Repository

git clone https://github.com/afteracademy/gomicro.git
cd gomicro

2. Generate RSA Keys

go run .tools/rsa/keygen.go

3. Create Environment Files

go run .tools/copy/envs.go 

4. Start with Docker Compose

# Full stack with all services
docker compose up --build

The API will be available at: http://localhost:8000 (via Kong Gateway)

5. Health Check

# Check Kong Gateway
curl http://localhost:8001/status

# Check NATS
curl http://localhost:8222/varz

Access Points

Service	URL	Description
Kong Gateway	http://localhost:8000	API Entry Point
Kong Admin	http://localhost:8001	Kong Configuration
NATS Monitoring	http://localhost:8222	NATS Dashboard
PostgreSQL	localhost:5432	Auth Database
MongoDB	localhost:27017	Blog Database
Redis (Auth)	localhost:6379	Auth Cache
Redis (Blog)	localhost:6380	Blog Cache

Development Tools (with docker-compose.dev.yml):

Tool	URL	Purpose
pgAdmin	http://localhost:5050	PostgreSQL Management
Mongo Express	http://localhost:8082	MongoDB Management
Redis Commander	http://localhost:8083	Redis Management

Troubleshooting

If you encounter issues:

• Ensure ports 8000, 8001, 5432, 27017, 6379, 6380, 4222 are available
• Check service logs: docker compose logs -f [service_name]
• Clean slate: docker compose down -v && docker compose up --build

For detailed setup, usage, and troubleshooting: README-DOCKER.md

Deployment Scenarios

1. Full Stack Development (Recommended)

docker compose up --build

Starts all services with Kong, NATS, and shared databases.

Adds pgAdmin, Mongo Express, and Redis Commander for database management.

2. Individual Service Development

# Auth service only
cd auth_service && docker compose up --build

# Blog service only  
cd blog_service && docker compose up --build

Runs a single service in isolation for fast iteration and debugging.

3. Load Balanced Production

docker compose -f docker-compose-load-balanced.yml up --build

Runs 2 instances of each service behind Kong for production-like setup.

Architecture

Microservices Design Principles

This project follows microservices best practices:

• Service Isolation - Each service has its own database and cache
• Independent Deployment - Services can be deployed independently
• API Gateway Pattern - Single entry point via Kong
• Event-Driven Communication - NATS for async messaging
• Database per Service - No shared databases
• Distributed Authentication - Auth service validates tokens via NATS
• Health Checks - Service health monitoring and dependency management

System Architecture

1. Without Load Balancing

2. With Load Balancing

Request Flow

Client → Kong Gateway → API Key Validation → Service → NATS → Response

1. Client Request → Kong Gateway (port 8000)
2. API Key Validation → Custom Kong plugin calls auth:8080/verify/apikey
3. Route to Service → Kong forwards to auth or blog service
4. Service Processing → Business logic execution
5. NATS Communication → Inter-service messaging (if needed)
6. Response → Kong → Client

Authentication Flow

• Users & Credentials → Stored in auth_service PostgreSQL database
• JWT Token Generation → Auth service creates access/refresh tokens
• Token Validation → Auth service middleware validates JWT
• Cross-Service Auth → Blog service requests token validation via NATS
• Distributed Security → Each service can enforce its own authentication

Authorization Flow

• Roles & Permissions → Stored in auth_service PostgreSQL database
• Role Assignment → Users can have multiple roles
• Role Validation → Auth service middleware checks permissions
• Cross-Service Authorization → Blog service requests role validation via NATS
• Fine-Grained Control → Each service decides which endpoints require which roles

Design Philosophy: This distributed authentication/authorization gives each service autonomy to define public, protected, and restricted APIs independently while maintaining centralized user management.

Service Communication

Synchronous (HTTP)

• Client ↔ Kong Gateway
• Kong ↔ Services (routing)
• Kong Plugin ↔ Auth Service (API key validation)

Asynchronous (NATS)

• Blog Service → Auth Service (token validation)
• Blog Service → Auth Service (role verification)
• Event-driven messaging between services

Network Architecture

• Custom Bridge Network (gomicro-network) for service discovery
• Container Names as DNS (postgres, mongo, redis-auth, redis-blog, nats)
• Internal Communication via container names (no external IPs)
• External Access only via Kong Gateway
• Database Access exposed for development (can be restricted in production)

Project Structure

gomicro/
├── auth_service/              # Authentication & Authorization Service
│   ├── api/
│   │   ├── auth/             # Auth endpoints (signup, signin, refresh)
│   │   │   ├── dto/          # Request/response DTOs
│   │   │   ├── message/      # NATS message definitions
│   │   │   ├── middleware/   # Auth & authorization middleware
│   │   │   └── model/        # PostgreSQL models
│   │   └── user/             # User management endpoints
│   ├── cmd/main.go           # Service entry point
│   ├── migrations/           # PostgreSQL migrations
│   ├── startup/              # Server initialization
│   └── docker-compose.yml    # Standalone development
│
├── blog_service/              # Blog Management Service
│   ├── api/
│   │   ├── author/           # Author-specific blog operations
│   │   ├── blog/             # Blog CRUD operations
│   │   ├── blogs/            # Blog listing & search
│   │   └── editor/           # Editorial operations
│   ├── cmd/main.go           # Service entry point
│   ├── startup/              # Server initialization & indexes
│   └── docker-compose.yml    # Standalone development
│
├── kong/                      # API Gateway Configuration
│   ├── kong.yml              # Kong declarative config
│   ├── kong-load-balanced.yml # Load balanced config
│   └── apikey_auth_plugin/   # Custom Go plugin for API key validation
│
├── docker-compose.yml         # Full stack orchestration
├── docker-compose.dev.yml     # Development tools
├── docker-compose-load-balanced.yml # Production setup
└── README-DOCKER.md          # Detailed Docker documentation

Service Directories

Directory	Purpose
api/	Feature-based API implementations
cmd/	Application entry point (main.go)
common/	Shared code across APIs
config/	Environment configuration
keys/	RSA keys for JWT signing
migrations/	Database migration files (auth service)
startup/	Server, DB, Redis, NATS initialization
utils/	Utility functions

Helper Directories

Directory	Purpose
.extra/	Database init scripts, documentation, assets
.tools/	RSA key generator, env file copier
.vscode/	Editor configuration, debug settings
.docs/	Architecture diagrams, banners

Code Examples

NATS Message Definition

Create message types for inter-service communication:

package message

type TokenValidation struct {
  AccessToken string `json:"accessToken,omitempty"`
}

func NewTokenValidation(token string) *TokenValidation {
  return &TokenValidation{
    AccessToken: token,
  }
}

Controller with NATS Endpoints

Controllers implement micro.Controller to handle both HTTP and NATS requests:

package auth

import (
  "github.com/gin-gonic/gin"
  "github.com/afteracademy/gomicro/auth_service/api/auth/message"