project-layout

A community maintained directory structure for Go application projects that is careful to say it is not an official standard, only a set of common patterns.

The README is upfront about what this is not. It is not an official standard from the core Go team, and it does not try to cover structures like Clean Architecture. It describes itself as a basic layout for Go application projects, focused on the general shape rather than what sits inside. The framing is a set of common historical and emerging patterns, some more popular than others.

For learning Go, a proof of concept, or a small personal project, the README says this layout is overkill. A single main.go file and a go.mod are enough. Structure matters as the project grows, when more people work on it and shared packages start to appear. The same section notes that with Go 1.14, Go Modules are ready for production use.

The cmd directory holds the main applications, and each folder name should match the executable, so cmd/myapp for example. The advice is to keep those application directories thin, with a small main function that imports and invokes code from elsewhere. Reusable code belongs in pkg, and private code belongs in internal, a pattern the Go compiler itself enforces. The README also notes that pkg is common but not universally accepted, and skipping it for small projects is fine.

The project is a community effort, and issues are open for new patterns or updates to existing ones. For naming and formatting, the recommendation is to run gofmt and staticcheck, since golint is deprecated. A reference project called iam is cited as a popular example that follows this layout closely.

• Source 1 · Project repository
• Source 2 · README