KC - OMS - GO - Microservices

A scalable microservices architecture built with Go, featuring hot-reload development and orchestrated service management.

🏗️ Architecture

This project consists of four core microservices:

• Gateway Service - API gateway and request routing
• Order Service - Order management and processing
• Product Service - Product catalog and inventory
• Notification Service - Event-driven notifications

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Docker & Docker Compose
• Make
• Homebrew (for macOS)

First Time Setup

1. Clone the repository

   git clone <repository-url>
   cd kc-go-microservices

2. Install dependencies

   make install-deps

3. Configure your shell (one-time only)

   make setup-path
   source ~/.zshrc  # or source ~/.bashrc for bash

4. Run setup

   make setup

5. Start services

   make start

   Or run everything in one command:

   make dev

📋 Available Commands

Command	Description
make help	Show all available commands
make setup	Complete project setup (configs, Docker, deps check)
make dev	Full setup + start services (one command)
make start	Start all services with live logs
make stop	Stop all running services
make install-deps	Install air and overmind
make setup-air	Create Air config files for hot-reload
make setup-procfile	Generate Procfile for Overmind
make docker-up	Start Docker containers
make docker-down	Stop Docker containers
make clean	Clean temporary files and stop everything

🛠️ Development Workflow

Daily Development

# Start your day
make start

# Code your changes...
# Air automatically reloads services on file changes

# Stop services (Ctrl+C or in another terminal)
make stop

Working with Individual Services

Services are located in the services/ directory:

services/
├── gateway-service/
├── order-service/
├── product-service/
└── notification-service/

Each service has:

• main.go - Service entry point
• .air.toml - Hot-reload configuration
• tmp/ - Build artifacts (gitignored)

🔧 Technology Stack

• Language: Go
• Service Orchestration: Overmind
• Hot Reload: Air
• Containerization: Docker & Docker Compose
• Build Tool: Make

📦 Project Structure

.
├── services/
│   ├── gateway-service/
│   │   ├── main.go
│   │   ├── .air.toml
│   │   └── tmp/
│   ├── order-service/
│   ├── product-service/
│   └── notification-service/
├── docker-compose.yml
├── Procfile
├── Makefile
└── README.md

🐳 Docker Services

The docker-compose.yml includes supporting services like:

• Database (PostgreSQL/MySQL)
• Message Queue (RabbitMQ/Kafka)
• Cache (Redis)
• etc.

Start Docker services separately:

make docker-up

Stop Docker services:

make docker-down

🔥 Hot Reload

Air watches for file changes and automatically rebuilds and restarts services. Configuration is in each service's .air.toml file.

What triggers a reload:

• Changes to .go files
• New Go files added

What doesn't trigger a reload:

• Changes in tmp/ directory
• Changes in vendor/ directory

🧹 Cleanup

Remove all temporary files and stop services:

make clean

This will:

• Remove all tmp/ directories
• Delete the Procfile
• Stop Docker containers

🐛 Troubleshooting

Services won't start

1. Check if all dependencies are installed:

   make check-deps

2. Ensure Docker is running:

   docker ps

3. Check if ports are already in use

Air not found

Make sure Go bin is in your PATH:

echo $PATH | grep go/bin

If not, run:

make setup-path
source ~/.zshrc

Permission denied errors

Ensure Docker doesn't require sudo:

sudo usermod -aG docker $USER
newgrp docker

📝 Service Configuration

Each service can be configured via:

• Environment variables in docker-compose.yml
• Config files in each service directory
• Command-line flags in Procfile

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Test locally with make start
4. Submit a pull request

📄 License

[Your License Here]

👥 Team

[Your Team Information]

---

Need help? Run make help to see all available commands.