Go Clean Architecture

The project follows a Clean Architecture pattern. Key directories include:

• /bootstrap: Modules required to start the application.
• /console: Server commands (run go run main.go -help for details).
• /domain: Core business logic. Contains models, constants, and sub-folders for each domain (e.g., /domain/user) containing its controller, repository, routes, and services.
• /domain/models: GORM ORM models.
• /migrations: Database migration files managed by Atlas.
• /pkg: Shared packages:
  • /pkg/errorz: Custom error types and handlers.
  • /pkg/framework: Core components (env parsing, logger).
  • /pkg/infrastructure: Third-party connections (AWS, DB, router).
  • /pkg/middlewares: HTTP middlewares.
  • /pkg/responses: Standardized HTTP response structures.
  • /pkg/services: Shared clients for external services (S3, SES, etc.).
• /tests: Unit and integration tests.
• main.go: Application entry point.

1. Define Models: Add new model definitions to the domain/models folder using GORM tags.
2. Handle UUIDs: For UUID fields, use types.BinaryUUID. You can implement a BeforeCreate hook to automatically generate a new UUID if one isn't provided.
3. Generate Migrations: Use atlas go to diff your models against the current database. The project provides make commands to simplify this.
4. Apply Migrations: Run the generated migrations to update the database schema.

Note: The project uses MySQL; ensure model definitions are compatible with MySQL syntax.

package models

import (
	"clean-architecture/domain/constants"
	"clean-architecture/pkg/types"

	_ "ariga.io/atlas-provider-gorm/gormschema"

	"github.com/google/uuid"
	"gorm.io/gorm"
)

// User model
type User struct {
	gorm.Model
	UUID       types.BinaryUUID `json:"uuid" gorm:"index;notnull;unique"`
	CognitoUID *string          `json:"-" gorm:"index;size:50;unique"`

	FirstName   string `json:"first_name" gorm:"size:255"`
	LastName    string `json:"last_name" gorm:"size:255"`

	Email string             `json:"email" gorm:"notnull;index,unique;size:255"`
	Role  constants.UserRole `json:"role" gorm:"size:25" copier:"-"`
}

// BeforeCreate auto generate uuid before creating if it's not present already
func (u *User) BeforeCreate(tx *gorm.DB) error {
	if u.UUID.String() == (types.BinaryUUID{}).String() {
		id, err := uuid.NewRandom()
		u.UUID = types.BinaryUUID(id)
		return err
	}
	return nil
}

func (*User) TableName() string {
	return "users"
}

Routes are defined in a route.go file within the feature directory.

1. Define Route Struct: The Route struct should hold dependencies like framework.Logger, infrastructure.Router, and the feature's *Controller.
2. Initialize Route: Create a NewRoute constructor.
3. Implement Registration: Create a RegisterRoute function that uses the router's Group method (e.g., r.handler.Group("/api")) to associate paths with controller methods.
4. Automatic Registration: Use fx.Invoke(RegisterRoute) in your feature's fx.Module to ensure routes are registered automatically on application startup.

package user

import (
	"clean-architecture/pkg/framework"
	"clean-architecture/pkg/infrastructure"
)

// Route struct
type Route struct {
	logger     framework.Logger
	handler    infrastructure.Router
	controller *Controller
}

// NewRoute initializes a new Route instance
func NewRoute(
	logger framework.Logger,
	handler infrastructure.Router,
	controller *Controller,
) *Route {
	return &Route{
		handler:    handler,
		logger:     logger,
		controller: controller,
	}
}

// RegisterRoute sets up the routes for the feature
func RegisterRoute(r *Route) {
	r.logger.Info("Setting up routes")

	api := r.handler.Group("/api")

	api.POST("/user", r.controller.CreateUser)
	api.GET("/user/:id", r.controller.GetUserByID)
}

The errorz package allows you to define commonly used errors in a centralized manner. This ensures consistency in error messages and status codes across the application.

1. Define Common Errors

Create a package (e.g., errorz) and define APIError instances for frequent scenarios like unauthorized access or invalid input.

package errorz

import "net/http"

var (
    ErrUnauthorized = &APIError{
        StatusCode: http.StatusUnauthorized,
        Message:    "Unauthorized access",
    }

    ErrResourceNotFound = &APIError{
        StatusCode: http.StatusNotFound,
        Message:    "The requested resource was not found",
    }

    ErrInvalidInput = &APIError{
        StatusCode: http.StatusBadRequest,
        Message:    "Invalid input provided",
    }
)

2. Use Defined Errors in Handlers

Inject these errors into the responses.HandleError function within your handlers to return the standardized response.

import (
    "github.com/gin-gonic/gin"
    "clean-architecture/pkg/errorz"
    "clean-architecture/pkg/framework"
    "clean-architecture/pkg/responses"
    "net/http"
)

func ExampleHandler(c *gin.Context) {
    logger := framework.NewLogger()

    // Simulate an error condition
    if true { 
        responses.HandleError(logger, c, errorz.ErrInvalidInput)
        return
    }

    responses.SuccessJSON(c, http.StatusOK, "Operation successful")
}

To capture unhandled exceptions (panics) in your application, use a defer block with recover() to intercept the panic. Once recovered, use utils.CurrentSentryService.CaptureException(err) to send the error details to Sentry for debugging. This ensures that unexpected crashes are logged with context rather than silently failing or crashing the process without a trace.

Best Practices:

1. Always use defer and recover to handle panics.
2. Pass relevant context to Sentry to facilitate easier debugging.
3. Security: Ensure that sensitive user information or credentials are not included in the error context sent to Sentry.

import (
	"errors"
	"github.com/gin-gonic/gin"
	"clean-architecture/pkg/utils"
)

func ExampleUnhandledExceptionHandler(c *gin.Context) {
	defer func() {
		if r := recover(); r != nil {
			err := errors.New("Unhandled exception occurred")
			utils.CurrentSentryService.CaptureException(err)
			c.JSON(500, gin.H{"error": "An unexpected error occurred. Please try again later."})
		}
	}()

	// Simulate an unhandled exception
	panic("Simulated panic")
}

To implement a new feature, follow these architectural steps:

1. Create Feature Directory: Create a new directory under domain/<feature_name>/.
2. Implement Components: Create separate files for the following components within that directory:
   • controller.go
   • route.go
   • service.go
   • module.go
   • serializer.go (DTO layer)
   • repository.go
3. Define DTOs: Strictly separate the database structure (defined in models/) from the request/response structure. Use the DTO layer in your feature directory to convert between these two.
4. Dependency Injection: In domain/<feature_name>/module.go, set up the dependency injection using fx.Module. Use fx.Provide for your components and fx.Invoke for route registration.
5. Link Module: Ensure the new feature's module is linked to the main domain/module.go so it is included in the application's dependency injection tree.