Clean Code: Package Architecture, Dependency Flow, and Scalability [Part 4]

This is the fourth article in the "Clean Code in Go" series. Previous Parts: Clean Code: Functions and Error Handling in Go: From Chaos to Clarity [Part 1] Clean Code in Go (Part 2): Structs, Methods, and Composition Over Inheritance Clean Code: Interfaces in Go - Why Small Is Beautiful [Part 3] Clean Code: Functions and Error Handling in Go: From Chaos to Clarity [Part 1] Clean Code: Functions and Error Handling in Go: From Chaos to Clarity [Part 1] Clean Code in Go (Part 2): Structs, Methods, and Composition Over Inheritance Clean Code in Go (Part 2): Structs, Methods, and Composition Over Inheritance Clean Code: Interfaces in Go - Why Small Is Beautiful [Part 3] Clean Code: Interfaces in Go - Why Small Is Beautiful [Part 3] Why Import Cycles Hurt I've spent countless hours helping teams untangle circular dependencies in their Go projects. "Can't load package: import cycle not allowed" — if you've seen this error, you know how painful it is to refactor tangled dependencies. Go is merciless: no circular imports, period. And this isn't a bug, it's a feature that forces you to think about architecture.Common package organization mistakes I've seen:- Circular dependencies attempted: ~35% of large Go projects- Everything in one package: ~25% of small projects- Utils/helpers/common packages: ~60% of codebases- Wrong interface placement: ~70% of packages- Over-engineering with micropackages: ~30% of projects After 6 years working with Go and reviewing architecture in projects from startups to enterprise, I've seen projects with perfect package structure and projects where everything imports everything (spoiler: the latter don't live long). Today we'll explore how to organize packages so your project scales without pain and new developers understand the structure at first glance. Anatomy of a Good Package Package Name = Purpose // BAD: generic names say nothing package utils package helpers package common package shared package lib // GOOD: name describes purpose package auth // authentication and authorization package storage // storage operations package validator // data validation package mailer // email sending // BAD: generic names say nothing package utils package helpers package common package shared package lib // GOOD: name describes purpose package auth // authentication and authorization package storage // storage operations package validator // data validation package mailer // email sending Project Structure: Flat vs Nested BAD: Java-style deep nesting /src /main /java /com /company /project /controllers /services /repositories /models # GOOD: Go flat structure /cmd /api # API server entry point /worker # worker entry point /internal # private code /auth # authentication /storage # storage layer /transport # HTTP/gRPC handlers /pkg # public packages /logger # reusable /crypto # crypto utilities BAD: Java-style deep nesting /src /main /java /com /company /project /controllers /services /repositories /models # GOOD: Go flat structure /cmd /api # API server entry point /worker # worker entry point /internal # private code /auth # authentication /storage # storage layer /transport # HTTP/gRPC handlers /pkg # public packages /logger # reusable /crypto # crypto utilities Internal: Private Project Packages Go 1.4+ has a special `internal` directory whose code is accessible only to the parent package: // Structure: // myproject/ // cmd/api/main.go // internal/ // auth/auth.go // storage/storage.go // pkg/ // client/client.go // cmd/api/main.go - CAN import internal import "myproject/internal/auth" // pkg/client/client.go - CANNOT import internal import "myproject/internal/auth" // compilation error! // Another project - CANNOT import internal import "github.com/you/myproject/internal/auth" // compilation error! // Structure: // myproject/ // cmd/api/main.go // internal/ // auth/auth.go // storage/storage.go // pkg/ // client/client.go // cmd/api/main.go - CAN import internal import "myproject/internal/auth" // pkg/client/client.go - CANNOT import internal import "myproject/internal/auth" // compilation error! // Another project - CANNOT import internal import "github.com/you/myproject/internal/auth" // compilation error! Rule: internal for Business Logic // internal/user/service.go - business logic is hidden package user type Service struct { repo Repository mail Mailer } func NewService(repo Repository, mail Mailer) *Service { return &Service{repo: repo, mail: mail} } func (s *Service) Register(email, password string) (*User, error) { // validation if err := validateEmail(email); err != nil { return nil, fmt.Errorf("invalid email: %w", err) } // check existence if exists, _ := s.repo.EmailExists(email); exists { return nil, ErrEmailTaken } // create user user := &User{ Email: email, Password: hashPassword(password), } if err := s.repo.Save(user); err != nil { return nil, fmt.Errorf("save user: %w", err) } // send welcome email s.mail.SendWelcome(user.Email) return user, nil } // internal/user/service.go - business logic is hidden package user type Service struct { repo Repository mail Mailer } func NewService(repo Repository, mail Mailer) *Service { return &Service{repo: repo, mail: mail} } func (s *Service) Register(email, password string) (*User, error) { // validation if err := validateEmail(email); err != nil { return nil, fmt.Errorf("invalid email: %w", err) } // check existence if exists, _ := s.repo.EmailExists(email); exists { return nil, ErrEmailTaken } // create user user := &User{ Email: email, Password: hashPassword(password), } if err := s.repo.Save(user); err != nil { return nil, fmt.Errorf("save user: %w", err) } // send welcome email s.mail.SendWelcome(user.Email) return user, nil } Dependency Inversion: Interfaces on Consumer Side Rule: Define Interfaces Where You Use Them // BAD: interface in implementation package // storage/interface.go package storage type Storage interface { Save(key string, data []byte) error Load(key string) ([]byte, error) } // storage/redis.go type RedisStorage struct { client *redis.Client } func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ } func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ } // PROBLEM: service depends on storage // service/user.go package service import "myapp/storage" // dependency on concrete package! type UserService struct { store storage.Storage } // BAD: interface in implementation package // storage/interface.go package storage type Storage interface { Save(key string, data []byte) error Load(key string) ([]byte, error) } // storage/redis.go type RedisStorage struct { client *redis.Client } func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ } func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ } // PROBLEM: service depends on storage // service/user.go package service import "myapp/storage" // dependency on concrete package! type UserService struct { store storage.Storage } // GOOD: interface in usage package // service/user.go package service // Interface defined where it's used type Storage interface { Save(key string, data []byte) error Load(key string) ([]byte, error) } type UserService struct { store Storage // using local interface } // storage/redis.go package storage // RedisStorage automatically satisfies service.Storage type RedisStorage struct { client *redis.Client } func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ } func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ } // main.go package main import ( "myapp/service" "myapp/storage" ) func main() { store := storage.NewRedisStorage() svc := service.NewUserService(store) // storage satisfies service.Storage } // GOOD: interface in usage package // service/user.go package service // Interface defined where it's used type Storage interface { Save(key string, data []byte) error Load(key string) ([]byte, error) } type UserService struct { store Storage // using local interface } // storage/redis.go package storage // RedisStorage automatically satisfies service.Storage type RedisStorage struct { client *redis.Client } func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ } func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ } // main.go package main import ( "myapp/service" "myapp/storage" ) func main() { store := storage.NewRedisStorage() svc := service.NewUserService(store) // storage satisfies service.Storage } Import Graph: Wide and Flat Problem: Spaghetti Dependencies // BAD: everyone imports everyone // models imports utils // utils imports config // config imports models // CYCLE! // controllers imports services, models, utils // services imports repositories, models, utils // repositories imports models, database, utils // utils imports... everything // BAD: everyone imports everyone // models imports utils // utils imports config // config imports models // CYCLE! // controllers imports services, models, utils // services imports repositories, models, utils // repositories imports models, database, utils // utils imports... everything Solution: Unidirectional Dependencies // Application layers (top to bottom) // main // ↓ // transport (HTTP/gRPC handlers) // ↓ // service (business logic) // ↓ // repository (data access) // ↓ // models (data structures) // models/user.go - zero dependencies package models type User struct { ID string Email string Password string } // repository/user.go - depends only on models package repository import "myapp/models" type UserRepository interface { Find(id string) (*models.User, error) Save(user *models.User) error } // service/user.go - depends on models and defines interfaces package service import "myapp/models" type Repository interface { Find(id string) (*models.User, error) Save(user *models.User) error } type Service struct { repo Repository } // transport/http.go - depends on service and models package transport import ( "myapp/models" "myapp/service" ) type Handler struct { svc *service.Service } // Application layers (top to bottom) // main // ↓ // transport (HTTP/gRPC handlers) // ↓ // service (business logic) // ↓ // repository (data access) // ↓ // models (data structures) // models/user.go - zero dependencies package models type User struct { ID string Email string Password string } // repository/user.go - depends only on models package repository import "myapp/models" type UserRepository interface { Find(id string) (*models.User, error) Save(user *models.User) error } // service/user.go - depends on models and defines interfaces package service import "myapp/models" type Repository interface { Find(id string) (*models.User, error) Save(user *models.User) error } type Service struct { repo Repository } // transport/http.go - depends on service and models package transport import ( "myapp/models" "myapp/service" ) type Handler struct { svc *service.Service } Organization: By Feature vs By Layer By Layers (Traditional MVC) project/ /controllers user_controller.go post_controller.go comment_controller.go /services user_service.go post_service.go comment_service.go /repositories user_repository.go post_repository.go comment_repository.go /models user.go post.go comment.go # Problem: changing User requires edits in 4 places project/ /controllers user_controller.go post_controller.go comment_controller.go /services user_service.go post_service.go comment_service.go /repositories user_repository.go post_repository.go comment_repository.go /models user.go post.go comment.go # Problem: changing User requires edits in 4 places By Features (Domain-Driven) project/ /user handler.go # HTTP handlers service.go # business logic repository.go # database operations user.go # model /post handler.go service.go repository.go post.go /comment handler.go service.go repository.go comment.go # Advantage: all User logic in one place project/ /user handler.go # HTTP handlers service.go # business logic repository.go # database operations user.go # model /post handler.go service.go repository.go post.go /comment handler.go service.go repository.go comment.go # Advantage: all User logic in one place Hybrid Approach project/ /cmd /api main.go /internal /user # user feature service.go repository.go /post # post feature service.go repository.go /auth # auth feature jwt.go middleware.go /transport # shared transport layer /http server.go router.go /grpc server.go /storage # shared storage layer postgres.go redis.go /pkg /logger /validator project/ /cmd /api main.go /internal /user # user feature service.go repository.go /post # post feature service.go repository.go /auth # auth feature jwt.go middleware.go /transport # shared transport layer /http server.go router.go /grpc server.go /storage # shared storage layer postgres.go redis.go /pkg /logger /validator Dependency Management: go.mod Minimal Version Selection (MVS) // go.mod module github.com/yourname/project go 1.21 require ( github.com/gorilla/mux v1.8.0 github.com/lib/pq v1.10.0 github.com/redis/go-redis/v9 v9.0.0 ) // Use specific versions, not latest // BAD: // go get github.com/some/package@latest // GOOD: // go get github.com/some/package@v1.2.3 // go.mod module github.com/yourname/project go 1.21 require ( github.com/gorilla/mux v1.8.0 github.com/lib/pq v1.10.0 github.com/redis/go-redis/v9 v9.0.0 ) // Use specific versions, not latest // BAD: // go get github.com/some/package@latest // GOOD: // go get github.com/some/package@v1.2.3 Replace for Local Development // go.mod for local development replace github.com/yourname/shared => ../shared // For different environments replace github.com/company/internal-lib => ( github.com/company/internal-lib v1.0.0 // production ../internal-lib // development ) // go.mod for local development replace github.com/yourname/shared => ../shared // For different environments replace github.com/company/internal-lib => ( github.com/company/internal-lib v1.0.0 // production ../internal-lib // development ) Code Organization Patterns Pattern: Options in Separate File package/ server.go # main logic options.go # configuration options middleware.go # middleware errors.go # custom errors doc.go # package documentation package/ server.go # main logic options.go # configuration options middleware.go # middleware errors.go # custom errors doc.go # package documentation // options.go package server type Option func(*Server) func WithPort(port int) Option { return func(s *Server) { s.port = port } } func WithTimeout(timeout time.Duration) Option { return func(s *Server) { s.timeout = timeout } } // errors.go package server import "errors" var ( ErrServerStopped = errors.New("server stopped") ErrInvalidPort = errors.New("invalid port") ) // doc.go // Package server provides HTTP server implementation. // // Usage: // srv := server.New( // server.WithPort(8080), // server.WithTimeout(30*time.Second), // ) package server // options.go package server type Option func(*Server) func WithPort(port int) Option { return func(s *Server) { s.port = port } } func WithTimeout(timeout time.Duration) Option { return func(s *Server) { s.timeout = timeout } } // errors.go package server import "errors" var ( ErrServerStopped = errors.New("server stopped") ErrInvalidPort = errors.New("invalid port") ) // doc.go // Package server provides HTTP server implementation. // // Usage: // srv := server.New( // server.WithPort(8080), // server.WithTimeout(30*time.Second), // ) package server Pattern: Facade for Complex Packages // crypto/facade.go - simple API for complex package package crypto // Simple functions for 90% of use cases func Encrypt(data, password []byte) ([]byte, error) { return defaultCipher.Encrypt(data, password) } func Decrypt(data, password []byte) ([]byte, error) { return defaultCipher.Decrypt(data, password) } // For advanced cases - full access type Cipher struct { algorithm Algorithm mode Mode padding Padding } func NewCipher(opts ...Option) *Cipher { // configuration } // crypto/facade.go - simple API for complex package package crypto // Simple functions for 90% of use cases func Encrypt(data, password []byte) ([]byte, error) { return defaultCipher.Encrypt(data, password) } func Decrypt(data, password []byte) ([]byte, error) { return defaultCipher.Decrypt(data, password) } // For advanced cases - full access type Cipher struct { algorithm Algorithm mode Mode padding Padding } func NewCipher(opts ...Option) *Cipher { // configuration } Testing and Packages Test Packages for Black Box Testing // user.go package user type User struct { Name string age int // private field } // user_test.go - white box (access to private fields) package user func TestUserAge(t *testing.T) { u := User{age: 25} // access to private field // testing } // user_blackbox_test.go - black box package user_test // separate package! import ( "testing" "myapp/user" ) func TestUser(t *testing.T) { u := user.New("John") // only public API // testing } // user.go package user type User struct { Name string age int // private field } // user_test.go - white box (access to private fields) package user func TestUserAge(t *testing.T) { u := User{age: 25} // access to private field // testing } // user_blackbox_test.go - black box package user_test // separate package! import ( "testing" "myapp/user" ) func TestUser(t *testing.T) { u := user.New("John") // only public API // testing } Anti-patterns and How to Avoid Them Anti-pattern: Models Package for Everything // BAD: all models in one package package models type User struct {} type Post struct {} type Comment struct {} type Order struct {} type Payment struct {} // 100500 structs... // BETTER: group by domain package user type User struct {} package billing type Order struct {} type Payment struct {} // BAD: all models in one package package models type User struct {} type Post struct {} type Comment struct {} type Order struct {} type Payment struct {} // 100500 structs... // BETTER: group by domain package user type User struct {} package billing type Order struct {} type Payment struct {} Anti-pattern: Leaking Implementation Details // BAD: package exposes technology package mysql type MySQLUserRepository struct {} // BETTER: hide details package storage type UserRepository struct { db *sql.DB // details hidden inside } // BAD: package exposes technology package mysql type MySQLUserRepository struct {} // BETTER: hide details package storage type UserRepository struct { db *sql.DB // details hidden inside } Practical Tips Start with a monolith— don't split into micropackages immediately internal for all private code— protection from external dependencies Define interfaces at the consumer— not at implementation Group by features, not by file types One package = one responsibility Avoid circular dependencies through interfaces .Document packages in doc.go Start with a monolith— don't split into micropackages immediately Start with a monolith internal for all private code— protection from external dependencies internal for all private code Define interfaces at the consumer— not at implementation Define interfaces at the consumer Group by features, not by file types Group by features One package = one responsibility Avoid circular dependencies through interfaces Avoid circular dependencies .Document packages in doc.go Document packages Package Organization Checklist - Package has a clear, specific name- No circular imports- Private code in internal- Interfaces defined at the usage site- Import graph flows top to bottom- The package solves one problem- Has doc.go with examples- Tests in a separate test package Conclusion Proper package organization is the foundation of a scalable Go project. Flat import graph, clear responsibility boundaries, and Dependency Inversion through interfaces allow project growth without the pain of circular dependencies.In the final article of the series, we'll discuss concurrency and context — unique Go features that make the language perfect for modern distributed systems.What's your approach to package organization? Do you prefer organizing by feature or by layer? How do you handle the temptation to create a "utils" package? Let me know in the comments!