How would you structure a large Go monorepo or multi-service repository?

Question

Accepted Answer

platform/
├── cmd/                      // entry points — one per service
│   ├── api-gateway/
│   │   └── main.go
│   ├── user-service/
│   │   └── main.go
│   └── notification-service/
│       └── main.go
├── internal/                 // shared, not exported outside module
│   ├── auth/                 // shared auth logic
│   ├── database/             // shared DB utilities
│   └── observability/        // shared metrics/tracing
├── pkg/                      // exported, importable by other modules
│   └── apierror/             // shared error types
├── proto/                    // protobuf definitions
├── scripts/
├── deployments/
├── go.mod
└── go.sum

// Per-service go.mod (multi-module layout)
platform/
├── services/
│   ├── user/
│   │   ├── go.mod            // independent versioning
│   │   └── ...
│   └── payment/
│       ├── go.mod
│       └── ...
└── libs/
    └── common/
        └── go.mod Single module: simpler tooling, shared internal packages, atomic cross-service changes, but all services always built together Multi-module: independent versioning and deployment, cleaner boundaries, but more tooling complexity with workspace files Go workspaces (go.work): manage multi-module repos locally without replacing directives Use buf for managing protobuf definitions and gRPC code generation across services golangci-lint and Makefile or mage for consistent build/lint/test commands across services

How would you structure a large Go monorepo or multi-service repository?

Large Go repositories use either a multi-module layout with independent go.mod per service, or a single module with services under cmd/ and shared code under pkg/ and internal/.

Scenario Questions

Follow-up Questions