Skip to content
Get packs

go-clean-arch

A sample Go project showing how to structure an API using Clean Architecture ideas.

GitHub Download v2.0.1
Stars
10.2k
Forks
1.3k
Licence
MIT
Language
Go
Last update
2.5 years ago
Type
Learning resource

No commits in over a year — check for forks or alternatives before adopting.

What it is

This is an example codebase in Go (Golang) that demonstrates how to organize a backend application using Clean Architecture, an approach popularized by Uncle Bob. It separates the code into layers such as models, repositories, use cases, and delivery so that business rules do not depend on the database or web framework. People use it as a reference when designing their own Go projects.

  • Read the layered folder structure to understand how use cases call repositories through interfaces
  • Run the included test suite with make tests to see how the layers are mocked and tested
  • Start the sample service with docker-compose and call the articles endpoint locally
  • Use the code as a starting template for your own API structure

Great for

  • Go developers who want to see a concrete example of Clean Architecture
  • Students learning how to separate business logic from databases and HTTP handlers
  • Teams comparing project layouts before starting a new Go service

Not ideal for

  • Readers who want a ready-made production framework, since this is an example project rather than a library
  • Developers who need a simple script or small tool, because the layered structure adds overhead
  • Anyone new to Go, since the README assumes familiarity with Go modules and MySQL
Step-by-step guide: how to use go-clean-archInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Run with Docker

    You'll need: Docker · Docker Compose · Make · Go modules (see go.mod for the required Go version) · MySQL (the README says to load article.sql into it)

    Clone the repository

    git clone https://github.com/bxcodec/go-clean-arch.git

    Move into the project folder

    cd go-clean-arch

    Copy the example environment file

    cp example.env .env

    Run the application

    make up
  2. 2

    Run it

    • Clone the repository and move into its folder.
    • Copy example.env to .env.
    • Run make up to start the application with docker-compose.
    • In another terminal, run curl localhost:9090/articles to call the API.
  3. 3

    Get the most out of it

    • Run make tests to check the code and see how the layers are tested with mocks
    • Read the v1 to v4 branches to compare how the directory structure has changed over time
    • Follow the linked Medium articles for the reasoning behind the design choices
    • Swap the data layer for another database, since the README describes the layers as independent of the database

Downloads

Source code (.zip)master branch · straight from GitHubRelease v2.0.1Release notes and source

Strengths

  • Clear, readable example of a layered Go project structure
  • Includes tests and mock generation with mockery
  • README links to a write-up explaining the design reasoning and version history

Trade-offs

  • The README is short and some setup details, such as database schema loading, are only briefly mentioned
  • It is an example project, so it may not reflect current best practices for every team
  • Last code push was in April 2024, so it may lag behind newer Go versions or libraries

How it compares

ProjectStarsTypeLevelUpdatedBest for
go-clean-arch (this)10.2kLearning resourceintermediate2.5 years agoGo developers who want to see a concrete example of Clean Architecture
usql10.2kCLIbeginner4 days agoDevelopers who use several different databases and want one tool for all of them
kysely14.3kLibraryintermediate4 days agoTypeScript developers who want SQL control without losing compile-time type checks
modular-monolith-with-ddd14.1kLearning resourceadvanced2.4 years agoDevelopers learning Domain-Driven Design tactical patterns in C#
tech-interview-for-developer17.7kLearning resourcebeginner1.4 years agoKorean-speaking junior developers preparing for technical interviews
domain-driven-hexagon15kLearning resourceintermediate2.4 years agoDevelopers who want to understand Domain-Driven Design and hexagonal architecture through examples

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.