go-project-layout

Go Project Layout

Structure follows size. The biggest layout mistake in Go is copying a microservice skeleton for a 500-line tool — or growing a 50-package service inside a flat directory. Match the layout to the project.

1. Pick the Layout by Project Size

Project	Layout
Small tool, single binary, <5 files	Flat: everything in package main at the root
Library for others to import	Root package named after the module, internal/ for helpers
Service with one binary	cmd/<name>/main.go + internal/ packages
Multiple binaries sharing code	cmd/<name1>/, cmd/<name2>/ + internal/

Never start with empty pkg/, api/, docs/, build/ directories "for later". Add structure when the code demands it, not before.

2. Module Naming

# ✅ Good — repository path, lowercase
go mod init github.com/acme/payment-service

# ❌ Bad — not fetchable, uppercase, or vanity without DNS
go mod init PaymentService
go mod init payment_service

The last path element should match what users will see: for a library, it becomes the default import name.

3. Service Layout (the default for APIs and workers)

payment-service/
├── cmd/
│   └── payment-api/
│       └── main.go         # flag/env parsing, wiring, Run() — nothing else
├── internal/
│   ├── domain/             # core types, business rules; zero external deps
│   ├── service/            # use cases orchestrating domain + stores
│   ├── store/              # data access implementations (postgres/, redis/)
│   ├── handler/            # HTTP/gRPC adapters
│   └── config/             # config loading and validation
├── migrations/             # if the service owns a database
├── go.mod
├── Makefile
└── README.md

Rules:

• internal/ by default — the compiler enforces that nobody outside the module imports it. Promote to a public package only on demand.
• pkg/ only when external consumers exist AND the module also has private code. When in doubt, don't create it.
• Dependencies point inward: handler → service → domain ← store. domain imports neither store nor handler.