<div align="center">

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.

---

</div>

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