How to Clean Architecture in Go?

How to prepare your Go application to scale fast and reliable

Some months ago I wrote an article about clean architecture principles with a focus on a Java application. If you are not familiar with Onion architecture and separation of business-logic concerns, I recommend you give a read to be more familiar with some concepts we will talk about here.

Rethinking microservices: Process, rules, and scalability

A different approach with Golang

I was a full-time Java programmer for the first 6 years of my career when I was focussed on product engineering. Some months ago, I’ve joined the SRE team of QuintoAndar, and I had to become familiar with the new set of tools and languages used by my new team.


What is GEEK

Buddha Community

How to Clean Architecture in Go?
Fannie  Zemlak

Fannie Zemlak


What's new in the go 1.15

Go announced Go 1.15 version on 11 Aug 2020. Highlighted updates and features include Substantial improvements to the Go linker, Improved allocation for small objects at high core counts, X.509 CommonName deprecation, GOPROXY supports skipping proxies that return errors, New embedded tzdata package, Several Core Library improvements and more.

As Go promise for maintaining backward compatibility. After upgrading to the latest Go 1.15 version, almost all existing Golang applications or programs continue to compile and run as older Golang version.

#go #golang #go 1.15 #go features #go improvement #go package #go new features

Jackson George


ECS: Residential & Commercial Cleaning Services in London

Specializing in commercial cleaning, office cleaning, hospital & GP surgery cleaning, residential cleaning, washroom cleaning, school cleaning, Covid cleaning and sanitization, ECS Commercial Cleaning Company London has built up a large, experienced team of highly-skilled team of professionals who ensures work is delivered to highest standards, on time and on budget.

At ECS Commercial Cleaning, we provide a safe, cost-effective and efficient service that covers all your commercial cleaning needs. From residential cleaning, washroom cleaning, school cleaning to office cleaning, hospital & GP surgery cleaning, we cater it all. We have years of experience with all kinds of projects and know the best approach to save you time and money. Our professional knowledge and skills has enabled us to provide high quality cleaning solutions throughout London.

We’ve been delivering commercial cleaning services throughout London with the help of trained and experienced professionals, using only the finest equipment and cleaning solutions. Our team starts cleaning project from initial consultation through to completion on budget and schedule.

ECS Commercial Cleaning strives to keep people first, investing in their professional training and safety. We work hard to create and sustain an environment that helps us to achieve clients’ expectations through consistently excellent service and minimal downtime.

Our Services

With 10 years of market experience, a resource of professional employees and coverage throughout the London, ECS Commercial Cleaning has established itself as one of the leading commercial cleaning company, offering valuable cleaning solutions including:

  • commercial cleaning
  • office cleaning
  • hospital & GP surgery cleaning
  • residential cleaning
  • washroom cleaning
  • school cleaning
  • covid cleaning and sanitization

Our clients are the London’s leading retail outlets, office buildings and office premises, schools, hospitals, production and industrial premises and others. Our cleaning solutions offers peace of mind to clients and most importantly ensure that workers are able to do their jobs comfortably and efficiently without compromising safety. Over the years of industry experience, we remain at the forefront of our industry due to our unparalleled customer dedication and unrivalled experience in providing safe, and cost-effective cleaning solutions.

Our Expert Team

ECS Commercial Cleaning provides you with an expert team that completes your cleaning project professionally and efficiently. No matter what cleaning service you require, our aim is to work closely with our clients in order to comprehend their needs and fulfil their specific requirements through tailored cleaning solutions.

With our eco-friendly cleaning products and a team of experienced professionals, we can provide timely cleaning solutions to our clients. Contact ECS Commercial Cleaning on 0161 5462235.

#cleaning #commercial cleaning #office cleaning #residential cleaning #washroom cleaning #covid cleaning and sanitization

Elian  Harber

Elian Harber


Go Clean Architecture based on Reading Uncle Bob's Clean Architecture



This is an example of implementation of Clean Architecture in Go (Golang) projects.

