Project structure · Backend
Go REST API project structure
Opens with creditsA JSON API in Go using the standard library router, PostgreSQL through pgx and sqlc, SQL migrations with goose, and tests next to the code. It follows the layout the Go team itself documents: commands in cmd/, everything else in internal/, one package per feature plus a small platform package for the plumbing, and nothing added until it is needed.
Curated by Tauseef FayyazIntermediate176 files and foldersGo 1.27, net/http ServeMux patterns, log/slogChecked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you13 files and folders
- 2GrowingWhat a real app with features and tests adds+73 files and folders
- ProductionWhat running it for real users adds+43 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+47 files and foldersOpens with credits
How it is organised
- Start flat and add folders when they earn their place. The Go team says a small project can be a single main package; this tree is what a growing API needs over years, not a starting template to copy whole.
- Commands live in cmd/<name>/main.go and stay tiny. All logic lives in internal/, which the Go toolchain refuses to let other modules import.
- Skip pkg/. The official layout guide never mentions it, and for a server nothing is meant to be imported by others. The popular golang-standards/project-layout repository is a community collection, not a Go standard, and the Go team has said so.
- Package by feature (internal/order), not by layer (internal/handlers, internal/models). Each feature owns its handler, service, store and SQL. Plumbing every feature shares (config, logging, database, middleware) lives in internal/platform.
- Dependencies point one way: server imports features, features import platform, platform imports nothing of yours. Go rejects import cycles at compile time, and an architecture test keeps the rest honest.
- Define interfaces where they are used, small, and only when there is a second implementation or a test needs one. Accept interfaces, return structs.
- Tests sit next to the code as _test.go files in the same package. Only black-box suites that run the whole binary (e2e, contract, load) get a separate test/ folder.
- Pass context.Context through every call that does I/O, log with log/slog in JSON, and never let a goroutine outlive the request or the server that started it.
At the top of the project
Open one in the explorer for the full story
- shop/
- .devcontainer/A Dev Container definition: Go, Docker and the tools preinstalled in a container.1 inside
- .vscode/Shared VS Code settings, recommended extensions and debug configurations.3 inside
- api/The API contract: the OpenAPI document that describes every endpoint.1 inside
- bin/Built binaries from make build (go build -o bin/api ./cmd/api).
- tmp/Where air writes the rebuilt binary and its build log during live reload.
- cmd/One folder per executable this module builds.1 inside
- internal/All the application code. Go forbids other modules from importing anything under internal/.5 inside
- migrations/SQL migrations for goose, embedded into the binary with go:embed. sqlc reads them as the schema.3 inside
- .air.tomlConfig for air, which rebuilds and restarts the server when a .go or .sql file changes.
- .editorconfigTabs for Go and Makefiles, spaces for YAML, final newline everywhere.
- .envLocal environment variables for development. Never committed.
- .env.exampleEvery environment variable the service reads, with safe example values. Committed.
- .gitignoreIgnores bin/, tmp/, .env, coverage files and editor folders.
- .golangci.ymlgolangci-lint v2 configuration: which linters and formatters run and with what settings.
- AGENTS.mdInstructions for AI coding agents: commands, layout rules, testing rules.
- CLAUDE.mdClaude Code's instructions file, often a single line importing AGENTS.md.
- compose.yamlLocal services: PostgreSQL now, an OpenTelemetry collector or Jaeger later.
- coverage.outThe coverage profile from go test -coverprofile; view it with go tool cover -html.
- go.modThe module definition: import path, Go version, dependencies and tools.
- go.sumChecksums of every dependency version, written by the go command. Commit it.
- lefthook.ymlGit hooks with lefthook: format and lint staged Go files before each commit.
- MakefileShort names for the commands you run every day: dev, test, lint, generate, migrate, build.
- README.mdWhat the service does and how to run, test, migrate and deploy it.
- sqlc.yamlsqlc config: the migrations as schema, each feature's queries.sql, and where to write the Go.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Go REST API.
- Roadmap· GoBackend development roadmapAPIs, databases, auth, deploys
- Roadmap· PostgreSQLSQL and databases roadmapQueries, design, indexes, transactions
- RoadmapDevOps and cloud roadmapLinux, Docker, Kubernetes, AWS
- Roadmap· Platform engineeringPlatform engineering and SRE roadmapSLOs, observability, Kubernetes platforms
- Cheat sheetBackend development cheat sheetAPIs, databases, auth, deploys.
- Cheat sheetSQL and databases cheat sheetQueries, design, indexes, transactions.
- Cheat sheetDevOps and cloud cheat sheetLinux, Docker, Kubernetes, AWS.
- FYP idea· IntermediateFeature Flag Service with Local Evaluation and Stale Flag CleanupA self-hostable feature flag service for small product teams, with SDKs that evaluate flags locally, streaming updates, consistent user bucketing and a scanner that finds stale flags in the codebase. An intermediate cloud and DevOps final year project that follows the OpenFeature standard.
- FYP idea· BeginnerStatus Page with Multi-Region Uptime Checks for Small SaaS TeamsA hosted status page and uptime monitor for small SaaS teams that probes each service from several regions and only raises an incident when probes agree. A beginner-friendly cloud and DevOps final year project covering HTTP checks, quorum-based alerting, incident updates and subscriber notifications.
See 10 moreShow fewer
- FYP idea· IntermediateMutation Testing Bot That Grades AI-Written Tests on Pull RequestsBuild a pull request bot that runs mutation testing only on the code a pull request changed, then comments with the mutants its tests failed to catch. AI tools write tests quickly, and many of them check nothing. This bot shows reviewers which new tests are decoration, in minutes rather than the hours a full mutation run takes.
- QuestionShould I learn Rust or Go in 2026?For most backend, cloud and DevOps work, learn Go first: it is small, quick to get productive in and common in cloud tooling. Choose Rust if you want systems programming, performance-critical code, embedded or you enjoy going deep on how memory works. Neither is a good first language if you cannot yet build software in another one.
- QuestionHow do I learn to read a large codebase when I can handle small projects but get lost in real ones?Nobody reads a large codebase from top to bottom. You follow one real path through it, such as a single request or button click, from entry point to database and back. Map what you find, ignore everything off that path for now, and repeat with a different path. Understanding builds in layers, and a first small change teaches more than a week of reading.
- QuestionDo I need Docker and Kubernetes as a junior developer?Docker, yes: learn the basics, because nearly every team uses containers and you will be expected to run the project locally and read a Dockerfile. Kubernetes, mostly no: understand what it does and a few core terms, but deep Kubernetes can wait until your job or a DevOps direction needs it.
- QuestionHow do I get better at debugging instead of immediately asking AI or another developer?Debugging is a method, not a talent. Reproduce the problem, read the actual error, form one hypothesis, test it, and narrow the search until the cause has nowhere left to hide. Give yourself a fixed window of honest effort before asking, and when you do ask AI or a person, bring your evidence so you still learn from the answer.
- Resource· GuideGo DocumentationThe official Go documentation hub: the interactive Tour of Go, getting started tutorials (modules, workspaces, a REST API with Gin, generics, fuzzing, database access with database/sql, a simple web app), Effective Go, the language specification, the memory model, and guides on the garbage collector, dependencies, coverage, profile guided optimisation and diagnostics. The best free route into Go for developers who already know another language.
- Resource· CourseA Tour of GoThe official interactive introduction to Go, maintained by the Go team: short pages that each explain one idea and let you edit and run code in the browser. It covers basics, flow control, structs, slices and maps, methods and interfaces, generics, and concurrency with goroutines and channels. It takes an afternoon or two if you already know another language, and is the natural first step before building anything in Go.
- Resource· GuideGo by ExampleAnnotated example programs for most everyday Go tasks, from slices, maps and structs to generics, iterators, goroutines, channels, worker pools, JSON, HTTP clients and servers, context and testing, each shown with its output. It works as a companion to A Tour of Go and as a quick lookup when you remember what you want but not the idiomatic way to write it.
- Resource· GuidePostgreSQL DocumentationThe official PostgreSQL manual for the current release: a tutorial, the full SQL language reference, every data type and function, server administration, and chapters on indexes, EXPLAIN and concurrency control. It is accurate, well written and the place to check any PostgreSQL behaviour before trusting a blog post.
- Resource· GuideDocker Docs: Get StartedDocker's official starting point: install Docker, follow a tutorial that builds, runs and shares a containerised application, then work through short concept pages on containers, images, registries, Compose, image layers, Dockerfiles, the build cache, multi-stage builds, ports and persistent data. It suits developers who have heard of containers but never used them, and it is current, free and more accurate than most tutorials copied from it.
Checked against 19 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Organizing a Go module (go.dev)
- Tutorial: Create a Go module
- go.mod file reference (including tool directives)
- Go workspaces tutorial
- Routing enhancements for Go 1.22 (ServeMux patterns)
- Structured logging with slog
- Go fuzzing
- govulncheck
- Go downloads and current versions
- pgx PostgreSQL driver
- sqlc: getting started with PostgreSQL
- goose migrations
- Testcontainers for Go: PostgreSQL module
- golangci-lint configuration
- air live reload
- OpenTelemetry Go getting started
- Distroless container images
- GoReleaser documentation
- k6 documentation
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Node.js API Best PracticesBuild Node.js REST APIs that hold up in production: structure, validation, error handling, security headers, rate limits, logging, testing and graceful shutdown.
- Observability Best PracticesKnow when production is hurting users and why: SLOs, golden signals, metric naming and cardinality, structured logs, OpenTelemetry traces and burn-rate alerts.
- PostgreSQL Best PracticesDesign, index, query and run PostgreSQL well: data types, constraints, EXPLAIN, zero-downtime migrations, pooling, transactions, backups and roles.
Checklists
See all- Database Migration ChecklistCheck a schema or data migration before it ships: expand and contract, lock behaviour, online indexes, batched backfills, rehearsal on real data, backups, rollback, deploy order and monitoring.
- Production Readiness ChecklistCheck a service before it takes real traffic: ownership, SLOs, capacity, timeouts and retries, alerts, rollout and rollback, backups, security and on-call.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com