Go Microservices

Go-based microservices backend with a REST API gateway, gRPC service-to-service communication, JWT auth, and local observability tooling.

Overview

This repo contains:

• api-gateway: public HTTP API (/api/v1/*)
• services/auth-service: authentication and user auth workflows
• services/user-service: user domain service
• services/post-service: post domain service
• proto: shared protobuf contracts used by gateway and services

Core infra for local development includes PostgreSQL, Redis, Docker Compose, Prometheus, Grafana, and Jaeger.

Project Layout

go-microservices/
├── api-gateway/
├── services/
│   ├── auth-service/
│   ├── user-service/
│   └── post-service/
├── proto/
├── scripts/
├── docker-compose.yml
├── Makefile
└── README.md

Quick Start

Prerequisites:

• Go 1.21+
• Docker + Docker Compose
• protoc
• make

Local startup:

make dev-setup
make db-up
make proto

# run each in separate terminals
make run-auth
make run-user
make run-post
make run-gateway

Docker-first startup:

make docker-build
make docker-up
make docker-logs

API Summary

Base URL: http://localhost:8080/api/v1

Endpoints:

• GET / health check
• POST /signup register
• POST /signin login (returns access_token, refresh_token)
• POST /validate validate token
• POST /userinfo protected endpoint (Authorization: Bearer <token>)
• POST /test create test entry
• GET /tests list test entries

Typical auth flow:

1. POST /signup
2. POST /signin
3. Use access_token as Bearer token on protected routes
4. (Optional) POST /validate

Service Ports

• API Gateway: 8080
• Auth gRPC: 50051
• User gRPC: 50052
• Post gRPC: 50053
• PostgreSQL: 5432
• Redis: 6379
• Grafana: 3000
• Prometheus: 9090
• Jaeger: 16686

Testing Options

1) Postman

• Import postman_collection.json
• Import postman_environment.json
• Set base_url=http://localhost:8080
• Run requests in this order: health -> signup -> signin -> validate -> userinfo -> test -> tests

2) Posting (terminal TUI)

./scripts/posting-start.sh

Environment file used by Posting:

• ~/.config/posting/collections/go_microservices/Go Microservices API.env

3) curl

# Health
curl -X GET http://localhost:8080/api/v1/

# Sign in
curl -X POST http://localhost:8080/api/v1/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","password":"SecurePassword123!"}'

Common Make Targets

• make build build all services
• make test run tests
• make lint run linting
• make format format code
• make proto regenerate protobuf output
• make db-up / make db-down start/stop DB infra
• make docker-up / make docker-down start/stop container stack

Protobuf Regeneration

When proto contracts change, regenerate bindings:

make proto

Direct command example:

protoc --go_out=. --go-grpc_out=. proto/auth.proto

Generated files are expected in service proto directories such as:

• services/auth-service/proto/
• services/user-service/proto/
• services/post-service/proto/

Troubleshooting

• Port conflicts: stop local stack (make docker-down) and restart required services
• DB errors: run make db-down && make db-up
• Token errors (401): sign in again and ensure Bearer prefix is present
• 404/connection errors: verify base_url and gateway process on :8080

Notes

• API returns JSON for most responses; errors typically use { "error": "..." }
• JWT can be passed via Authorization header (or cookie where supported)
• Keep docs and contract examples in sync when changing endpoint behavior