A comprehensive Clean Architecture template using Gin framework with GORM Gen and MySQL, designed to scale from simple applications to large enterprise systems with domain-specific adapter organization.
This template demonstrates enterprise-grade Clean Architecture with domain-specific adapter organization for infinite scalability:
┌─────────────────────────────────────────────────────────────┐
│ 🌐 Presentation Layer │
│ Domain-Specific Controllers • Route Handlers │
└─────────────────────────────────────────────────────────────┘
↕️
┌─────────────────────────────────────────────────────────────┐
│ 💼 Application Layer │
│ Domain-Specific Use Cases • Commands • Queries • CQRS │
└─────────────────────────────────────────────────────────────┘
↕️
┌─────────────────────────────────────────────────────────────┐
│ 🏛️ Domain Layer │
│ Bounded Contexts • Pure Entities • Business Logic │
└─────────────────────────────────────────────────────────────┘
↕️
┌─────────────────────────────────────────────────────────────┐
│ 🔧 Infrastructure Layer │
│ GORM Gen • Database • External APIs • Shared Concerns │
└─────────────────────────────────────────────────────────────┘
- 🎯 Team Ownership: Each team owns their domain's complete stack
- 📈 Infinite Scalability: Add domains without structural changes
- 🔄 Independent Evolution: Domains evolve without affecting others
- 👥 Parallel Development: 100+ developers can work simultaneously
- ⚡ Compile-time SQL validation - Catch errors before runtime
- 🛡️ Automatic SQL injection prevention - Security by design
- 🔍 Full IDE IntelliSense support - Better developer experience
- 🏗️ Clean Architecture compatible - Maintains separation of concerns
- Just: Modern command runner replacing Make
- Wire: Dependency injection code generation
- GORM Gen: Type-safe database query generation
- Docker: Containerized development environment
- Bounded Contexts: Clear domain boundaries with DDD
- CQRS: Command Query Responsibility Segregation
- Event-Driven Architecture: Ready for implementation
- Hexagonal Architecture: Port/Adapter pattern
clean-arch-gin/
├── cmd/
│ └── main.go # Application entry point
│
├── internal/
│ ├── domain/ # 🏛️ Pure Domain Layer (Bounded Contexts)
│ │ ├── user/ # 👥 User Bounded Context
│ │ │ ├── entities/user.go # User domain entity
│ │ │ ├── repositories/user_repository.go # Repository interface
│ │ │ └── usecases/user_usecase.go # Use case interface
│ │ ├── order/ # 📦 Order Bounded Context
│ │ │ ├── entities/order.go # Order domain entity
│ │ │ ├── repositories/order_repository.go # Repository interface
│ │ │ └── usecases/order_usecase.go # Use case interface
│ │ └── shared/ # 🤝 Shared Domain Concepts
│ │ └── entities/domain_error.go
│ │
│ ├── application/ # 💼 Application Layer (CQRS)
│ │ └── user/ # User application services
│ │ ├── commands/create_user_command.go
│ │ └── queries/get_user_query.go
│ │
│ ├── adapters/ # 🔌 Domain-Specific Adapters
│ │ ├── user/ # 👥 User Team Owns This
│ │ │ ├── controllers/user_controller.go # User HTTP controllers
│ │ │ ├── repositories/
│ │ │ │ ├── user_repository.go # Traditional GORM
│ │ │ │ └── user_repository_gen.go # 🆕 GORM Gen (type-safe)
│ │ │ └── usecases/user_usecase_impl.go # Use case implementation
│ │ ├── order/ # 📦 Order Team Owns This
│ │ │ ├── controllers/order_controller.go # Order HTTP controllers
│ │ │ ├── repositories/order_repository.go # Order repository impl
│ │ │ └── usecases/order_usecase_impl.go # Order use case impl
│ │ ├── shared/ # 🤝 Shared Infrastructure
│ │ │ └── models/user_model.go # GORM models (reusable)
│ │ └── middleware/auth_middleware.go # HTTP middleware
│ │
│ ├── modules/ # 📦 Feature Modules
│ │ ├── module.go # Module interface & registry
│ │ ├── user/user_module.go # User feature module
│ │ └── order/order_module.go # Order feature module
│ │
│ └── infrastructure/ # 🔧 Infrastructure Layer
│ ├── config/ # Configuration
│ ├── database/ # Database setup
│ │ ├── gen.go # 🆕 GORM Gen configuration
│ │ └── query/ # 🆕 Generated query code
│ └── router/user/ # Feature-specific routes
│
├── docs/ # 📚 Consolidated Documentation
│ ├── large-scale-architecture.md # Scaling strategies
│ ├── large-scale-adapter-structure.md # Domain-specific adapters
│ ├── consistent-domain-structure.md # Bounded context organization
│ ├── gorm-gen-integration.md # Type-safe database operations
│ ├── gorm-gen-comparison.md # Traditional vs GORM Gen
│ └── dependency_comparison.md # DI strategies
│
├── docker-compose.yaml # 🐳 Docker setup
├── Dockerfile # 🐳 Container image
├── justfile # 🤖 Modern command runner (Just)
├── LICENSE # 📄 MIT License
└── README.md # 📖 Project documentation
👥 User Team Owns:
├── internal/domain/user/ # Domain layer
├── internal/adapters/user/ # Adapter layer
├── internal/application/user/ # Application layer
└── internal/modules/user/ # Module layer
📦 Order Team Owns:
├── internal/domain/order/ # Domain layer
├── internal/adapters/order/ # Adapter layer
├── internal/application/order/ # Application layer
└── internal/modules/order/ # Module layer
🤝 Platform Team Owns:
├── internal/adapters/shared/ # Shared infrastructure
├── internal/infrastructure/ # Infrastructure layer
└── cmd/main.go # Application bootstrap
- Go 1.21+: Download Go
- Docker: Install Docker
- Just: Install Just (replaces Make)
# Clone and setup
git clone <repository>
cd clean-arch-gin
# Install dependencies (including GORM Gen)
just deps
# Setup environment
just init-env
# Edit .env with your database credentials# Start database with Docker
just docker-up
# Generate type-safe database code
just gen-query
# Run database migrations
just migrate
# Start development server
just dev# Create a user (using domain-specific adapters)
curl -X POST http://localhost:8080/api/v1/users \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","name":"John Doe","password":"password123"}'
# Get all users
curl http://localhost:8080/api/v1/users
# Test GORM Gen advanced features
curl http://localhost:8080/api/v1/users/domain/example.com # Users by domain
curl http://localhost:8080/api/v1/users/active # Active users only
curl "http://localhost:8080/api/v1/users/search?email=john&name=doe" # Dynamic search
# Check module health (shows domain-specific status)
curl http://localhost:8080/health| Team Size | Architecture Pattern | Adapter Organization | Recommended Structure |
|---|---|---|---|
| 1-5 devs | Simple Layer-First | Flat adapters | Traditional structure |
| 5-20 devs | Feature-Based | Domain-specific | Current implementation |
| 20-50 devs | Bounded Context + CQRS | Domain + technology specific | Advanced patterns |
| 50-100+ devs | Microservice Ready | Service boundaries | Extraction ready |
# Add Product domain following the pattern
internal/adapters/product/
├── controllers/product_controller.go # Product HTTP endpoints
├── repositories/
│ ├── product_repository.go # Traditional GORM
│ └── product_repository_gen.go # GORM Gen type-safe
└── usecases/product_usecase_impl.go # Business logic
# Update module registration in cmd/main.go
registry.Register(productModule.NewProductModule(db))- 🎯 Clear Domain Boundaries: Each team owns their complete stack
- 👥 Team Independence: 100+ developers work without conflicts
- 📦 Module Isolation: Changes don't cascade across domains
- 🚀 Microservice Ready: Easy extraction to separate services
- ⚡ Type-Safe Operations: GORM Gen prevents SQL errors
- 🛡️ Security by Design: Automatic SQL injection prevention
- 🔍 IDE Intelligence: Full autocompletion and navigation
- 📊 Performance Optimized: Generated, efficient queries
- 🔄 Parallel Development: Multiple teams work simultaneously
- 📈 Easy Onboarding: Clear structure and documentation
- 🎯 Domain Focus: Teams focus on business logic, not infrastructure
- 🔧 Consistent Patterns: Repeatable across all domains
# Run all tests across domains
just test
# Run tests with coverage
just test-cov
# Run tests in watch mode
just test-watch
# Run domain-specific tests
go test ./internal/adapters/user/...
go test ./internal/domain/user/...
# Run shared component tests
go test ./internal/adapters/shared/...
# Benchmark tests
just benchWhy Just? We use Just instead of Make for a better developer experience with simpler syntax and better error messages.
# 📋 Command Discovery
just # List all available commands
just help # Show detailed help with descriptions
# 📦 Development
just dev # Start development server
just dev-hot # Start with hot reload (requires air)
just quick-dev # Quick start (deps + gen + dev)
just dev-setup # Complete development setup
# 🏗️ Build
just build # Build the application
just build-linux # Build for Linux (cross-compile)
just prod-build # Production build with optimizations
# 🧪 Testing
just test # Run all tests across domains
just test-cov # Run tests with coverage report
just test-watch # Run tests in watch mode
just bench # Run benchmark tests
# ⚙️ Code Generation (Type-Safe Database)
just gen-query # Generate GORM Gen type-safe queries
just wire # Generate Wire dependency injection
just gen-all # Generate all code
# 🗃️ Database
just setup-db # Setup database for development
just migrate # Run database migrations
# 🐳 Docker
just docker-up # Start Docker services
just docker-down # Stop Docker services
just docker-build # Build Docker image
just docker-run # Run application in Docker
# 🧹 Utilities
just clean # Clean build artifacts and generated code
just clean-gen # Clean only generated code
just fmt # Format Go code
just lint # Run linter
just lint-fix # Run linter with auto-fix
just deps # Download and tidy dependencies
just deps-check # Check for outdated dependencies
# 🔧 Development Tools
just install-tools # Install required development tools
just status # Show project and tools status
just security # Run security audit
just reset # Full environment reset
# 📚 Documentation
just docs # Generate and serve documentation# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=user
DB_PASSWORD=password
DB_NAME=clean_arch_db
# Server
SERVER_PORT=8080
GIN_MODE=debug
# GORM Gen Configuration
GORM_GEN_OUTPUT_PATH=./internal/infrastructure/database/query
GORM_GEN_MODE=safe- Large-Scale Architecture - 📈 Complete scaling guide
- Large-Scale Adapter Structure - 🔌 Domain-specific adapters
- Consistent Domain Structure - 🏛️ Bounded context organization
- GORM Gen Integration - ⚡ Type-safe database operations
- GORM Gen Comparison - 📊 Traditional vs GORM Gen
- Dependency Comparison - 🔧 Manual vs Framework DI
- ✅ Bounded Context separation with clear domain boundaries
- ✅ Domain-specific adapter organization for team ownership
- ✅ Pure domain entities with no external dependencies
- ✅ Shared infrastructure concerns properly isolated
- ✅ Type-safe database operations with GORM Gen
- ✅ Comprehensive error handling with domain-specific errors
- ✅ Security-first approach with automatic SQL injection prevention
- ✅ Full test coverage across all domains
- ✅ Clear team ownership boundaries
- ✅ Independent domain evolution
- ✅ Parallel development support
- ✅ Conway's Law alignment (architecture matches team structure)
- ✅ Just for better command running experience
- ✅ Emojis and clear descriptions for better UX
- ✅ Advanced commands for security, benchmarking, and monitoring
- ✅ Tool status checking and dependency management
# Build production image
just docker-build
# Run with Docker Compose
docker-compose -f docker-compose.prod.yml up -d- ✅ Stateless application design
- ✅ Health check endpoints for each domain
- ✅ Graceful shutdown handling
- ✅ Environment-based configuration
- ✅ Horizontal scaling support
- Follow domain-specific organization patterns
- Use GORM Gen for all new database operations
- Use Just commands instead of direct go commands
- Write tests for new features with domain isolation
- Update documentation for architectural changes
- Use conventional commits for clear change tracking
- Ensure code coverage > 80% per domain
This project is licensed under the MIT License - see the LICENSE file for details.
- Clean Architecture: Robert C. Martin (Uncle Bob)
- Domain-Driven Design: Eric Evans
- Team Topologies: Matthew Skelton & Manuel Pais
- Building Microservices: Sam Newman
- Go Best Practices: Effective Go & Go Code Review Comments
- GORM Gen Documentation: Type-safe query generation
- Just Documentation: github.com/casey/just
This architecture successfully scales to:
- 🏢 Enterprise Teams: 100+ developers across 20+ domains
- 🚀 High Performance: Type-safe queries with GORM Gen optimization
- 📈 Rapid Growth: Add new domains in minutes, not days
- 🎯 Team Productivity: Clear ownership reduces coordination overhead
- 🔧 Developer Experience: Modern tooling with Just improves daily workflow
Built with ❤️ for infinitely scalable, type-safe, enterprise-grade Go applications 🚀