golang-project-structure

Go Project Structure

Standard Layout

yourorg-order-service/
├── cmd/
│   └── server/
│       └── main.go              # Entry point, wire dependencies
├── internal/                     # Private to this module
│   ├── order/
│   │   ├── service.go           # Business logic
│   │   ├── service_test.go
│   │   ├── repository.go        # Interface + implementation
│   │   ├── handler.go           # HTTP handlers
│   │   ├── handler_test.go
│   │   └── model.go             # Domain types
│   ├── config/
│   │   └── config.go            # Configuration loading
│   └── middleware/
│       ├── auth.go
│       └── logging.go
├── pkg/                          # Public, reusable packages (use sparingly)
│   └── httputil/
│       └── response.go
├── migrations/
│   └── 001_create_orders.sql
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
└── README.md

Rules

• internal/ for all business logic — enforced by Go compiler
• cmd/ for entry points only — minimal code, just wiring
• pkg/ only for truly reusable cross-project code (most code goes in internal/)
• One package per domain concept (order, payment, auth)
• Package = directory, no nested packages unless necessary
• go.mod at repo root with go 1.22 minimum