Go - The Ultimate Folder Structure

Go - The Ultimate Folder Structure

Organizing your Go (Golang) project's folder structure can help improve code readability, maintainability, and scalability. While there is no one-size-fits-all structure, here's a common folder structure for a Go project:

The Common Structure

project/
    ├── cmd/
    │   ├── your-app-name/
    │   │   ├── main.go         # Application entry point
    │   │   └── ...             # Other application-specific files
    │   └── another-app/
    │       ├── main.go         # Another application entry point
    │       └── ...
    ├── internal/                # Private application and package code
    │   ├── config/
    │   │   ├── config.go       # Configuration logic
    │   │   └── ...
    │   ├── database/
    │   │   ├── database.go     # Database setup and access
    │   │   └── ...
    │   └── ...
    ├── pkg/                     # Public, reusable packages
    │   ├── mypackage/
    │   │   ├── mypackage.go    # Public package code
    │   │   └── ...
    │   └── ...
    ├── api/                     # API-related code (e.g., REST or gRPC)
    │   ├── handler/
    │   │   ├── handler.go      # HTTP request handlers
    │   │   └── ...
    │   ├── middleware/
    │   │   ├── middleware.go  # Middleware for HTTP requests
    │   │   └── ...
    │   └── ...
    ├── web/                     # Front-end web application assets
    │   ├── static/
    │   │   ├── css/
    │   │   ├── js/
    │   │   └── ...
    │   └── templates/
    │       ├── index.html
    │       └── ...
    ├── scripts/                 # Build, deployment, and maintenance scripts
    │   ├── build.sh
    │   ├── deploy.sh
    │   └── ...
    ├── configs/                 # Configuration files for different environments
    │   ├── development.yaml
    │   ├── production.yaml
    │   └── ...
    ├── tests/                   # Unit and integration tests
    │   ├── unit/
    │   │   ├── ...
    │   └── integration/
    │       ├── ...
    ├── docs/                    # Project documentation
    ├── .gitignore               # Gitignore file
    ├── go.mod                   # Go module file
    ├── go.sum                   # Go module dependencies file
    └── README.md                # Project README

1. Flat Structure:

In smaller projects, you might opt for a flat structure where all your Go source files reside in the project root directory. This approach is simple but may become hard to manage as the project grows.

   project-root/
       ├── main.go
       ├── handler.go
       ├── config.go
       ├── database.go
       ├── ...
       ├── static/
       ├── templates/
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

2. Layered Structure:

Organize your code into layers, such as "web," "api," and "data." This approach helps separate concerns.

   project/
       ├── main.go
       ├── web/
       │   ├── handler.go
       │   ├── static/
       │   ├── templates/
       ├── api/
       │   ├── routes.go
       │   ├── middleware/
       ├── data/
       │   ├── database.go
       │   ├── repository.go
       ├── configs/
       ├── tests/
       ├── docs/

3. Domain-Driven Design (DDD):

In larger applications, consider structuring your project based on domain-driven design principles. Each domain has its own directory.

   project/
       ├── cmd/
       │   ├── app1/
       │   ├── app2/
       ├── internal/
       │   ├── auth/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── orders/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── ...
       ├── pkg/
       │   ├── utility/
       │   │   ├── ...
       │   ├── ...
       ├── api/
       │   ├── app1/
       │   │   ├── ...
       │   ├── app2/
       │   │   ├── ...
       ├── web/
       │   ├── app1/
       │   │   ├── ...
       │   ├── app2/
       │   │   ├── ...
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

4. Clean Architecture:

You can adopt a clean architecture approach, which emphasizes a separation of concerns between different layers of your application.

   project/
       ├── cmd/
       │   ├── your-app/
       │   │   ├── main.go
       ├── internal/
       │   ├── app/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── domain/
       │   │   ├── model.go
       │   │   ├── repository.go
       ├── pkg/
       │   ├── utility/
       │   │   ├── ...
       ├── api/
       │   ├── ...
       ├── web/
       │   ├── ...
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

5. Modular Structure:

Organize your code into separate modules, each with its own directory structure. This approach can be useful when developing multiple independent components within a single project.

   project/
       ├── module1/
       │   ├── cmd/
       │   ├── internal/
       │   ├── pkg/
       │   ├── api/
       │   ├── web/
       │   ├── scripts/
       │   ├── configs/
       │   ├── tests/
       │   └── docs/
       ├── module2/
       │   ├── ...

Use based on Your need

Gist

Comments

[Thaka]

I really appreciate how you clearly layout best practices—from flat layouts for small apps, through layered structures, all the way to domain-driven designs.

I recently applied these principles in a Go-based project: Golang-Sample-CRUD
It demonstrates:

• A layered architecture with cmd, internal, handlers, services, repositories, and models
• For internal folder handlers, services, repositories, and models for clean separation of concerns
• pkg folder containing utilities and shared code meant for reuse

Feel free to browse the structure—I think it’s a practical complement to the concepts you’ve shared here.

[Lucian I. Last]

Way too many folders imo

fosstodon.org/@lil5/11087110195484...

[Sensei]

In Your Opinion, You are right actually. and I have looked into you repo "The Clothing Loop" It's a fully fledge website and The design system that you choose make perfect sense. My in my case I Write tools and API Bots, basically Backend stuff. and I choose different folder structure based on requirment. But I agree with You..