Idiomatic Go + Domain-Driven Design - A production-ready Go template combining idiomatic Go practices with DDD architecture patterns.

• Overview
• Features
• Architecture
• Project Structure
• Getting Started
• Configuration
• Development
• API Documentation
• Testing
• Deployment
• Contributing
• License

idiogo is a modern, production-ready Go boilerplate that combines idiomatic Go practices with Domain-Driven Design (DDD) principles. It provides a solid foundation for building scalable, maintainable REST APIs with clean architecture.

This template is designed to help you kickstart Go projects with best practices baked in, including:

• Clean DDD architecture
• Type-safe request/response handling
• Built-in validation and i18n support
• Database migrations with GORM
• Docker-ready deployment
• Middleware patterns

• golang code review comments
• effective go docs
• golang styleguide by Google

• 🏗️ Domain-Driven Design: Clean separation of concerns with domain, application, and infrastructure layers
• 🚀 Fiber Framework: High-performance HTTP framework built on Fasthttp
• 🗃️ GORM ORM: Powerful ORM with PostgreSQL support and auto-migrations
• ✅ Validation: Comprehensive request validation with go-playground/validator
• 🌍 Internationalization: Multi-language support with go-i18n
• 🔄 Type-Safe Handlers: Generic handler patterns for type-safe request/response handling
• 📦 Dependency Injection: Clean dependency management pattern
• 🐳 Docker Support: Production-ready Docker and Docker Compose configurations

• 🔧 Hot Reload Ready: Easy integration with development tools
• 📝 Structured Logging: Clean, readable log output
• 🎯 Graceful Shutdown: Proper resource cleanup on termination
• 🔐 Security: Built-in security headers and proxy detection
• 📊 Database Migrations: Automatic schema management with GORM

idiogo follows a Layered DDD Architecture with clear separation of concerns:

┌─────────────────────────────────────────────┐
│            cmd/ (Entry Points)              │
│  • serve: REST API server                   │
│  • cron: Background jobs                    │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        internal/app (Application)           │
│  • Application initialization               │
│  • Module composition                       │
│  • Dependency wiring                        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│       internal/domain (Business Logic)      │
│  • Entities & Aggregates                    │
│  • Services (Business Logic)                │
│  • Repository Interfaces                    │
│  • Handlers (HTTP)                          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        internal/infra (Infrastructure)      │
│  • Database connections                     │
│  • External service integrations            │
│  • Repository implementations               │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│          pkg/ (Shared Packages)             │
│  • Reusable utilities                       │
│  • Common types & helpers                   │
└─────────────────────────────────────────────┘

1. Domain Layer (internal/domain/): Contains business logic, entities, and domain services
2. Application Layer (internal/app/): Orchestrates domain logic and handles use cases
3. Infrastructure Layer (internal/infra/): Technical implementations (DB, external APIs)
4. Interface Layer (internal/rest/, internal/port/): HTTP handlers and protocol adapters
5. Shared Kernel (pkg/): Reusable utilities and common abstractions

