go-clean-architecture

A modular, scalable Go codebase template built with Clean Architecture principles.

Go version: v1.25

🎯 What Is This?

This is a production-ready template for building Go applications with:

• ✅ Clean separation of concerns
• ✅ Framework-independent business logic
• ✅ Fully testable code
• ✅ Easy to extend and maintain

📖 Learn more about Clean Architecture

---

🚀 Two Ways to Get Started

Option 1: Use the Generator Tool (Recommended)

The easiest way to create a new project based on this architecture:

# Install the generator
go install github.com/dung13890/go-base-gen@latest

# Generate your new project
go-base-gen project --pkg github.com/yourusername/yourproject --path yourproject

# Setup and run
cd yourproject
go mod tidy
cp .env.example .env
go run cmd/migrate/main.go
make dev

👉 View go-base-gen documentation

Option 2: Clone This Repository

To explore or contribute to the template itself:

# Clone the repository
git clone https://github.com/dung13890/go-clean-architecture.git
cd go-clean-architecture
git submodule update --init --force --remote

# Build and run with Docker
docker compose build
cp .env.example .env
docker compose up -d

# Access the container
docker compose exec go-app sh

# Inside container: Setup database
make create_example_table.sql
go run cmd/migrate/main.go
go run cmd/seed/main.go

# Run the application
air -c cmd/app/.air.toml

---

📁 Project Structure

Architecture Flow

Handler → UseCase → Domain Interface (gateway, Repository, internal service)
            ↓               ↑
        Validation          └─ Adapters (Cache, DB, External)

Directory Layout

internal/
├── domain/              # 🎯 Core Business Layer (Layer 1)
│   ├── entity/          # Business entities (User, Role, etc.)
│   ├── repository/      # Repository interfaces
│   ├── gateway/         # Gateway interfaces
│   └── service/         # Pure domain business services
│
├── usecase/             # 📋 Application orchestrates workflow (Layer 2)
├── adapter/             # 🔌 External Integrations (Layer 3)
│   ├── repository/      # Data persistence
│   ├── gateway/         # External services (SMTP, Cache)
│   └── presenter/       # maps usecase output -> delivery
│
├── delivery/            # 🌐 User Interface Layer (Layer 4)
│   └── http/            # HTTP handlers & routes
└── infrastructure/      # ⚙️ Cross-cutting Concerns (Layer 4)
    └── registry/        #  🏗️ Dependency Injection

Layer Responsibilities

Layer	Responsibility	Example
Domain	Core business rules & interfaces	User entity, UserRepo
Usecase	Application workflows & orchestration	Register user flow
Adapter	External system integration	PostgreSQL, Redis, SMTP
Delivery	Request/response handling	HTTP handlers, CLI
Infrastructure	Technical concerns	Config, DB, Redis

---

✨ Built-in Features

• 🔐 JWT Authentication — Secure token-based auth
• 👤 User Management — Full CRUD operations
• 🎭 Role & Permissions — Access control system
• 📧 Email Service — SMTP integration
• 🚦 Rate Limiting — Redis-based throttling
• 🔄 Hot Reload — Development with Air
• 🧪 Testing Ready — Mock generation included

---

🛠️ Development Commands

# Code quality
make lint              # Run linter
make test              # Run unit tests
make go-gen            # Generate mocks

# Database
make create_example_table.sql  # Create migration file
go run cmd/migrate/main.go     # Run migrations
go run cmd/migrate/main.go down 1  # Rollback 1 step
go run cmd/seed/main.go        # Seed database

# Development
make dev               # Run with hot reload

---

🧪 API Examples

Register User

curl -X POST 'http://localhost:8080/api/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "password",
    "role_id": 1,
    "name": "John Doe"
  }'

Login

curl -X POST 'http://localhost:8080/api/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

---

📦 Tech Stack

Category	Technology
Framework	Echo
ORM	GORM
Configuration	Viper
Authentication	JWT
Hot Reload	Air
Database	PostgreSQL
Cache	Redis

---

🎓 Learn More

Adding New Features

Want to add a new domain (e.g., "Product")?

# Use the generator tool
go-base-gen domain --dn product --pkg github.com/yourusername/yourproject

# This creates:
# - internal/domain/entity/product.go
# - internal/domain/repository/product_repo.go
# - internal/usecase/product/
# - internal/adapter/repository/product_dao.go
# - internal/adapter/repository/product_repo.go
# - internal/delivery/http/product_handler.go

Architecture Principles

1. Dependency Rule: Inner layers don't know about outer layers
2. Interface Segregation: Use small, focused interfaces
3. Dependency Injection: Wire dependencies in registry
4. Testability: Mock external dependencies

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

☕ Support

If you find this project helpful:

---

📄 License

MIT License - see LICENSE for details.