Rule of Clean Architecture by Uncle Bob

  • Independent of Frameworks. The architecture does not depend on the existence of some library of feature laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.
  • Testable. The business rules can be tested without the UI, Database, Web Server, or any other external element.
  • Independent of UI. The UI can change easily, without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
  • Independent of Database. You can swap out Oracle or SQL Server, for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
  • Independent of any external agency. In fact your business rules simply don’t know anything at all about the outside world.

More at

This project has 4 Domain layer :

  • Models Layer
  • Repository Layer
  • Usecase Layer
  • Delivery Layer

The diagram:

golang clean architecture

The original explanation about this project's structure can read from this medium's post :

It may different already, but the concept still the same in application level, also you can see the change log from v1 to current version in Master.

How To Run This Project

Make Sure you have run the article.sql in your mysql

Since the project already use Go Module, I recommend to put the source code in any folder but GOPATH.

Run the Testing

$ make test

Run the Applications

Here is the steps to run it with docker-compose

#move to directory
$ cd workspace

# Clone into YOUR $GOPATH/src
$ git clone

#move to project
$ cd go-clean-arch

# Build the docker image first
$ make docker

# Run the application
$ make run

# check if the containers are running
$ docker ps

# Execute the call
$ curl localhost:9090/articles

# Stop
$ make stop

Tools Used:

In this project, I use some tools listed below. But you can use any simmilar library that have the same purposes. But, well, different library will have different implementation type. Just be creative and use anything that you really need.


v1: checkout to the v1 branch 
Proposed on 2017, archived to v1 branch on 2018 
Desc: Initial proposal by me. The story can be read here:

v2: checkout to the v2 branch 
Proposed on 2018, archived to v2 branch on 2020 
Desc: Improvement from v1. The story can be read here:

v3: master branch 
Proposed on 2019, merged to master on 2020. 
Desc: Introducing Domain package, the details can be seen on this PR #21

Download Details:

Author: Bxcodec
Source Code: 
License: MIT license

#go #golang #clean #mysql 

Go-cleanarch: Clean Architecture Validator for Go

Clean Architecture checker for Golang

go-cleanarch was created to keep Clean Architecture rules, like a The Dependency Rule and interaction between modules in your Go projects. For more information you should read our article about Clean Architecture.

Some benefits of using Clean Architecture:

  1. Independent of Frameworks. The architecture does not depend on the existence of some library of feature laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.
  2. Testable. The business rules can be tested without the UI, Database, Web Server, or any other external element.
  3. Independent of UI. The UI can change easily, without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
  4. Independent of Database. You can swap out Oracle or SQL Server, for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
  5. Independent of any external agency. In fact your business rules simply don’t know anything at all about the outside world.

Source: The Clean Architecture

Clean Architecture

Project schema requirements

go-cleanarch assumes this files structure:




For example

  • go/src/
    • auth
      • domain
      • application
      • interfaces
    • content
      • domain
        • submodule1
        • submodule2
        • etc.
      • application
      • interfaces
    • frontend
      • domain
      • application
      • interfaces


The default layer names are as followed. It is possible to set different names by command line parameters see -domain/-application/-interfaces/-infrastructure bellow.

