🧠 Applying Clean Architecture in Go — A Real-World Project Walkthrough
Clean Architecture is a popular approach for building scalable and maintainable backend systems. However, applying it effectively — especially in real-world projects — can feel overwhelming without concrete examples.
In this post, I’d like to share how I’ve applied Clean Architecture principles in a simple Go project called 🎟️ Ticket Reservation System. It’s a small concert ticket booking service, and while not exhaustive, it demonstrates one possible way to organize code using Clean Architecture. The project includes features like domain-driven modeling, repository interfaces, CLI tooling, Swagger documentation, and modular routing.
If you’re looking for a starting point to apply Clean Architecture in your own Go projects, this layout might offer a useful reference.
🧭 Why Clean Architecture?
Clean architecture promotes separation of concerns, testability, and clear boundaries between core business logic and external dependencies like databases, HTTP frameworks, or third-party APIs.
This means:
- Business logic doesn’t depend on frameworks.
- Infrastructure can change without rewriting your use cases.
- Handlers, services, and domain models remain isolated and testable.
🧱 Folder Structure Breakdown
Here’s the high-level layout of the ticket-reservation project:
ticket-reservation/
├── cmd/ # Application entry points and CLI commands
│ ├── root.go # Root command for the CLI
│ ├── serve_cmd.go # Command to start the server
│ ├── migrate_cmd.go # Command to run database migrations
│ ├── new_migration_cmd.go # Command to create new migration files
│ ├── print_config_cmd.go # Command to print the current configuration
│ └── generate_sql_builder.go # Command to generate SQL builder files
│ └── ... # Other commands
├── db/ # Database-related files
│ └── migrations/ # Database migration files
├── docs/ # Documentation files
│ ├── swagger.yaml # API documentation in Swagger format
│ └── ... # Other design and architecture documents
├── internal/ # Internal application code
│ ├── api/ # Delivery layer
│ │ └── http/ # HTTP API components
│ │ ├── handler/ # HTTP handlers by domain
│ │ │ ├── healthcheck/ # Health check handlers
│ │ │ └── ... # Other domain handlers
│ │ ├── middleware/ # HTTP middleware
│ │ └── route/ # HTTP route definitions
│ ├── config/ # Application configuration
│ ├── domain/ # Domain layer
│ │ ├── cache/ # Cache-related interfaces
│ │ ├── entity/ # Domain models (e.g., Concert, Reservation)
│ │ ├── errs/ # Domain-specific errors
│ │ └── repository/ # Repository interfaces
│ ├── infra/ # Infrastructure layer
│ │ ├── db/ # Database implementations
│ │ │ ├── connection.go # Database connection setup
│ │ │ ├── sql_execer.go # SQL execution interface
│ │ │ ├── transactor.go # Transaction management
│ │ │ ├── mocks/ # Mock implementations
│ │ │ ├── model_gen/ # Generated models from DB schema
│ │ │ └── repository/ # Repository implementations
│ │ │ ├── healthcheck/ # Health check repository
│ │ │ └── ... # Other repositories
│ │ └── redis/ # Redis implementations
│ │ ├── client.go # Redis client interface
│ │ ├── connection.go # Redis connection setup
│ │ ├── mocks/ # Mock implementations
│ │ └── repository/ # Repository implementations
│ │ ├── seat/ # Seat locking and cache implementations
│ │ └── ... # Other repositories
│ ├── server/ # Server setup and initialization
│ │ ├── dependency.go # Dependency injection
│ │ ├── middleware.go # Server middleware
│ │ └── server.go # HTTP server setup
│ ├── usecase/ # Application business logic
│ │ ├── healthcheck/ # Health check use case
│ │ └── ... # Other use cases
│ └── util/ # Utility functions
│ ├── httpresponse/ # HTTP response helpers
│ └── ... # Other utility functions
├── pkg/ # Shared helper packages
├── docker-compose.yaml # Docker Compose for local development
├── Dockerfile # Docker build definition
├── env.yaml # Environment variables configuration
├── go.mod # Go module definition
├── go.sum # Go module dependencies
├── main.go # Main application entry point
├── Makefile # Makefile for common tasks
└── README.md # Project documentation
Let’s walk through some highlights 👇
🧩 Clean Architecture in Action
1. Delivery Layer — internal/api/http/
This layer exposes the API using the Gin framework. It includes:
-
handler/: request parsing, validation, response formatting -
middleware/: application-level HTTP middleware such as authentication -
route/: HTTP route setup using injected dependencies
2. Usecase Layer — internal/usecase/
This layer contains pure application logic. It defines input/output structs and orchestrates repository calls or business rules. It does not depend on Gin, SQL, or any infra packages.
3. Domain Layer — internal/domain/
This is the heart of the application. It defines:
-
entity/: domain models like Concert, Reservation -
repository/: abstract interfaces for data access -
mocks/: auto-generated mocks for unit tests
No dependencies, no framework imports — just business terms and contracts.
4. Infrastructure Layer — internal/infra/
This layer implements database logic using go-jet and sqlx. It satisfies the interfaces defined in the domain layer.
🛠️ Built-in CLI Tools
This project comes with a built-in CLI (powered by Cobra) for common dev tasks. Run go run main.go --help to explore all commands.
Key commands:
-
serve: Start the HTTP server -
migrate: Run database migrations -
new-migration: Generate new migration files -
print-config: Print current effective config -
generate-db: Generate SQL builder and model files using go-jet
🔄 Project Status
This project is still a work-in-progress, and not all features are complete. However, it already provides a useful reference for:
- Structuring Go services with Clean Architecture
- Organizing code for testability and scalability
- Using tools like Cobra, Swagger, Jet, and MockGen effectively
If you’re starting a backend service in Go and want a clean, extensible foundation — feel free to fork or study this project. Feedback and contributions are welcome!
👉 GitHub Repo — ticket-reservation
Top comments (0)