idiogo/
├── cmd/                          # Application entry points
│   ├── serve/                    # REST API server
│   │   ├── main.go
│   │   └── Dockerfile
│   └── cron/                     # Background jobs
│       └── main.go
├── internal/                     # Private application code
│   ├── app/                      # Application layer
│   │   ├── serve/               # Server initialization
│   │   └── cron/                # Cron initialization
│   ├── domain/                   # Business logic layer
│   │   └── todo/                # Example domain (Todo)
│   │       ├── todo.go          # Entity
│   │       ├── service.go       # Business logic
│   │       ├── repo.go          # Repository implementation
│   │       ├── handler.go       # HTTP handlers
│   │       └── filters.go       # Query filters
│   ├── infra/                    # Infrastructure layer
│   │   └── db/                  # Database
│   │       ├── pg.go            # PostgreSQL connection
│   │       └── migration/       # DB migrations
│   ├── rest/                     # REST API implementation
│   │   ├── rest.go              # Server setup
│   │   ├── service.go           # REST service utilities
│   │   ├── handler.go           # Generic handlers
│   │   └── middleware/          # HTTP middlewares
│   ├── port/                     # Ports (interfaces)
│   │   └── rest.go              # REST port interface
│   └── config/                   # Configuration
│       ├── config.go            # Config structures
│       └── bind.go              # Config loader
├── pkg/                          # Public shared packages
│   ├── entity/                  # Base entities
│   ├── i18np/                   # Internationalization
│   ├── validation/              # Validation utilities
│   ├── query/                   # Query builders
│   ├── state/                   # State management
│   ├── list/                    # List/pagination
│   └── server/                  # Server utilities
├── assets/                       # Static assets
│   └── locales/                 # Translation files
│       ├── en.toml
│       └── tr.toml
├── deployments/                  # Deployment configurations
│   ├── compose.yml              # Docker Compose
│   └── config.yml               # Application config
├── docs/                         # Documentation
├── tmp/                          # Temporary files (gitignored)
├── go.mod                        # Go modules
└── README.md

• Go: 1.25.5 or higher
• Docker: Latest version (for containerized deployment)
• PostgreSQL: 15+ (or use Docker Compose)

1. Clone the repository (or use as a GitHub template):

git clone https://github.com/salihguru/idiogo.git my-project
cd my-project

2. Install dependencies:

go mod download

3. Update module name:

Replace github.com/salihguru/idiogo with your module path in:

• go.mod
• All import statements

# Use a script or IDE refactoring tools
find . -type f -name "*.go" -exec sed -i '' 's/github.com\/salihguru\/idiogo/your-module-path/g' {} +

4. Configure the application:

Copy the example configuration:

cp deployments/config.yml config.yaml

Edit config.yaml with your settings.

5. Start the database:

docker compose -f deployments/compose.yml up -d idiogo-pg

6. Run migrations (automatic on startup with migrate: true in config)

7. Start the server:

go run cmd/serve/main.go

The API will be available at http://localhost:4041

Configuration is managed through YAML files. See deployments/config.yml for an example.

rest:
  host: 0.0.0.0           # Server host
  port: 4041               # Server port

db:
  host: localhost          # Database host
  port: "5432"             # Database port
  user: idiogo             # Database user
  pass: idiogo             # Database password
  name: idiogo             # Database name
  ssl_mode: disable        # SSL mode (disable, require, verify-ca, verify-full)
  migrate: true            # Auto-run migrations on startup
  debug: false             # Enable SQL query logging

i18n:
  locales:                 # Supported locales
    - en
    - tr
  default: en              # Default locale
  dir: "./assets/locales"  # Locale files directory

You can override configuration values with environment variables (when implemented):

export DB_HOST=localhost
export DB_PORT=5432
export REST_PORT=8080

1. Create domain directory:

mkdir -p internal/domain/yourdomein

2. Define the entity (internal/domain/yourdomain/entity.go):

package yourdomain

import "github.com/salihguru/idiogo/pkg/entity"

type YourEntity struct {
    entity.Base
    Name        string `json:"name"`
    Description string `json:"description"`
}

3. Create the repository (internal/domain/yourdomain/repo.go):

package yourdomain

import (
    "context"
    "github.com/google/uuid"
    "gorm.io/gorm"
)

type Repo struct {
    db *gorm.DB
}

func NewRepo(db *gorm.DB) *Repo {
    return &Repo{db: db}
}

func (r *Repo) Save(ctx context.Context, entity *YourEntity) error {
    return r.db.WithContext(ctx).Save(entity).Error
}

func (r *Repo) View(ctx context.Context, id uuid.UUID) (*YourEntity, error) {
    var entity YourEntity
    err := r.db.WithContext(ctx).First(&entity, "id = ?", id).Error
    return &entity, err
}

4. Implement the service (internal/domain/yourdomain/service.go):

package yourdomain

import "context"

type Service struct {
    repo *Repo
}

func NewService(repo *Repo) *Service {
    return &Service{repo: repo}
}

