technical

How I organize (most of) my Go microservices

The folder layout I use for most of my Go microservices, with a clear place for API specs, build files, deployment, docs, scripts and the internal packages.

When I first learned Go, my instinct was to look for a framework that would scaffold a folder structure and the basic plumbing for my first project. It didn’t take long to realize that Go, thanks to its rich standard library, doesn’t need one. A framework owns your main function and your request lifecycle, so you upgrade on its schedule and fight it whenever you need something it didn’t plan for. Since then, I’ve welcomed many developers to my team who came from other languages. Some of them were surprised that different parts of our codebase had no consistent folder structure at all.

Not using a pre-packaged boilerplate means you are free to structure each project the way it needs. But some patterns show up again and again, and for those I keep a template project as a starting point. A template is copied once and then belongs to the service, which is the difference from a framework. The deal I settled on: the top level of every service looks the same, so anyone can navigate any repo, and what lives inside internal is the team’s call.

This is that layout. It fits most of my services. The exceptions are usually CLIs and one-off jobs that have no API to describe and nothing to deploy.

First: a few ground rules

A few rules I follow for names:

  • Package names are one word, lowercase, with no separators. The first two are the official guidance; keeping them singular is my preference, and the standard library has plenty of plural ones like strings and errors.
  • Each package has a .go file with the same name that declares its main interface or struct.
  • Folders that are not packages can have multi-word names, separated by -, never _. Go itself doesn’t care, since those folders hold no Go code.

The minimal folder structure

.
├── 📁 .local
├── 📁 api
├── 📁 build
├── 📁 deployment
├── 📁 docs
│   ├── 📁 architecture
│   │   └── 📁 decision-records
│   ├── 📁 develop
│   ├── 📁 release-notes
│   └── 📁 runbooks
├── 📁 scripts
├── 📁 cmd
└── 📁 internal
    ├── 📁 app
    ├── 📁 logger
    ├── 📁 metrics
    └── 📁 server

The folders are listed in the order I read them: infrastructure first, code last.

📁 .local

The .local folder holds everything I need to run the app on my own machine but that plays no part in deployment: secrets, Compose files, debugging helpers. The Compose files are committed and the secrets are not. The .gitignore ignores the whole folder and then lets the Compose files back in:

