ULFlow Golang Starter Kit là nền tảng khởi tạo dự án backend cho Team ULFlow, được thiết kế để giúp khởi tạo các dự án trong thời gian ngắn, nhanh chóng mà vẫn đảm bảo các yếu tố cơ bản về kiến trúc, bảo mật và khả năng mở rộng.

Đặc điểm chính

Kiến trúc DDD (Domain Driven Development) - Customize cho phù hợp với nhu cầu dự án
U-Hierarchy - Mô hình tổ chức mã nguồn theo các cấp độ logic
Hot Reload - Phát triển nhanh với Air Tomb
Docker & Docker Compose - Containerization và orchestration
Gitea Full - CI/CD, Secret Manager, Registry Image
Postgres - Cơ sở dữ liệu quan hệ

Cài đặt

Yêu cầu hệ thống

Go 1.23
Docker và Docker Compose
Git

Khởi tạo dự án

# Clone repository
git clone [repo-url] my-project
cd my-project

# Cài đặt dependencies và công cụ
make init

# Cấu hình môi trường
cp .env.example .env
# Chỉnh sửa file .env theo nhu cầu

# Khởi động môi trường phát triển
make dev

Sử dụng Docker

Dự án cung cấp hai cấu hình Docker:

Môi trường phát triển (Local)

# Khởi động tất cả các dịch vụ với Docker Compose
make docker-compose-up

# Dừng tất cả các dịch vụ
make docker-compose-down

# Dọn dẹp container sau khi sử dụng
make docker-clean

Môi trường phát triển bao gồm:

API service với hot reload (Air Tomb)
PostgreSQL database
Gitea (Git Server, CI/CD, Registry)
Gitea Runner

Môi trường production

# Khởi động các dịch vụ cho production
make docker-compose-prod-up

# Dừng các dịch vụ production
make docker-compose-prod-down

Môi trường production bao gồm:

API service (optimized build)
PostgreSQL database
Nginx reverse proxy

Kiến trúc

Dự án sử dụng mô hình DDD (Domain Driven Development) với các thành phần chính:

Resource: Các Aggregate DDD
Transaction: Các Saga điều phối luồng nghiệp vụ phức tạp
Adapter: Xử lý giao tiếp với các hệ thống bên ngoài
Helper: Các thư viện, tiện ích dùng chung
UIUX: Lớp giao diện người dùng

Thành phần kiến trúc chi tiết (U-Hierarchy):

ubit: Đơn vị logic nhỏ nhất (hàm, type, hằng số)
ubrick: Tập hợp các ubit liên quan
ublock: Thành phần hoạt động độc lập tương đối
ubundle: Tính năng hoàn chỉnh cho người dùng

Cấu trúc thư mục

├── cmd/                # Entry points
├── pkg/                # Packages
│   ├── resource/       # Domain resources (DDD Aggregates)
│   ├── transaction/    # Business workflows
│   ├── adapter/        # External system interfaces
│   ├── helper/         # Utilities
│   └── uiux/           # User interfaces
├── config/             # Configuration
├── docs/               # Documentation
├── scripts/            # Helper scripts
└── test/               # Tests

Các lệnh Makefile

# Xem danh sách lệnh có sẵn
make help

# Khởi tạo dự án
make init

# Chạy môi trường phát triển với Air Tomb
make dev

# Chạy tests
make test

# Kiểm tra linting
make lint

# Build ứng dụng
make build

# Dọn dẹp tệp tạm
make clean

# Docker commands
make docker-build                # Build Docker image
make docker-run                  # Run container từ image
make docker-clean                # Dọn dẹp container
make docker-prune                # Dọn dẹp tất cả tài nguyên Docker không sử dụng
make docker-compose-up           # Khởi động môi trường phát triển
make docker-compose-down         # Dừng môi trường phát triển
make docker-compose-prod-up      # Khởi động môi trường production
make docker-compose-prod-down    # Dừng môi trường production

# Cấu hình Git
make setup-git

Quy trình phát triển

Dự án sử dụng Trunk-Based Development với các quy ước đặt tên nhánh:

feat: Tạo tính năng mới
fix: Sửa lỗi
docs: Thay đổi tài liệu
style: Thay đổi không ảnh hưởng đến logic
refactor: Refactor code
test: Thêm hoặc sửa test
chore: Thay đổi cấu hình hoặc các task không liên quan đến code

Xem thêm chi tiết trong docs/workflow.md.

Tài liệu

Đóng góp

Xem hướng dẫn đóng góp trong docs/workflow.md.

Giấy phép

Dự án này được phân phối dưới Giấy phép MIT. Xem file LICENSE để biết thêm thông tin.