GoApp: An Opinionated Go Application Guideline

Welcome to GoApp, an opinionated guideline for structuring a Go web application or service. This project is the culmination of over 9 years of experience building web services with Go, applying principles from Domain-Driven Design (DDD) and Clean Architecture.

This documentation will guide you through the project's structure, core concepts, and how to get it up and running. It is designed for developers who are competent in Go but new to this project's specific architecture.

goapp gopher

Core Philosophy

The primary goal of this structure is to create a maintainable, scalable, and testable application by enforcing a clear separation of concerns. The key principles are:

  • Domain-Driven Design: The business logic and domain models (users, usernotes) are at the core of the application, independent of infrastructure concerns like databases or web servers.
  • Clean Architecture: Dependencies flow inwards. The core business logic does not depend on outer layers like the UI or database. This is achieved through the use of interfaces and dependency inversion.
  • Explicit Dependencies: The application avoids global state and singletons, instead opting to inject dependencies explicitly. This makes the code easier to reason about and test.
  • Separation of Concerns: Each package has a single, well-defined responsibility. For example, cmd/server/http handles HTTP requests, internal/users contains user-related business logic, and internal/pkg/postgres manages database connections.

This guideline is particularly effective for Go 1.4+ due to the introduction of the special internal directory, which helps enforce package boundaries.

What's Inside this Documentation

  • Installation: Get the necessary tools and set up the project on your local machine.
  • Quick Start: The fastest way to get the application running using Docker Compose.
  • Usage Guide / Core Concepts: A deep dive into the architecture, directory structure, and design patterns used in GoApp.
  • API Reference: Detailed information on the available HTTP API endpoints.
  • Configuration: A complete reference for all required environment variables.
  • Deployment: Instructions for building and running the application with Docker.
  • Database: An overview of the database schema and triggers.
  • Observability: Learn how the application is instrumented with OpenTelemetry for tracing and metrics.
  • Go Client SDK: How to use the provided Go client library to interact with the API.
  • Contributing: Guidelines for running tests, understanding the CI process, and contributing to the project.
  • License: The project is licensed under the MIT License.