func (s *Service) Create(ctx context.Context, req CreateReq) (*YourEntity, error) {
    entity := &YourEntity{
        Name:        req.Name,
        Description: req.Description,
    }
    if err := s.repo.Save(ctx, entity); err != nil {
        return nil, err
    }
    return entity, nil
}

5. Create HTTP handlers (internal/domain/yourdomain/handler.go):

package yourdomain

import (
    "github.com/gofiber/fiber/v2"
    "github.com/salihguru/idiogo/internal/port"
    "github.com/salihguru/idiogo/internal/rest"
)

type Handler struct {
    srv Service
}

func NewHandler(srv Service) *Handler {
    return &Handler{srv: srv}
}

func (h *Handler) RegisterRoutes(srv port.RestService, router fiber.Router) {
    group := router.Group("/yourdomains")
    
    group.Post("/",
        srv.Timeout(rest.Handle(rest.WithBody(rest.WithValidation(srv.ValidateStruct(),
            rest.CreateResponds(h.srv.Create))))))
}

6. Register the module in internal/app/serve/modules.go:

yourDomainRepo := yourdomain.NewRepo(d.DB)
yourDomainService := yourdomain.NewService(yourDomainRepo)
yourdomainModule := rest.Module[*yourdomain.Repo, *yourdomain.Service]{
    Repo:    yourDomainRepo,
    Service: yourDomainService,
    Router:  yourdomain.NewHandler(*yourdomainModule.Service),
}

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./internal/domain/todo/...

# Format code
go fmt ./...

# Lint code
golangci-lint run

# Security scan
gosec ./...

POST /todos
Content-Type: application/json

{
  "title": "Buy groceries",
  "description": "Milk, eggs, bread"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Buy groceries",
  "description": "Milk, eggs, bread",
  "status": "pending",
  "created_at": "2025-12-18T10:00:00Z"
}

GET /todos?page=1&limit=10&status=pending

GET /todos/{id}

PATCH /todos/{id}
Content-Type: application/json

{
  "title": "Buy groceries and fruits",
  "status": "completed"
}

DELETE /todos/{id}

All API responses follow a consistent format:

Success Response:

{
  "data": { /* response data */ }
}

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "title",
        "message": "title is required"
      }
    ]
  }
}

The project includes examples for:

• Unit tests
• Integration tests
• Repository tests

Example test structure:

func TestService_Create(t *testing.T) {
    // Setup
    db := setupTestDB(t)
    repo := NewRepo(db)
    service := NewService(repo)
    
    // Test
    result, err := service.Create(context.Background(), CreateReq{
        Title: "Test Todo",
    })
    
    // Assert
    assert.NoError(t, err)
    assert.NotNil(t, result)
    assert.Equal(t, "Test Todo", result.Title)
}

# Start all services
docker compose -f deployments/compose.yml up -d

# View logs
docker compose -f deployments/compose.yml logs -f

# Stop services
docker compose -f deployments/compose.yml down

# Build image
docker build -f cmd/serve/Dockerfile -t idiogo:latest .

# Run container
docker run -p 4041:4041 \
  -e DB_HOST=postgres \
  -e DB_PORT=5432 \
  idiogo:latest

For production deployment:

1. Set environment-specific configuration
2. Use secrets management for sensitive data
3. Enable SSL/TLS for database connections
4. Configure reverse proxy (nginx, traefik)
5. Set up monitoring and logging
6. Enable health checks

Example production config:

rest:
  host: 0.0.0.0
  port: 4041

db:
  host: ${DB_HOST}
  port: ${DB_PORT}
  user: ${DB_USER}
  pass: ${DB_PASSWORD}
  name: ${DB_NAME}
  ssl_mode: require
  migrate: false
  debug: false

i18n:
  locales: [en, tr]
  default: en
  dir: "/app/assets/locales"

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

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

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

• Fiber - Web framework
• GORM - ORM library
• go-playground/validator - Validation
• go-i18n - Internationalization
• rescode - Response code management

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Built with ❤️ using idiomatic Go and DDD principles