https://github.com/alfariiizi/vandor-backend
A production-ready Go service template implementing hexagonal architecture with Huma, Uber FX, Ent.go, and Cobra for building scalable, testable microservices.
https://github.com/alfariiizi/vandor-backend
clean-architecture cobra-cli dependency-injection docker echo-framework go golang gorm hexagonal-architecture microservices ports-and-adapters service-template uber-fx
Last synced: about 1 month ago
JSON representation
A production-ready Go service template implementing hexagonal architecture with Huma, Uber FX, Ent.go, and Cobra for building scalable, testable microservices.
- Host: GitHub
- URL: https://github.com/alfariiizi/vandor-backend
- Owner: alfariiizi
- Created: 2025-05-05T12:30:21.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-09-04T17:38:16.000Z (about 1 month ago)
- Last Synced: 2025-09-04T19:24:14.218Z (about 1 month ago)
- Topics: clean-architecture, cobra-cli, dependency-injection, docker, echo-framework, go, golang, gorm, hexagonal-architecture, microservices, ports-and-adapters, service-template, uber-fx
- Language: Go
- Homepage:
- Size: 12.7 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Vandor Backend
A production-ready Go service template implementing **Hexagonal Architecture** /
DDD with Huma, Uber FX, Ent (Ent.go), Cobra CLI and other tools to build
scalable, testable microservices. This README provides quickstart, development
workflow, code-generation hints, and deployment instructions
---
## Table of Contents
- [Highlights](#highlights)
- [Tech stack](#tech-stack)
- [Prerequisites](#prerequisites)
- [Quickstart (local with Docker)](#quickstart-local-with-docker)
- [Development workflow](#development-workflow)
- [Code generation & migrations](#code-generation--migrations)
- [Docker / Production build](#docker--production-build)
- [API docs](#api-docs)
- [Project structure](#project-structure)
- [Environment variables (example)](#environment-variables-example)
- [Testing](#testing)
- [Contributing](#contributing)
- [License & Maintainer](#license--maintainer)
- [Troubleshooting & FAQ](#troubleshooting--faq)
# Highlights
- Clean **Hexagonal / Ports & Adapters** layout separating domain,
infrastructure and delivery layers.
- DI via **Uber FX** for lifecycle management and testability.
- Type-safe DB access via **Ent.go** and migrations via **Atlas**.
- Auto-generated API docs using **Huma v2**
# Tech stack
- **Language:** Go (recommended 1.24.1)
- **DI / Lifecycle:** Uber FX
- **ORM / Codegen:** Ent.go + Atlas migrations
- **HTTP / API:** Chi router + Huma (OpenAPI)
- **DB / Driver:** PostgreSQL, pgx/v5
- **Cache / Broker:** Redis
- **CLI:** Cobra
- **Task runner:** Task (github.com/go-task/task)
- **Scheduler:** gocron
- **Auth:** JWX / bcrypt for token hashing & passwords
- **Containerization:** Docker (image build scripts included
# Prerequisites
- Go ≥ 1.24.1
- Docker & Docker Compose (or local Postgres + Redis)
- `task` (install with `go install github.com/go-task/task/v3/cmd/task@latest`)
- Optional: `atlas` & `ent` tooling if you will modify schemas and run
migrations locally
# Quickstart (local with Docker)
1. Clone the repo:
```bash
git clone https://github.com/alfariiizi/vandor-backend.git
cd vandor-backend
```
2. Copy or create config file:
```bash
cp ./config/config.yaml.example ./config/config.yaml
```
3. Start required services (example):
```bash
docker-compose up -d postgres redis
```
4. Download go modules:
```bash
go mod tidy
```
5. Generate repository code (Ent / generated repositories) if needed:
```bash
task gen:db-model
```
6. Run database migrations:
```bash
task migrate:up
```
7. Start development server (hot reload mode):
```bash
task run:dev
```
You should now be able to visit the API docs and OpenAPI JSON locally.
# Development workflow
- **Dev (hot reload):** `task run:dev` — watches files, regenerate code and
restarts.
- **Build:** `task build` then run the binary from `./bin/main`.
- **Run (production binary):**
```bash
./bin/main
```
- **Add new usecase/service:** use the provided generators:
- Generate a new usecase: `task create:usecase name=CreateUser`
- Generate a new service: `task create:service group=auth name=LoginUser`
# Code generation & migrations
- Ent schema changes → generate code:
```bash
# edit schemas under database/schema (or internal/core/model)
task gen:db-model
```
- Atlas / migrations:
```bash
task migrate:diff name="add users table"
task migrate:up
task migrate:status
```
(Adjust commands to match the installed atlas/ent tooling on your machine.)
# Docker / Production build
Build images using the included `build.sh` helper:
```bash
# application image
./build.sh app
# migration image
./build.sh migrate
# both
./build.sh all
```
Images referenced in docs:
- `alfariiizi/go-app:latest` (app server)
- `alfariiizi/go-migrate:latest` (migration runner
# API docs
When the server runs locally:
- **Swagger UI / docs:** `http://localhost:8080/docs`
- **OpenAPI spec:** `http://localhost:8080/openapi.json` The API documentation
is generated by Huma from your code and stays in sync with route definitions.
# Project structure (high level)
```
.
├── cmd/ # command-line entrypoints (app, generators)
├── config/
├── database/
│ ├── migrate/ # migrations
│ └── schema/ # ent schemas
├── docker/
├── docs/
├── internal/
│ ├── core/ # domain (models, repositories, services, usecases)
│ ├── delivery/ # http server, routes, middleware
│ ├── infrastructure/ # db, redis adapters
│ └── utils/
├── plugin/ # optional plugins (e.g., file management)
├── scripts/ # helper scripts (ent-tools.sh, atlas-tool.sh, watch.sh)
├── build.sh
├── taskfile.yaml
└── go.mod
```
(Trimmed for brevity; see repo for full tree.
# Testing
- Run unit tests:
```bash
task test
# or
go test ./... -v
```
- Coverage:
```bash
go test -cover ./...
```
# Contributing
1. Fork the repo and create feature branches in the pattern:
`feat/-short-desc` or `fix/-short-desc`.
2. Keep domain code in `internal/core`, delivery in `internal/delivery`, infra
adapters in `internal/infrastructure`.
3. Add tests for new features and run all generator. files.
4. Open a PR with a clear description and mention any migration steps.
# License & Maintainer
- **Maintainer:** GitHub — `alfariiizi` (this repo).
# Troubleshooting & FAQ
- **Migration failures:** Ensure the `atlas` or migration image has proper DB
credentials and that `task migrate:diff` was run from repo root.
- **Codegen not running:** Make sure Ent & Task are installed and the task
runner is in your PATH. Use `go install` for the task binary.