Production-ready microservices template demonstrating modern Go backend practices with gRPC, REST, event-driven messaging, and full observability.

• Clean Architecture - Hexagonal architecture with clear separation of concerns
• gRPC + REST - Dual API support via gRPC-gateway
• Event-Driven - Asynchronous messaging with RabbitMQ
• Type-Safe SQL - Code generation with sqlc
• Monitoring - Prometheus metrics + Grafana dashboards
• Docker - Multi-stage builds for minimal images (~20MB)
• Kubernetes - Production-ready manifests with HPA
• CI/CD - Automated testing and deployment

• Architecture
• Tech Stack
• Getting Started
• Project Structure
• API Documentation
• Testing
• Deployment
• Monitoring
• Contributing

This project follows Clean Architecture (Hexagonal) principles:

┌─────────────────────────────────────────┐
│          API Layer (Adapters)           │
│     gRPC Server │ REST Gateway          │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         Application Layer               │
│         (Use Cases / Business Logic)    │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│          Domain Layer                   │
│    (Entities, Value Objects, Rules)     │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│      Infrastructure Layer (Adapters)    │
│  PostgreSQL │ RabbitMQ │ External APIs  │
└─────────────────────────────────────────┘

• Repository Pattern - Abstract data access
• Dependency Injection - Google Wire for compile-time DI
• CQRS Lite - Separate read/write use cases
• Event Sourcing - Domain events for async communication

• Go 1.21+
• Docker & Docker Compose
• PostgreSQL 15+
• RabbitMQ 3.12+
• Make

1. Clone the repository

git clone https://github.com/memclutter/go-microservices-template.git
cd go-microservices-template

2. Install development tools

make install-tools

3. Start infrastructure

make docker-up

4. Run database migrations

make migrate-up

5. Generate code (protobuf + sqlc + wire)

make generate

6. Run the application

make run

The API will be available at:

• REST: http://localhost:8080
• gRPC: localhost:50051
• Metrics: http://localhost:8080/metrics

# Create a user via REST
curl -X POST http://localhost:8080/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"Test User","password":"password123"}'

# Get user
curl http://localhost:8080/v1/users/{user_id}

.
├── api/
│   └── proto/              # Protocol buffer definitions
├── cmd/
│   └── api/               # Application entrypoint
├── internal/
│   ├── domain/            # Business entities & logic
│   ├── usecase/           # Application business flows
│   └── infrastructure/    # External implementations
│       ├── grpc/          # gRPC server
│       ├── http/          # REST gateway
│       ├── repository/    # Database access
│       └── messaging/     # Event pub/sub
├── pkg/                   # Public reusable packages
│   ├── config/           # Configuration
│   ├── logger/           # Logging
│   └── metrics/          # Prometheus metrics
├── db/
│   ├── migrations/       # Database migrations
│   └── queries/          # SQL queries for sqlc
├── deployments/
│   ├── docker/           # Dockerfiles & compose
│   └── k8s/              # Kubernetes manifests
├── scripts/              # Build & utility scripts
└── docs/                 # Additional documentation

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse)
  rpc GetUser(GetUserRequest) returns (GetUserResponse)
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse)
  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse)
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse)
}

See API Documentation for detailed request/response schemas.

# Run all tests
make test

# Run with coverage
make test-coverage

# Run integration tests
make test-integration

# Run benchmarks
make benchmark

• Unit tests for all layers
• Integration tests with testcontainers
• Mocks generated with gomock
• Table-driven tests

# Build image
make docker-build

# Run with docker-compose
make docker-up

# View logs
make docker-logs

# Deploy to cluster
make k8s-apply

# Check status
make k8s-status

# Scale deployment
kubectl scale deployment api -n microservices --replicas=5

• Use external secret management (Vault, AWS Secrets Manager)
• Configure TLS for gRPC and HTTPS
• Set up log aggregation (ELK, Loki)
• Configure distributed tracing (Jaeger, Zipkin)
• Enable rate limiting
• Set up backups for PostgreSQL
• Configure alerts in Prometheus

Access metrics at http://localhost:8080/metrics

Key metrics:

• http_requests_total - Total HTTP requests
• http_request_duration_seconds - Request latency
• database_queries_total - Database operations
• events_published_total - Published events

Access Grafana at http://localhost:3000 (admin/admin)

Pre-configured dashboards:

• Service Overview
• HTTP Performance
• Database Performance
• RabbitMQ Metrics

See CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see LICENSE file.

• Clean Architecture by Robert Martin
• Domain-Driven Design by Eric Evans
• Go community and maintainers

Happy coding! 🚀