A production-ready microservices boilerplate built with Go, implementing Clean Architecture principles with comprehensive testing, security, and documentation.

graph TB subgraph "External Layer" UI[Web UI] API[REST API] DB[(PostgreSQL)] end subgraph "Infrastructure Layer" Controllers[REST Controllers] Repositories[Repositories] Security[JWT Security] Logger[Structured Logging] end subgraph "Application Layer" AuthUC[Auth Use Cases] UserUC[User Use Cases] MedicineUC[Medicine Use Cases] end subgraph "Domain Layer" Entities[Domain Entities] Rules[Business Rules] Errors[Domain Errors] end UI --> API API --> Controllers Controllers --> AuthUC Controllers --> UserUC Controllers --> MedicineUC AuthUC --> Entities UserUC --> Entities MedicineUC --> Entities Repositories --> DB AuthUC --> Repositories UserUC --> Repositories MedicineUC --> Repositories Security --> AuthUC Logger --> Controllers Logger --> Repositories 

graph LR subgraph "Dependencies Point Inward" A[Infrastructure] --> B[Application] B --> C[Domain] A --> C end subgraph "Domain is Independent" C --> D[No External Dependencies] end 

• Go 1.24.2+
• Docker & Docker Compose
• PostgreSQL (via Docker)

# Clone the repository git clone https://github.com/gbrayhan/microservices-go cd microservices-go # Copy environment file cp .env.example .env # Start services docker-compose up --build -d

# Check if services are running docker-compose ps # Test the API curl http://localhost:8080/v1/health

• Clean Architecture: Fully implemented with dependency inversion
• JWT Authentication: Secure token-based authentication
• Structured Logging: Zap logger with correlation IDs
• Comprehensive Testing: Unit, integration, and acceptance tests
• API Documentation: Complete REST API documentation
• Error Handling: Centralized error management
• Validation: Request validation with custom rules
• Search & Pagination: Advanced search capabilities

• Framework: Gin-Gonic (HTTP router)
• Database: PostgreSQL with GORM
• Authentication: JWT with refresh tokens
• Logging: Zap structured logger
• Testing: Go testing + Cucumber integration tests
• Documentation: Comprehensive API documentation
• Containerization: Docker & Docker Compose
• Code Quality: golangci-lint, CodeFactor, Codacy

microservices-go/ ├── src/ │ ├── domain/ # 🎯 Domain Layer (Entities & Business Rules) │ ├── application/ # 📋 Application Layer (Use Cases) │ └── infrastructure/ # 🔧 Infrastructure Layer │ ├── di/ # Dependency Injection │ ├── repository/ # Data Access Layer │ ├── rest/ # HTTP Controllers │ ├── security/ # JWT & Security │ └── logger/ # Structured Logging ├── Test/ │ └── integration/ # Integration Tests ├── docs/ # Documentation └── docker-compose.yml # Development Environment 

# Run the application go run main.go # Run tests go test ./... # Run tests with coverage ./coverage.sh # Run integration tests ./scripts/run-integration-test.bash # Lint code golangci-lint run ./... # Security scan trivy fs .

sequenceDiagram participant Client participant AuthController participant AuthUseCase participant UserRepository participant JWTService participant Database Client->>AuthController: POST /auth/login AuthController->>AuthUseCase: Login(email, password) AuthUseCase->>UserRepository: GetByEmail(email) UserRepository->>Database: SELECT * FROM users Database-->>UserRepository: User data UserRepository-->>AuthUseCase: User entity AuthUseCase->>AuthUseCase: Validate password AuthUseCase->>JWTService: Generate tokens JWTService-->>AuthUseCase: Access + Refresh tokens AuthUseCase-->>AuthController: User + Tokens AuthController-->>Client: 200 OK + Tokens 

stateDiagram-v2 [*] --> Authenticated Authenticated --> TokenExpired: Access token expires TokenExpired --> Refreshing: Send refresh token Refreshing --> Authenticated: New tokens received Refreshing --> Unauthorized: Invalid refresh token Unauthorized --> [*]: Re-login required Authenticated --> [*]: Logout 

• POST /v1/auth/login - User login
• POST /v1/auth/access-token - Refresh access token

• GET /v1/user - Get all users
• POST /v1/user - Create user
• GET /v1/user/:id - Get user by ID
• PUT /v1/user/:id - Update user
• DELETE /v1/user/:id - Delete user
• GET /v1/user/search - Search users with pagination
• GET /v1/user/search-property - Search by specific property

• GET /v1/medicine - Get all medicines
• POST /v1/medicine - Create medicine
• GET /v1/medicine/:id - Get medicine by ID
• PUT /v1/medicine/:id - Update medicine
• DELETE /v1/medicine/:id - Delete medicine
• GET /v1/medicine/search - Search medicines with pagination
• GET /v1/medicine/search-property - Search by specific property

graph TB subgraph "Test Pyramid" E2E[End-to-End Tests<br/>Cucumber Integration] Integration[Integration Tests<br/>API Testing] Unit[Unit Tests<br/>Use Cases & Controllers] end E2E --> Integration Integration --> Unit 

# Run all tests with coverage ./coverage.sh # Expected coverage: ≥ 80%

• JWT Authentication: Access and refresh tokens
• Password Hashing: bcrypt with salt
• CORS Configuration: Cross-origin resource sharing
• Input Validation: Request sanitization
• Error Handling: No sensitive data exposure
• Security Headers: XSS protection, content security policy

{ "level": "info", "timestamp": "2024-01-01T00:00:00Z", "message": "User login successful", "user_id": 123, "email": "user@example.com", "correlation_id": "req-123-456", "service": "auth-service" }

# Health endpoint GET /v1/health # Response { "status": "healthy", "timestamp": "2024-01-01T00:00:00Z", "version": "1.0.0" }

# Build production image docker build -t microservices-go . # Run with environment variables docker run -p 8080:8080 \ -e DB_HOST=postgres \ -e DB_PORT=5432 \ -e JWT_ACCESS_SECRET_KEY=your_secret \ microservices-go

# Server Configuration SERVER_PORT=8080 GO_ENV=production # Database Configuration DB_HOST=localhost DB_PORT=5432 DB_USER=postgres DB_PASSWORD=password DB_NAME=microservices_go # JWT Configuration JWT_ACCESS_SECRET_KEY=your_access_secret JWT_REFRESH_SECRET_KEY=your_refresh_secret JWT_ACCESS_TIME_MINUTE=60 JWT_REFRESH_TIME_HOUR=24

• Clean Architecture Guide - Detailed architecture documentation
• API Search Endpoints - Search and pagination features
• Complete API Documentation - Full API reference

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow Clean Architecture principles
• Write tests for new features
• Maintain ≥ 80% test coverage
• Use conventional commit messages
• Update documentation for API changes

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

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

• ✅ Implemented Clean Architecture
• ✅ Added comprehensive search and pagination
• ✅ Enhanced error handling and logging
• ✅ Improved test coverage and quality
• ✅ Added integration tests with Cucumber
• ✅ Updated all documentation to English
• ✅ Added architecture diagrams and flow charts

• ✅ Initial microservices structure
• ✅ Basic CRUD operations
• ✅ JWT authentication
• ✅ PostgreSQL integration