zerohours / hex-arch-go

a TODO System with Hexagonal Architecture written in Go, test and uses cases examples, docker ready, heroku ready, basic CI integration, can use it how template for your projects

Clean Architecture / Hexagonal Architecture in Go

✔️ A TODO System with hexagonal architecture / clean architecture what you can use how template for your projects

✔️ Includes a simple CI.yml that you can use to get started with continuous integration in Github Actions

✔️ DB and Tests Implemented with CockRoachDB but you can run with another, for example MySQL

✔️ It have use cases and test examples for that use cases

✔️ Unit tests models and integration test models

✔️ API REST with Echo MicroFramework

✔️ Simple error logs system

✔️ Docker and Heroku ready

✅ Install

First clone the repo

git clone https://github.com/prinick96/hex-arch-go.git

⚠️ Now, the system need connect to a database, by default you can use Postgres or CockroachDB

• Just create a database
• Upload the schema on your DB

/db/schema.sql

• Change the enverioment variables located in .env.development

DB_ENGINE = "postgres or mysql"
DB_HOST = "host"
DB_PORT = 1234
DB_DATABASE = "db name"
DB_USERNAME = "user name"
DB_PASSWORD = "your secret password"

# For cockroach
DB_OPTIONS = "--cluster=cockroach-cluser-id"

# For postgres
DB_OPTIONS = "sslmode=disable timezone=UTC connect_timeout=5"

# For mysql
DB_OPTIONS = ""

✅ Run

If you want run in local, simply

go get
go run main.go

If you want run with Docker, simply

make docker-up 

If you want run with Heroku local, simply

# For Linux/MacOS
make heroku-run

# For Windows
heroku-run-win

⚠️ If you use Windows, you need change Procfile in the root of project for

# For windows use 
web: bin\hex-arch-go.exe
# web: bin/hex-arch-go

And now you can run Heroku local for Windows

✅ Test

For unit tests, simply

make unit-test

⚠️For integration tests, first need configure the .env.test vars adding the database test connection, after, simply

make integration-test

Or both of them

make test

🌳 Understanding the folder structure

.
├── /.github/workflows       # Github Actions!
├── /cmd                     # Start the application with server and database
├── /core                    # The CORE of hexagonal architecture: infrastructure, application and domain
│   ├── /application         # Handlers and the entry point of data
│   ├── /entities            # The entities what conform the domain
│   └── /infrastructure      # Gateways for the domain logic and Storage/Repository for the implementation of database
├── /db                      # Simply the schema of DB for you first run
├── /env                     # .env loader
├── /internal                # Elemental logic common for all the system
│   ├── /database            # Connection with database implemented
│   └── /helpers             # Reusable functions around the app, like a UUID generation
│       └── tests            # Unit tests for helpers 
└── /server                  # The server listener and endpoints of API REST