.local/*
!.local/compose*.yaml

📁 api

The api folder holds the files that define the service’s API for each protocol it speaks: OpenAPI specs for REST, .proto files for gRPC, GraphQL schemas.

📁 build

The build folder holds everything needed to produce images and binaries, both for deployment and for local development: the Dockerfile, packaging scripts and other build files. Keeping all of it in one place makes the build process easier to maintain.

📁 deployment

The deployment folder holds the deployment-specific files, such as Helm charts and templates.

📁 docs

These are mostly markdown files. Some are rendered by tools like Backstage or MkDocs, and some are meant for developers working on the project, who read them in their IDE.

It usually has four subfolders:

  • architecture: diagrams and decision records.
  • develop: notes for people working on the code, like how to debug a subsystem or install a library locally.
  • release-notes: one markdown file per release, named after its semantic version, saying what was fixed and what was added.
  • runbooks: step-by-step fixes for production problems I have already seen once.

📁 scripts

This is where I keep the scripts, mostly written in Bash but sometimes in Go. They handle tasks like updating libraries and installing dependencies.

They are invoked through make targets. Keeping them here keeps the Makefile at the root short.

📁 cmd

The cmd folder holds the entry points. Each binary gets a folder with its name and a small main.go inside. The main.go stays short because the heavy lifting is done by the packages inside internal.

📁 internal

The internal folder holds the private packages that make up the service. The Go toolchain refuses to compile an import of an internal package from outside the module, so nothing in here can leak into other services.

Almost every project has four packages in here: app, server, logger and metrics. Each of them takes its configuration through the functional options pattern, an idea from Rob Pike that Dave Cheney popularized. The caller decides the settings and the package stays reusable. On disk that looks like:

└── 📁 package
    ├── 📄 package.go
    └── 📄 option.go

The app package is the only one that main.go instantiates and runs. It exposes a constructor and a one-method interface:

// New creates an App configured with the given options.
func New(context.Context, ...Option) (App, error)

type App interface {
	Run(context.Context) error
}

Both return an error so that a failed startup, such as an unreachable database, reaches main.go, which is the only place that calls os.Exit. The app package wires the other packages together through their options, so each one gets its configuration injected rather than reading it itself. It also shuts the other components down cleanly when the process receives a signal.

The business code lives in its own packages next to these four, one per domain concept. Those packages never import server, logger or metrics directly. The app package builds them and hands their handlers to server. When a service grows a second binary, such as a worker, that binary gets its own composition package built the same way.

The other packages you will find in my template are:

  • logger: a thin wrapper around whichever logging library the project uses, adapted to my own needs.
  • metrics: metrics and observability, usually behind prometheus counters and histograms.

server is the part that listens. Some projects speak REST, some gRPC, a few both, and on rare occasions GraphQL, so the package exposes one interface:

type Server interface {
	Start(context.Context) error
	Stop(context.Context) error
}

Start blocks until the listener dies and Stop returns whatever the shutdown reported, so app can run several servers under an error group and log every failure. Each of http.go, grpc.go and, when needed, graphql.go implements the interface for its protocol.

📄 Root files

The root also holds these files:

  • 📄 .editorconfig
  • 📄 .gitattributes
  • 📄 .gitignore
  • 📄 .golangci.yaml
  • 📄 CODEOWNERS
  • 📄 CONTRIBUTING.md
  • 📄 LICENSE.md
  • 📄 Makefile
  • 📄 README.md
  • 📄 SECURITY.md
  • 📄 go.mod
  • 📄 go.sum

Add sonar-project.properties if the project uses SonarQube and catalog-info.yaml if it is registered in Backstage.

Final project skeleton

.
├── 📄 .editorconfig
├── 📄 .gitattributes
├── 📄 .gitignore
├── 📄 .golangci.yaml
├── 📄 CODEOWNERS
├── 📄 CONTRIBUTING.md
├── 📄 LICENSE.md
├── 📄 Makefile
├── 📄 README.md
├── 📄 SECURITY.md
├── 📄 go.mod
├── 📄 go.sum
├── 📁 .local
│   ├── 📄 compose.yaml
│   └── 📄 compose.debug.yaml
├── 📁 api
│   └── 📄 openapi.json
├── 📁 build
│   └── 📄 Dockerfile
├── 📁 deployment
│   └── 📁 helm
│       ├── 📁 templates
│       ├── 📄 .helmignore
│       └── 📄 Chart.yaml
├── 📁 docs
│   ├── 📁 architecture
│   │   └── 📁 decision-records
│   ├── 📁 develop
│   ├── 📁 release-notes
│   │   ├── 📄 template.md
│   │   └── 📄 v1.0.0.md
│   └── 📁 runbooks
├── 📁 scripts
├── 📁 cmd
│   └── 📁 myapp
│       └── 📄 main.go
└── 📁 internal
    ├── 📁 app
    │   ├── 📄 app.go
    │   └── 📄 option.go
    ├── 📁 logger
    │   ├── 📄 logger.go
    │   └── 📄 option.go
    ├── 📁 metrics
    │   ├── 📄 metrics.go
    │   ├── 📄 prometheus.go
    │   └── 📄 option.go
    └── 📁 server
        ├── 📄 grpc.go
        ├── 📄 http.go
        ├── 📄 option.go
        └── 📄 server.go

When the layout outgrows one repo

Some folders inside internal end up nearly identical across services. Those can be extracted as separate modules and imported as dependencies, so a fix lands in one place and each service chooses when to upgrade. logger and metrics are the usual candidates. This is the one place where I accept a shared dependency, and it carries the same risk as a framework: every breaking change fans out to every service. So I extract a package only after a few services have copied it unchanged, and I keep its public surface to a small interface that never exposes the underlying library’s types.

That is the whole layout. Anyone on my team can open any service and know where the API spec, the runbook and the entry point live before reading a single line of code, which is all I ever wanted from a framework.