Inevitably, every Go developer asks the following question: How do I organize my code? There are many articles and approaches, and while some work well for some, they may not work well for others. Go has no official conventions and preferences on how you should structure your packages and where your non-code resources should reside. Unlike other languages though, Go does not allow . Projects thus require additional planning when grouping code into packages to ensure that dependencies do not import each other. circular package imports The goal of this article is not to specify a strict convention, but rather advocate building for reasoning about your problem domains and how to represent them in your project layouts. robust mental models Project Layout Types No approach is perfect, but there are a few that have gained widespread adoption. Please check the following resources: article on . Ben Johnson's Standard Package Layout . Golang Standards Project Layout excellent talk, presentation and code samples can be found . Kat Zien's here Now we are going to explore what options are available for structuring your applications and distinguish between some good and some bad practices. Flat Structure Rather than spending time trying to figure out how to break your code into packages, an app with a flat structure would just place all of the files in a single package. .go At first, this sounds awful, because we do not use packages that separate concerns while making it easier to navigate to the correct source files quickly. Recommendations When using a flat structure you should still try to adhere to coding best practices. Here are some helpful tips: You want to separate different parts of your application using different files: .go restaurant-app/  
  customer.go  
  data.go  
  handlers.go  
  main.go  
  reservation.go  
  server.go  
  storage.go  
  storage_json.go   
  storage_mem.go Global variables can still become problematic, so you should consider using types with methods to keep them out of your code: package main

import (
	"net/http"
	"some"
	"someapi"
)

