Guide · Open source
How to use go-clean-arch: run the Clean Architecture Go example
Updated · written with AI from the project's own documentation and checked against our catalogue data
go-clean-arch is an MIT-licensed example project written in Go that shows how to organize a backend using Clean Architecture, the approach popularized by Uncle Bob. It is a reference codebase rather than a library or framework. This guide walks through what the project contains, how to run it with Docker Compose and Make, and how to read its layers so you can apply the same ideas to your own Go service.
go-clean-archbxcodec/go-clean-arch · ★ 10.2k · MIT Install options & downloads Quick start
- 1Check prerequisites. Install Docker, Docker Compose and Make, and set up a MySQL database.
- 2Load the database. Run article.sql against your MySQL database, as the README instructs.
- 3Clone the repository. Clone bxcodec/go-clean-arch into a folder outside GOPATH and move into it.
- 4Create the environment file. Copy example.env to .env.
- 5Start the application. Run make up and wait for hot reload to start.
- 6Test the endpoint. Call localhost:9090/articles with curl to confirm the app responds.
- 7Run the tests. Run make tests to execute the test suite.
What is go-clean-arch?
go-clean-arch is an example implementation of Clean Architecture in Go. The core idea it demonstrates is that business rules should not depend on the database, the web framework or other external details.
The README says the project has four layers: Models, Repository, Usecase and Delivery. The repository also includes a diagram of the structure.
- Models layer
- Repository layer
- Usecase layer
- Delivery layer
What are the prerequisites?
The README's quick-start uses Docker Compose and Make, and it expects a MySQL database loaded with article.sql. It also assumes you are comfortable with Go modules. The README recommends placing the source code in any folder outside GOPATH because the project uses Go Modules.
- Docker and Docker Compose
- Make
- Go modules (check go.mod for the required Go version)
- MySQL, with article.sql loaded into it
Install and run go-clean-arch with Docker
Run these commands in a terminal. The README says to move to your workspace, clone the repository, copy the example environment file to .env, and then start the application with make up. Hot reload runs while the application is up.
Make sure you have run article.sql in your MySQL database before you start, as the README instructs.
cd workspace
git clone https://github.com/bxcodec/go-clean-arch.git
cd go-clean-arch
cp example.env .env
make upTest the running application
With the application running, the README shows a curl call in a second terminal to fetch the articles endpoint on port 9090. The README also documents a separate command to run the test suite.
- Fetch articles: curl localhost:9090/articles
- Run tests: make tests
curl localhost:9090/articles
make testsHow do the layers fit together?
The README describes the layers as separate domains of responsibility. Models hold the data definitions, Repository handles data access, Usecase holds the application logic, and Delivery handles the entry point such as HTTP.
The README also explains the version history. The current master branch is v4, which declares interfaces on the consuming side, introduces an internal package, and adds a service-focused package. Older versions are kept on their own branches, and the author notes that the differences are mostly in directory layout and tooling. The README encourages you to compare branches and pick the structure you like best.
- v1 and v2: earlier branches kept for reference
- v3: introduced a domain package
- v4 (master): interfaces declared on the consuming side, internal package, service-focused package
Which tools does the project use?
The README says the project uses the libraries listed in go.mod. It also uses mockery to generate mocks for testing. The author notes that you can swap in any library that serves the same purpose.
- Libraries listed in go.mod
- github.com/vektra/mockery for generating mocks
What people use it for
- Studying how models, repositories, use cases and delivery code are separated in a Go project.
- Using the layout as a reference when starting a new Go backend service.
- Comparing the v1 to v4 branches to see how the structure changed over time.
- Learning how to generate mocks with mockery for unit tests.
Frequently asked questions
Is go-clean-arch free to use?
Yes. The project is licensed under MIT, as listed on its repository page. You can use, modify and distribute it under the terms of that licence.
What do I need to install before running go-clean-arch?
The README lists Docker, Docker Compose, Make, a Go module setup and MySQL. You also need to load article.sql into your MySQL database before starting the app.
How do I start go-clean-arch?
Clone the repository, move into the folder, copy example.env to .env and run make up. The README says hot reload will run while the application is up.
Is go-clean-arch a framework or library?
No. It is an example project that demonstrates a structure. It is not meant to be imported as a production framework.
Why do I need to run article.sql first?
The README says to run article.sql in your MySQL database before running the application. This sets up the database the example expects.
What are good alternatives for structuring a Go project?
Comparable projects mentioned for this topic include Go Kit, Buffalo, the Gin Gonic Project Layout and the Bee Framework. Go Kit and Buffalo are general toolkits, while Gin Gonic Project Layout is a layout guide for Gin apps.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Go developers and students who want a concrete, readable example of Clean Architecture will find go-clean-arch useful, especially for comparing layouts across its branches. If you need a production framework, a small script, or a beginner's introduction to Go, pick a different resource.
Install options & downloads