Go Backend Template

A clean, production-ready Go backend template with authentication, user management, and best practices built-in.

Features

• Clean Architecture - Separation of concerns with handler → service → processor → repository layers
• Authentication & Authorization - JWT-based auth with role-based access control
• Database Ready - PostgreSQL integration with GORM
• Middleware Stack - CORS, logging, recovery, correlation ID tracking
• Configuration Management - Environment-based config with Viper
• Structured Logging - Zap and Logrus integration
• Input Validation - Request validation with go-playground/validator
• Graceful Shutdown - Proper cleanup on termination signals

Project Structure

.
├── cmd/
│   └── server/              # Application entry point
├── config/                  # Configuration management
│   ├── configs.go          # Main config loader
│   ├── db.go               # Database config
│   ├── jwt.go              # JWT config
│   ├── log.go              # Logging config
│   ├── s3.go               # S3/file storage config
│   └── server.go           # Server config
├── internal/
│   ├── app/                # Application initialization
│   ├── appcontext/         # Request context utilities
│   ├── constant/           # Application constants
│   ├── constants/          # Business constants
│   ├── contract/           # API request/response DTOs
│   ├── db/                 # Database connection
│   ├── entities/           # Database models (GORM)
│   ├── handler/            # HTTP handlers
│   ├── logger/             # Logging utilities
│   ├── middleware/         # HTTP middleware
│   ├── processor/          # Business logic processors
│   ├── repository/         # Data access layer
│   ├── router/             # Route definitions
│   ├── service/            # Service layer
│   ├── transformer/        # DTO transformers
│   ├── util/               # Utility functions
│   └── validator/          # Custom validators
├── migrations/             # Database migrations
├── infra/                  # Infrastructure configs (YAML)
├── go.mod
├── go.sum
├── Makefile
└── README.md

Architecture Layers

1. Handler Layer (internal/handler/)

• HTTP request/response handling
• Request validation
• Route definitions
• Transforms contracts to/from services

2. Service Layer (internal/service/)

• Business logic orchestration
• Coordinates between processors
• Transaction management

3. Processor Layer (internal/processor/)

• Complex business operations
• Cross-repository transactions
• Business rule enforcement

4. Repository Layer (internal/repository/)

• Data access layer
• Database operations
• GORM integration

5. Supporting Packages

• Contract - API DTOs with JSON tags
• Entities - Database models with GORM tags
• Transformer - Contract ↔ Entity conversions
• Middleware - Request processing pipeline
• Validator - Custom validation logic

Getting Started

Prerequisites

• Go 1.21 or higher
• PostgreSQL 12+
• Make (optional, for using Makefile commands)

Installation

1. Clone this template

   git clone <your-repo-url>
   cd go-backend-template
   

2. Rename the project

   Update the module name in go.mod:

   module your-project-name
   

   Then update all imports:

   find . -name "*.go" -type f -exec sed -i '' 's|go-backend-template|your-project-name|g' {} \;
   

3. Install dependencies

   go mod download
   

4. Set up configuration

   Create your environment config file in infra/:

   cp infra/development.yaml infra/development.yaml
   

   Edit infra/development.yaml with your settings:

   server:
     port: "8080"
   
   postgresql:
     host: "localhost"
     port: "5432"
     user: "postgres"
     password: "your-password"
     database: "your-database"
     sslmode: "disable"
   
   jwt:
     token:
       secret: "your-secret-key"
       expires_ttl: 3600
   
   log:
     log_level: "info"
     log_format: "json"
   

5. Run database migrations

   make migration-up
   

6. Start the server

   # Set environment mode
   export ENV_MODE=development
   
   # Run the server
   go run cmd/server/main.go
   

Configuration

The application uses environment-based YAML configuration files located in the infra/ directory:

• infra/local.yaml - Local development
• infra/development.yaml - Development environment
• infra/production.yaml - Production environment

Set the ENV_MODE environment variable to select the configuration:

export ENV_MODE=development  # or local, production

API Endpoints

Health Check

• GET /health - Health check endpoint

Authentication

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/refresh - Refresh access token
• GET /api/v1/auth/profile - Get authenticated user profile

Users (Protected)

• POST /api/v1/users - Create user
• GET /api/v1/users - List users
• PUT /api/v1/users/:id - Update user
• DELETE /api/v1/users/:id - Delete user
• GET /api/v1/users/profile - Get current user profile
• PUT /api/v1/users/profile - Update current user profile
• PUT /api/v1/users/:id/password - Change user password

Development

Running with Air (Hot Reload)

Install Air:

go install github.com/cosmtrek/air@latest

Run with hot reload:

air

Database Migrations

Create a new migration:

make migration-create name=create_your_table

Run migrations:

make migration-up

Rollback last migration:

make migration-down

Code Formatting

make fmt

Running Tests

make test

Building for Production

Build the binary:

make build-http

The binary will be created in ./bin/http-server.

Run the production binary:

./bin/http-server

Docker Support

Build Docker image:

docker build -t your-app-name .

Run with Docker Compose:

docker-compose up

Customization Guide

Adding a New Feature

1. Define the entity in internal/entities/
2. Create migration for the database table
3. Add repository in internal/repository/
4. Create processor in internal/processor/ for business logic
5. Add service in internal/service/ for orchestration
6. Define contracts in internal/contract/ for API DTOs
7. Create handler in internal/handler/ for HTTP endpoints
8. Register routes in internal/router/router.go
9. Wire dependencies in internal/app/app.go

Example: Adding a "Product" Feature

// 1. Entity (internal/entities/product.go)
type Product struct {
    ID        string    `gorm:"primaryKey"`
    Name      string    `gorm:"not null"`
    Price     float64   `gorm:"not null"`
    CreatedAt time.Time
}

// 2. Repository (internal/repository/product_repository.go)
type ProductRepository interface {
    Create(ctx context.Context, product *entities.Product) error
    FindByID(ctx context.Context, id string) (*entities.Product, error)
}

// 3. Service (internal/service/product_service.go)
type ProductService interface {
    CreateProduct(ctx context.Context, req *contract.CreateProductRequest) error
}

// 4. Handler (internal/handler/product_handler.go)
func (h *ProductHandler) CreateProduct(c *gin.Context) {
    // Handle HTTP request
}

// 5. Register in router (internal/router/router.go)
products := v1.Group("/products")
products.Use(r.authMiddleware.RequireAuth())
{
    products.POST("", r.productHandler.CreateProduct)
    products.GET("/:id", r.productHandler.GetProduct)
}

Environment Variables

• ENV_MODE - Environment mode (local, development, production)

Dependencies

Key dependencies:

• Gin - HTTP web framework
• GORM - ORM library
• Viper - Configuration management
• Zap/Logrus - Structured logging
• JWT - JSON Web Token authentication
• Validator - Struct validation
• AWS SDK - S3 file storage (optional)

License

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

Contributing

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

Support

For issues and questions, please open an issue on GitHub.