Skip to content

Project layout

.
├── api/
│   ├── api.go                  embeds the document
│   └── openapi.yaml            the HTTP contract
├── cmd/
│   ├── api/                    the server
│   └── migrate/                up, down, status
├── configs/
│   └── env.example             generated: every variable with its default
├── deployments/
│   ├── compose.yaml            API and PostgreSQL, plus an observability profile
│   ├── helm/go-rest-template/  Helm chart
│   └── observability/          Prometheus, Tempo and Grafana configuration
├── docs/                       this site
├── internal/
│   ├── app/                    composition root
│   │   ├── app.go              construction, run, shutdown
│   │   ├── routes.go           middleware and routes
│   │   └── apptest/            end-to-end test harness
│   ├── auth/                   authentication
│   ├── config/                 configuration
│   ├── platform/               shared infrastructure
│   │   ├── contract/
│   │   ├── database/
│   │   ├── errs/
│   │   ├── httpx/
│   │   ├── logging/
│   │   ├── middleware/
│   │   ├── tracing/
│   │   └── version/
│   ├── tasks/                  example feature
│   └── users/                  users feature
├── migrations/
│   ├── migrations.go           embeds the SQL files
│   ├── postgres/
│   └── sqlite/
├── scripts/
│   └── test-init.sh            generates and tests projects
├── tools/
│   ├── init/                   turns the template into your project
│   └── scaffold/               generates a resource
├── Dockerfile
├── Makefile
└── mkdocs.yml

Conventions

internal/ holds all application code. Nothing is meant to be imported by other modules, so there is no pkg/ directory.

One package per feature, four files per package. task.go (model and inputs), service.go, repository.go and handler.go. The example and every generated resource also carry their end-to-end test in api_test.go; the tests of users and auth live in internal/app, because every other test depends on them.

platform is for code with no business meaning. If a package would still make sense in a different service, it belongs there. If it mentions users or tasks, it does not.

Embedded, not shipped next to the binary. The OpenAPI document and the migrations are compiled in. The container image contains two binaries and nothing else.

Generated files are committed and checked. configs/env.example and docs/reference/configuration.md are produced by make generate from the declarations in internal/config/config.go. A test fails when they are out of date.

Files at the root

File Purpose
Makefile Developer commands. make help lists them. See Make targets.
Dockerfile Multi-stage build of a static, distroless image.
.golangci.yml Linter configuration.
lefthook.yml Optional git hooks: formatting, vet and lint before a commit, Conventional Commits on the message.
.goreleaser.yaml Release binaries and their SBOM.
release-please-config.json, .release-please-manifest.json Versioning and changelog automation.
.editorconfig Indentation and line endings.

What the init tool removes

A generated project has no docs/, overrides/, mkdocs.yml, scripts/ or tools/init, and loses whatever belongs to the options that were turned off. See Create your project.