type Server struct {
	apiClient *someapi.Client
	router    *some.Router
}

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	s.router.ServeHTTP(w, r)
} Your function should still be stripped of most logic outside of setting up the application. main() A possible improvement to the flat structure is to again put all of your code into a single package, but separate the package where you define the entry point of the application. This would allow you to use the common sub-directory pattern: main cmd restaurant-app/
  cmd/
    web/
      # package main
      main.go
    cli/
      # package main
      main.go
  # package restaurantapp
  server.go
  customer_handler.go
  reservation_handler.go
  customer_store.go This project layout is usually suitable for small libraries or CLI tools and very simple projects. Anti Pattern: Group by Function (Layered Architecture) Layered architecture patterns are n-tiered patterns where the components are organized in . layers This is the traditional method for designing most software and is meant to be , i.e. all the components are interconnected, but do NOT depend on each other. self-independent We have all heard about the famous 3-tier MVC (Model-View-Controller) architecture where we split our application into the following 3 distinct layers: — Presentation / User Interface ( ) View — Business Logic ( ) Controller — Storage / External Dependencies ( ) Model This architecture translated into our example project layout would look like this: restaurant-app/
  # package main
  data.go
  handlers/
    # package handlers
    customers.go
    reservations.go
  # package main
  main.go
  models/
    # package models
    customer.go
    reservation.go
    storage.go
  storage/
    # package storage
    json.go
    memory.go
  ... This type of layout should NOT compile at all due to circular dependencies. The package uses the package to get the definitions for a and a and the package uses the package to make calls to the database. storage models Customer Reservation models storage Another disadvantage of this structure is that it does not guide us about what the application does (at least not more than the flat structure). This type of layout is strongly NOT recommended when writing applications in Go so try to avoid it. Anti Pattern: Group by Module Grouping by Module offers us a slight improvement over the layered approach: restaurant-app/
  customers/
    # package customers
    customer.go
    handler.go
  # package main
  main.go
  reservations/
    # package reservations
    reservation.go
    handler.go
  storage/
    # package storage
    data.go
    json.go
    memory.go
    storage.go
  ... Now our application is structured logically, but that is probably the only advantage of this approach. It is still hard to decide, e.g., if should go to the package because they are customer reservations or are they suited for having their own package. reservation customers Naming is worse because we now have and which introduces stutter. reservations.Reservation customers.Customer Worst of all is the possibility of circular dependencies again if the package needs to reference the package and vice versa. reservations customers Group by Context (Domain Driven Design) This way of thinking about your applications is called . Domain Driven Design (DDD) In its essence it guides you to think about the domain you are dealing with and all the business logic without even writing a single line of code. Three main components need to be defined: — Bounded contexts — Models within each context — Ubiquitous language Bounded Contexts A bounded context is a fancy term defining limits upon your models. An example would be, e.g., a entity that might have different properties attached to it based on the context: User A in a sales department context might have properties like , , etc. User leadTime costOfAquisition A in a customer support context might have properties like , , etc. User responseTime numberOfTicketsHandled This showcases that a means different things to different people, and the meaning depends heavily on the . User context The bounded context also helps in deciding what has to stay consistent within a particular boundary and what can change independently. If we decide later on to add a new property to the from the sales department context, that would not affect the model in the customer support context. User User Ubiquitous Language is the term used in for the practice of building up a common, rigorous language between developers and users. Ubiquitous Language Domain Driven Design This language is based on the used in the software, and it evolves up to the point of being able to express complex ideas by combining simple elements of the . Domain Model Domain Model Categorizing the building blocks Based on the methodology we will now start to reason about our domain by constructing its building blocks. DDD If we take our example, we would have the following elements: Restaurant Reservation System : Booking Reservations. Context : reservation, customer, storage, … Language : Reservation, Customer, … Entities : Restaurant, Host, … Value Objects : BookedReservation Aggregates : Reservation lister/listing, Reservation adder/adding, Customer adder/adding, Customer lister/listing, … Service : ReservationAdded, CustomerAdded, ReservationAlreadyExists, ReservationNotFound, … Events : ReservationRepository, CustomerRepository, … Repository Now after defining those blocks we can translate them into our project layout: restaurant-app/
  adding/
    endpoint.go
    service.go
  customers/
    customer.go
    sample_customers.go
  listing/
    endpoint.go
    service.go
  main.go
  reservations/
    reservation.go
    sample_reservations.go
  storage/
    json.go
    memory.go
    type.go The main advantage here is that our packages now communicate what they and not what they . PROVIDE CONTAIN This makes it easier to avoid , because: circular dependencies and talk to . adding listing storage pulls from and . storage customers reservations Model packages like and do not care about directly. reservations customers storage Group by Context (Domain Driven Design + Hexagonal Architecture) So far we managed to structure our application according to , eliminated and made it intuitive what each package does only by looking at the directory and file names. DDD circular dependencies We still have some problems though: *?* How can we start a version of our application that contains sample data In our current version sample data is bundled with the application’s entry point in main.go and we have only one main.go . We have NO option to run a sample data version separately from the main version of the application. Maybe we want a pure CLI version of the application where instead of adding reservations through HTTP requests, we want the command line to prompt us for each reservation property? Hexagonal Architecture This type of architecture distinguishes the parts of the system which form your and all the external dependencies are just implementation details. core domain Fig. 1: Hexagonal Architecture Layers Diagram External dependencies could be databases, external APIs, mail clients, cloud services etc., anything that your application interacts with. The problem this solves is giving you the ability to change one part of the application without affecting the rest, e.g., swapping databases or transport protocols (HTTP to gRPC). This is not in any way similar to the model, because: MVC (layered) tends to look at inputs and outputs in a top to bottom way (input -> main logic -> output). MVC Fig. 2: Layered Architecture Dependency Direction treats inputs and outputs on the same level. It does not care if something is an input or an output, it is just an external interface. Hex Fig. 3: Dependency Inversion Direction The key rule in the model is that dependencies only point (only and not the other way around). This is called the . Check by Martin Fowler to learn more. hex INWARDS outer layers depend upon inner layers Dependency Inversion Principle this excellent article Recommendations Based on this approach our project structure could look like this: restaurant-app/
  cmd/
    # HTTP server
    restaurant-server/
      main.go
    # CLI app
    restaurant-cli/
      main.go
    # HTTP server with seeded data
    restaurant-sample-data/
      main.go
      sample_reservation.go
      sample_customers.go
  pkg/
    adding/
      reservation.go
      endpoint.go
      service.go
    listing/
      customer.go
      reservation.go
      endpoint.go
      service.go
    transport/
      http/
        server.go
    main.go
    storage/
      json/
        customer.go
        repository.go
        reservation.go
      memory/
        customer.go
        repository.go
        reservation.go To solve the multiple app version binaries problem we utilize the sub-directory pattern which we mentioned as an improvement to the layout. cmd flat structure We are now able to produce 3 different binaries used to serve different purposes: - main version of the app deploying an HTTP server. restaurant-server - a CLI version with a removed transport layer offering a CLI interface for interaction. restaurant-cli - a sample data seeded version used mainly for testing. restaurant-sample-data We introduce the package which separates our Go code from the binaries and non-code resources, e.g. DB scripts, configs, documentation, etc. which should be found on the same level under the project's root directory. pkg cmd NOTE Using the cmd and pkg directories has become somewhat of a trend in the Go community. It is not a standard by any means, but a good recommendation that should be considered. According to we keep the and packages that represent our core domain. DDD adding listing We remove and packages and instead introduce models in each of the core domain packages, e.g., , , , etc. reservations customers adding.Reservation adding.Customer listing.Reservation The advantage here is that we have separate representations per model according to the ( or ). This allows decoupled model modification and avoids . bounded context adding listing circular dependencies We introduce a package which contains all transport protocol implementations, e.g. HTTP or maybe gRPC in their respective sub-packages. transport The package is another that features its model representations on a storage level and sub-packages for storage implementations, e.g. , , etc. storage bounded context json memory Again, ties everything together and should not contain any logic that would require testing. main.go Conclusion Unfortunately, there is no single right answer, but at least we outlined some examples of problem domains, how to reason about them and how to translate that reasoning into Go package organization. Great freedom comes with great responsibility! Use the following guidelines wisely: “Make everything as simple as possible, but not simpler.” — . Albert Einstein Maintain consistency. Flat and simple is OK for small projects. Avoid global scope and . init() Separate depended upon code into its own package. Two top-level directories: — (for your binaries) — (for your packages) cmd pkg All other project files (DB scripts, fixtures, resources, docs, Docker configs, etc.) — should reside under your project’s root directory. Group by context, not generic functionality. Try . DDD/Hex package initializes and ties everything together. main Also published . here

A Comprehensive Guide to Approaching Package Organization in Go

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Why Gemini 3.0 is a Great Builder But Still Needs a Human in the Loop

The HackerNoon Newsletter: How to Turn Year-End Reflections into Q1 Content Gold (12/4/2025)

The Art of the Prompt: Engineering GenAI to Produce SOLID-Compliant Code

Tired of Learning 50 New Concepts to Build a Form? Say Hello to Lighthouse for PHP

Why I Built Allos to Decouple AI Agents From LLM Vendors

When The Oldest Programming Language Outsmarts The Newest AI

Why Gemini 3.0 is a Great Builder But Still Needs a Human in the Loop

The HackerNoon Newsletter: How to Turn Year-End Reflections into Q1 Content Gold (12/4/2025)

The Art of the Prompt: Engineering GenAI to Produce SOLID-Compliant Code

Tired of Learning 50 New Concepts to Build a Form? Say Hello to Lighthouse for PHP

Why I Built Allos to Decouple AI Agents From LLM Vendors

When The Oldest Programming Language Outsmarts The Newest AI

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps