Go Structure

Go Project Structure

Recommend and scaffold idiomatic Go project layouts. Matches structure to project type and size — start simple, grow when needed.

When to Use

• Initializing a new Go project or module
• User asks about project layout or directory organization
• Reviewing an existing project for structural anti-patterns
• Migrating from flat layout to a more structured one
• Setting up a monorepo with multiple services

Prerequisites

1. go.mod exists or will be created: The project must be a Go module.
2. Project type is known or inferrable: CLI tool, REST API, library, or monorepo.

Core Principle

Simplicity first, complexity when necessary. Do not impose structure upfront. Let it emerge from actual needs. A single main.go is a valid starting point.

Anti-Patterns to Flag

Workflow: Recommend Structure

Step 1: Detect Project Type

Analyze the codebase to classify:

Step 2: Recommend Layout

Based on project type and current size, recommend the appropriate layout from the reference patterns below.

Sizing rules:

• Small (<10 Go files): Flat layout, no directories needed
• Medium (10–30 Go files): Introduce internal/ with feature-based packages
• Large (30+ Go files or multiple binaries): Full cmd/ + internal/ structure

Step 3: Report Findings

For existing projects, present a table of findings:

Reference Layouts

Flat Layout (Small CLI / Tool)

For single-purpose tools and prototypes. Grow from here.

mytool/
├── main.go
├── go.mod
├── go.sum
└── README.md

CLI Application (Cobra/Viper)

mytool/
├── main.go
├── command/
│   ├── root.go
│   └── version.go
├── go.mod
└── README.md

REST API Service

Organize by feature/domain, not by technical layer.

myapi/
├── cmd/
│   └── api/
│       └── main.go          # Minimal: wire deps, load config, start
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── middleware/
│   │   └── auth.go
│   ├── user/                 # Feature package
│   │   ├── handler.go        # HTTP concerns only
│   │   ├── handler_test.go
│   │   ├── service.go        # Business logic
│   │   ├── service_test.go
│   │   ├── repository.go     # Data access interface + implementation
│   │   └── repository_test.go
│   └── product/
│       ├── handler.go
│       ├── service.go
│       └── repository.go
├── go.mod
└── README.md

Key rule: cmd/*/main.go is minimal — only dependency wiring, config loading, and server start. All logic lives in internal/.

Layer Responsibilities Inside a Feature Package

Each file in a feature package (internal/user/) has a clear, single responsibility:

Dependency flow: Handler → Service → Repository (interfaces). Dependencies always point inward.

Dependency Injection Wiring

Services receive their dependencies as interfaces via constructors — never create them internally:

// internal/user/repository.go — define the interface (port)
type Repository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, user *User) error
}

// internal/user/service.go — accept interface, not concrete type
type Service struct {
    repo Repository
}

func NewService(repo Repository) *Service {
    return &Service{repo: repo}
}

// cmd/api/main.go — wire everything together
func main() {
    db := connectDB()
    userRepo := user.NewPostgresRepository(db)
    userService := user.NewService(userRepo)
    userHandler := user.NewHandler(userService)
    // ... register routes
}

This keeps services testable (mock the interface) and swappable (change DB without touching business logic).

Hexagonal / DDD (Large Service)

For complex domain logic with clear port/adapter separation.

myservice/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── domain/
│   │   └── user/
│   │       ├── entity.go       # Domain models, value objects
│   │       ├── repository.go   # Port (interface)
│   │       └── service.go      # Domain services
│   ├── application/
│   │   └── user/
│   │       ├── create_user.go  # Use case
│   │       ├── get_user.go     # Use case
│   │       └── service.go      # Orchestration
│   └── adapter/
│       ├── http/
│       │   └── user_handler.go # Inbound adapter
│       ├── postgres/
│       │   └── user_repo.go    # Outbound adapter (implements port)
│       └── redis/
│           └── cache.go        # Outbound adapter
├── api/
│   └── openapi.yaml
├── go.mod
└── README.md

Dependency rule: Dependencies flow inward. Domain has zero external imports. Adapters implement domain interfaces.

Reusable Library

Only use pkg/ when code is intended for external import.

mylib/
├── mylib.go              # Public API at package root
├── mylib_test.go
├── internal/
│   └── parser/           # Private implementation
│       ├── parser.go
│       └── parser_test.go
├── go.mod
└── README.md

Monorepo (Multiple Services)

myproject/
├── cmd/
│   ├── api/
│   │   └── main.go
│   ├── worker/
│   │   └── main.go
│   └── scheduler/
│       └── main.go
├── internal/
│   ├── shared/            # Shared internal packages
│   ├── api/               # API-specific code
│   ├── worker/            # Worker-specific code
│   └── scheduler/         # Scheduler-specific code
├── go.mod                 # ONE module for the whole repo
└── README.md

Generator caveat: /gen-goreleaser and /gen-taskfiles emit a single-binary build by default. After scaffolding several cmd/* binaries, add one builds: entry per binary to .goreleaser.yml and extend the build task in Taskfile.yml, or those binaries never get built or released.

No go.work here. A workspace file exists to union several modules; a repo with a single go.mod does not need one, and the Go docs advise against committing go.work in the first place. Reach for a workspace only when the repo genuinely holds multiple go.mod files (each service its own module, no shared root module) — then go.work is a local-development convenience, typically git-ignored rather than checked in.

Note: internal/ is enforced, not conventional

internal/ is a rule the Go compiler applies, not a naming habit: a package under .../internal/x can only be imported by code rooted at ... — the directory containing internal — and this holds at any nesting depth. That is what makes it a real boundary rather than a hint, and why it is the right home for code you do not want external consumers importing. See https://pkg.go.dev/cmd/go#hdr-Internal_Directories.

Workflow: Scaffold Structure

When creating a new project or restructuring:

Step 1: Confirm Project Type

Ask user to confirm the detected or intended project type if ambiguous.

Step 2: Create Directories

Create only the directories needed for the chosen layout. Do not create empty placeholder directories.

Step 3: Create Minimal Files

For new projects, create:

• main.go with minimal bootstrap code (for binaries)
• Package files with package declaration and doc comment

Step 4: Validate

go build ./...
go vet ./...

Organizing by Feature vs Layer

Prefer feature-based organization:

# Good: organized by domain
internal/
├── user/
│   ├── handler.go
│   ├── service.go
│   └── repository.go
└── order/
    ├── handler.go
    ├── service.go
    └── repository.go

# Avoid: organized by layer
internal/
├── handlers/
│   ├── user.go
│   └── order.go
├── services/
│   ├── user.go
│   └── order.go
└── repositories/
    ├── user.go
    └── order.go

Feature-based packages are self-contained, reduce cross-package imports, and make it easy to understand a domain in one place.

Workflow: Review Layer Violations

When reviewing an existing project, check for these structural violations:

Step 1: Scan for Logic in Handlers

Grep handler files for signs of business logic leaking into the transport layer:

• Direct SQL queries (db.Query, db.Exec) in handler files
• Complex conditionals or domain validation beyond input parsing
• Direct calls to external services (HTTP clients, message queues)

Step 2: Scan for Transport in Services

Check service files for HTTP or framework imports that don't belong:

• net/http imports in service layer
• Framework-specific types (gin.Context, echo.Context) in service signatures
• JSON marshaling in service code

Step 3: Check Dependency Direction

Verify dependencies flow inward (handler → service → repository):

• Services must not import handler packages
• Repositories must not import service packages
• Domain types must not import infrastructure packages

Step 4: Report

Error Handling