Go Clean Architecture

Clean Architecture with Gin Web Framework

Features ⭐

• Clean Architecture written in Go
• Application backbone with Gin Web Framework
• Dependency injection using uber-go/fx
• Uses fully featured GORM

Linter setup

Need Python3 to setup linter in git pre-commit hook.

make lint-setup

---

Run application

• Setup environment variables

cp .env.example .env

• Update your database credentials environment variables in .env file
• Update STORAGE_BUCKET_NAME in .env with your AWS S3 bucket name.

Locally

• Run go run main.go app:serve to start the server.
• There are other commands available as well. You can run go run main.go -help to know about other commands available.

Using Docker

Ensure Docker is already installed in the machine.

• Start server using command docker-compose up -d or sudo docker-compose up -d if there are permission issues.

---

Folder Structure 📁

Folder Path	Description
/bootstrap	Contains modules required to start the application.
/console	Server commands; run go run main.go -help for all available commands.
/docker	Docker files required for docker-compose.
/docs	Contains project documentation.
/domain	Pure domain layer (no infrastructure dependencies): entities/value objects, domain services, validators, repository ports (interfaces), commands, domain events. Base types: logger.go (Logger interface), types.go (Validator, EventPublisher interfaces), uuid.go (UUID value object).
/domain/constants	Global application constants.
/domain/<name>	Domain feature folder (e.g., user): contains user.go (entity), service.go (use cases), repository.go (port/interface), command.go (commands), events.go (domain events), validator.go (business rules), api_error.go (domain errors).
/interfaces/http	HTTP adapters layer: Gin handlers, DTOs (with binding tags), and route wiring for each domain (e.g., interfaces/http/user).
/interfaces/http/<name>	HTTP adapter for a domain: controller.go (handlers), dto.go (HTTP DTOs), routes.go (route registration), module.go (FX module).
/pkg/infrastructure/persistence	Persistence layer: GORM models (e.g., UserPersistence) plus mappers/converters (e.g., user_mapper.go, uuid_converter.go) between domain entities and DB representations — source of truth for DB schema.
/pkg/infrastructure	Infrastructure providers: DB connection, router, event bus implementation, logger adapter, repository implementations (e.g., user_repository.go).
/pkg	Shared packages for errors, framework utilities, middlewares, responses, services, types, and utils.
/pkg/errorz	Defines custom error types and handlers for the application.
/pkg/framework	Core framework components like environment variable parsing, logger setup, etc.
/pkg/middlewares	HTTP request middlewares used in the application.
/pkg/responses	Standardized HTTP response structures and error handling.
/pkg/services	Shared clients/services for external systems (e.g., Cognito, S3, SES).
/pkg/types	Infrastructure-friendly primitive types (e.g., binary UUID for persistence).
/pkg/utils	Global utility and helper functions.
/hooks	Git hooks.
/migrations	Database migration files managed by Atlas.
/seeds	Seed data for database tables.
/tests	Application tests (unit, integration, etc.).
.env.example	sample environment variables
docker-compose.yml	docker compose file for service application via Docker
main.go	entry-point of the server
Makefile	stores frequently used commands; can be invoked using make command

---

🚀 Running Migrations

This project uses Atlas for database schema migrations. Atlas enables declarative, versioned, and diff-based schema changes.

---

🧰 Prerequisites

Make sure you have the following set up:

• Atlas CLI: Install Atlas by running:

  curl -sSf https://atlasgo.sh | sh

  For other installation methods or details, visit the official installation guide.

• .env file at the project root with the following environment variables:

  DB_USER=postgres
  DB_PASS=secret
  DB_NAME=exampledb
  DB_FORWARD_PORT=5432

---

📦 Available Migration Commands

Below are the supported make commands for managing database migrations:

Make Command	Description
make migrate-status	Show the current migration status
make migrate-diff	Generate a new migration by comparing persistence models (/pkg/infrastructure/persistence) to the current DB (gorm env)
make migrate-apply	Apply all pending migrations
make migrate-down	Roll back the most recent migration (gorm env)
make migrate-hash	Hash migration files for integrity checking

---

📚 For more on schema management and best practices, refer to the Atlas documentation.

Testing

The framework comes with unit and integration testing support out of the box. You can check examples written in tests directory.

To run the test just run:

go test ./... -v

For test coverage

go test ./... -v -coverprofile cover.txt -coverpkg=./...
go tool cover -html=cover.txt -o index.html

Test Coverage with Coveralls

This project uses Coveralls to track test coverage. Coverage reports are automatically uploaded to Coveralls on every push and pull request via GitHub Actions.

Setup:

1. Sign up for a free account at coveralls.io
2. Add your repository to Coveralls (it will be auto-created on first coverage upload)
3. Ensure the @coveralls user has write access to your repository for PR comments
4. Enable "LEAVE COMMENTS?" in Coveralls repo settings under "Pull Request Alerts"

Coverage Reports:

• Coverage reports are automatically generated and uploaded on every push/PR
• PR comments will show coverage changes
• View detailed coverage at: https://coveralls.io/github/YOUR_USERNAME/go_clean_architecture

Local Coverage:

# Generate coverage report
make test-coverage

# Generate HTML report
make test-coverage-html

# View coverage summary
make test-coverage-report

Update Dependencies

See UPDATING_DEPENDENCIES.md file for more information on how to update project dependencies.

Contribute 👩‍💻🧑‍💻

We are happy that you are looking to improve go clean architecture. Please check out the contributing guide

Even if you are not able to make contributions via code, please don't hesitate to file bugs or feature requests that needs to be implemented to solve your use case.

Authors