Skip to content

Instantly share code, notes, and snippets.

@jenciso
Forked from ayoubzulfiqar/folder_structure.md
Created June 11, 2024 11:55
Show Gist options
  • Save jenciso/c85e4142e94010f1b29a3852ebc70156 to your computer and use it in GitHub Desktop.
Save jenciso/c85e4142e94010f1b29a3852ebc70156 to your computer and use it in GitHub Desktop.
The Folder Structure for Every Golang Project

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:

project-root/
    ├── 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

Here's a brief explanation of the key directories:

  • cmd/: This directory contains application-specific entry points (usually one per application or service). It's where you start your application.

  • internal/: This directory holds private application and package code. Code in this directory is not meant to be used by other projects. It's a way to enforce access control within your project.

  • pkg/: This directory contains public, reusable packages that can be used by other projects. Code in this directory is meant to be imported by external projects.

  • api/: This directory typically holds HTTP or RPC API-related code, including request handlers and middleware.

  • web/: If your project includes a front-end web application, this is where you'd put your assets (CSS, JavaScript, templates, etc.).

  • scripts/: Contains scripts for building, deploying, or maintaining the project.

  • configs/: Configuration files for different environments (e.g., development, production) reside here.

  • tests/: Holds unit and integration tests for your code.

  • docs/: Project documentation, such as design documents or API documentation.

This is a general guideline, and you can adjust it to match the specific needs of your project. Additionally, you can consider using a project layout tool like "golang-standards/project-layout" as a reference to structure your Go project.

Other Possible

The folder structure for a Go project can vary depending on the size and complexity of the project, as well as personal or team preferences. Here are some alternative folder structures for Go projects:

  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-root/
        ├── 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-root/
        ├── 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-root/
        ├── 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-root/
        ├── module1/
        │   ├── cmd/
        │   ├── internal/
        │   ├── pkg/
        │   ├── api/
        │   ├── web/
        │   ├── scripts/
        │   ├── configs/
        │   ├── tests/
        │   └── docs/
        ├── module2/
        │   ├── ...

Remember that the right folder structure depends on the specific needs of your project and your team's development practices. Choose a structure that helps maintain code organization, readability, and collaboration as your project evolves.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment