go-project-structure

Go Project Structure

Project layout and architecture patterns for Go applications. Covers service structure, CLI tools, libraries, and monorepos.

How It Works

1. Agent identifies the project type (service, CLI, library, monorepo)
2. Agent applies the appropriate layout template
3. Agent generates directory structure with standard files
4. Agent organizes existing code into the recommended structure

Layouts

1. Web Service / API (Most Common)

myservice/
├── cmd/
│   └── myservice/
│       └── main.go              # Entry point, wiring, startup
├── internal/
│   ├── config/
│   │   └── config.go            # Configuration loading
│   ├── domain/
│   │   ├── user.go              # Domain types & interfaces
│   │   └── order.go
│   ├── handler/
│   │   ├── user.go              # HTTP handlers
│   │   ├── order.go
│   │   └── middleware.go
│   ├── repository/
│   │   ├── postgres/
│   │   │   ├── user.go          # PostgreSQL implementation
│   │   │   └── migrations/
│   │   └── redis/
│   │       └── cache.go
│   ├── service/
│   │   ├── user.go              # Business logic
│   │   └── order.go
│   └── platform/
│       ├── database/
│       │   └── postgres.go      # Database connection setup
│       ├── logger/
│       │   └── logger.go
│       └── server/
│           └── server.go        # HTTP server setup
├── migrations/
│   ├── 001_create_users.up.sql
│   └── 001_create_users.down.sql
├── api/
│   └── openapi.yaml             # API specification
├── deployments/
│   ├── Dockerfile
│   └── docker-compose.yml
├── scripts/
│   ├── migrate.sh
│   └── seed.sh
├── go.mod
├── go.sum
├── Makefile
└── README.md

2. CLI Tool

mytool/
├── cmd/
│   └── mytool/
│       └── main.go
├── internal/
│   ├── cli/
│   │   ├── root.go              # Root command (cobra/urfave)
│   │   ├── init.go              # Subcommands
│   │   └── run.go
│   ├── config/
│   │   └── config.go
│   └── engine/
│       └── processor.go         # Core logic
├── pkg/                         # Public API (if any)
│   └── formatter/
│       └── formatter.go
├── testdata/
│   └── fixtures/
├── go.mod
├── go.sum
├── Makefile
└── README.md