var LayersAliases = map[string]Layer{
    // Domain
    "domain":   LayerDomain,
    "entities": LayerDomain,

    // Application
    "app":         LayerApplication,
    "application": LayerApplication,
    "usecases":    LayerApplication,
    "usecase":     LayerApplication,
    "use_cases":   LayerApplication,

    // Interfaces
    "interfaces": LayerInterfaces,
    "interface":  LayerInterfaces,
    "adapters":   LayerInterfaces,
    "adapter":    LayerInterfaces,

    // Infrastructure
    "infrastructure": LayerInfrastructure,
    "infra":          LayerInfrastructure,

For examples please go to examples directory, with contains examples of valid and invalid architectures.

For more information you should read our article about Clean Architecture.


go install

go-cleanarch was only tested on Linux and also should work on OS X. Probably it doesn't work well on Windows.


To run in the current directory:


To run in provided directory

go-cleanarch go/src/

Process will exit with code 1 if architecture is not valid, otherwise it will exit with 0.


If you need to ignore *_test.go files in go-cleanarch check you can pass -ignore-tests

go-cleanarch -ignore-tests

It is useful when you have memory implementation in infrastructure layer and you need to test application service which depends of it.


If for some reason you need to allow to make forbidden import, for example to

you can use


Layer names

The layer names can be set to a specific value with the following parameters. Each parameter stands for on layer.

go-cleanarch -domain dom -application appli -interfaces int -infrastructure outer

This would only allow the domain name to be dom, application hast to be appli, interafces must be int and infrastructure must be outer.

Running the tests

make test

And coding style tests

make qa


Please read for details on our code of conduct, and the process for submitting pull requests to us.


We use SemVer for versioning. For the versions available, see the tags on this repository.


Made without love by Robert Laszczak </3

Author: Roblaszczak
Source Code: 
License: MIT license

#go #golang #architecture 

Go-clean-template: Clean Architecture Template for Golang Services

Go Clean template

Clean Architecture template for Golang services



The purpose of the template is to show:

  • how to organize a project and prevent it from turning into spaghetti code
  • where to store business logic so that it remains independent, clean, and extensible
  • how not to lose control when a microservice grows

Using the principles of Robert Martin (aka Uncle Bob).

Go-clean-template is created & supported by Evrone.


Quick start

Local development:

# Postgres, RabbitMQ
$ make compose-up
# Run app with migrations
$ make run

Integration tests (can be run in CI):

# DB, app + migrations, integration tests
$ make compose-up-integration-test

Project structure


Configuration and logger initialization. Then the main function "continues" in internal/app/app.go.


Configuration. First, config.yml is read, then environment variables overwrite the yaml config if they match. The config structure is in the config.go. The env-required: true tag obliges you to specify a value (either in yaml, or in environment variables).

For configuration, we chose the cleanenv library. It does not have many stars on GitHub, but is simple and meets all the requirements.

Reading the config from yaml contradicts the ideology of 12 factors, but in practice, it is more convenient than reading the entire config from ENV. It is assumed that default values are in yaml, and security-sensitive variables are defined in ENV.


Swagger documentation. Auto-generated by swag library. You don't need to correct anything by yourself.


Integration tests. They are launched as a separate container, next to the application container. It is convenient to test the Rest API using go-hit.


There is always one Run function in the app.go file, which "continues" the main function.

This is where all the main objects are created. Dependency injection occurs through the "New ..." constructors (see Dependency Injection). This technique allows us to layer the application using the Dependency Injection principle. This makes the business logic independent from other layers.

Next, we start the server and wait for signals in select for graceful completion. If app.go starts to grow, you can split it into multiple files.

For a large number of injections, wire can be used.

The migrate.go file is used for database auto migrations. It is included if an argument with the migrate tag is specified. For example:

$ go run -tags migrate ./cmd/app


Server handler layer (MVC controllers). The template shows 2 servers:

  • RPC (RabbitMQ as transport)
  • REST http (Gin framework)

Server routers are written in the same style:

  • Handlers are grouped by area of application (by a common basis)
  • For each group, its own router structure is created, the methods of which process paths
  • The structure of the business logic is injected into the router structure, which will be called by the handlers


Simple REST versioning. For v2, we will need to add the http/v2 folder with the same content. And in the file internal/app add the line:

handler := gin.New()
v1.NewRouter(handler, t)
v2.NewRouter(handler, t)

Instead of Gin, you can use any other http framework or even the standard net/http library.

In v1/router.go and above the handler methods, there are comments for generating swagger documentation using swag.


Entities of business logic (models) can be used in any layer. There can also be methods, for example, for validation.


Business logic.

  • Methods are grouped by area of application (on a common basis)
  • Each group has its own structure
  • One file - one structure

Repositories, webapi, rpc, and other business logic structures are injected into business logic structures (see Dependency Injection).


A repository is an abstract storage (database) that business logic works with.


It is an abstract web API that business logic works with. For example, it could be another microservice that business logic accesses via the REST API. The package name changes depending on the purpose.


RabbitMQ RPC pattern:

  • There is no routing inside RabbitMQ
  • Exchange fanout is used, to which 1 exclusive queue is bound, this is the most productive config
  • Reconnect on the loss of connection

Dependency Injection

In order to remove the dependence of business logic on external packages, dependency injection is used.

For example, through the New constructor, we inject the dependency into the structure of the business logic. This makes the business logic independent (and portable). We can override the implementation of the interface without making changes to the usecase package.

package usecase

import (
    // Nothing!

type Repository interface {

type UseCase struct {
    repo Repository

func New(r Repository) *UseCase{
    return &UseCase{
        repo: r,

func (uc *UseCase) Do()  {

It will also allow us to do auto-generation of mocks (for example with mockery) and easily write unit tests.

We are not tied to specific implementations in order to always be able to change one component to another. If the new component implements the interface, nothing needs to be changed in the business logic.

Clean Architecture

Key idea

Programmers realize the optimal architecture for an application after most of the code has been written.

A good architecture allows decisions to be delayed to as late as possible.

The main principle

Dependency Inversion (the same one from SOLID) is the principle of dependency inversion. The direction of dependencies goes from the outer layer to the inner layer. Due to this, business logic and entities remain independent from other parts of the system.

So, the application is divided into 2 layers, internal and external:

  1. Business logic (Go standard library).
  2. Tools (databases, servers, message brokers, any other packages and frameworks).

Clean Architecture

The inner layer with business logic should be clean. It should:

  • Not have package imports from the outer layer.
  • Use only the capabilities of the standard library.
  • Make calls to the outer layer through the interface (!).

The business logic doesn't know anything about Postgres or a specific web API. Business logic has an interface for working with an abstract database or abstract web API.

The outer layer has other limitations:

  • All components of this layer are unaware of each other's existence. How to call another from one tool? Not directly, only through the inner layer of business logic.
  • All calls to the inner layer are made through the interface (!).
  • Data is transferred in a format that is convenient for business logic (internal/entity).

For example, you need to access the database from HTTP (controller). Both HTTP and database are in the outer layer, which means they know nothing about each other. The communication between them is carried out through usecase (business logic):

    HTTP > usecase
           usecase > repository (Postgres)
           usecase < repository (Postgres)
    HTTP < usecase

The symbols > and < show the intersection of layer boundaries through Interfaces. The same is shown in the picture:


Or more complex business logic:

    HTTP > usecase
           usecase > repository
           usecase < repository
           usecase > webapi
           usecase < webapi
           usecase > RPC
           usecase < RPC
           usecase > repository
           usecase < repository
    HTTP < usecase



Clean Architecture Terminology

Entities are structures that business logic operates on. They are located in the internal/entity folder. In MVC terms, entities are models.

Use Cases is business logic located in internal/usecase.

The layer with which business logic directly interacts is usually called the infrastructure layer. These can be repositories internal/usecase/repo, external webapi internal/usecase/webapi, any pkg, and other microservices. In the template, the infrastructure packages are located inside internal/usecase.

You can choose how to call the entry points as you wish. The options are:

  • controller (in our case)
  • delivery
  • transport
  • gateways
  • entrypoints
  • primary
  • input

Additional layers

The classic version of Clean Architecture was designed for building large monolithic applications and has 4 layers.

In the original version, the outer layer is divided into two more, which also have an inversion of dependencies to each other (directed inward) and communicate through interfaces.

The inner layer is also divided into two (with separation of interfaces), in the case of complex logic.

Complex tools can be divided into additional layers. However, you should add layers only if really necessary.

Alternative approaches

In addition to Clean architecture, Onion architecture and Hexagonal (Ports and adapters) are similar to it. Both are based on the principle of Dependency Inversion. Ports and adapters are very close to Clean Architecture, the differences are mainly in terminology.

Similar projects

Useful links

Download Details:

Author: Evrone
Source Code: 
License: MIT license

#go #golang #clean #template