Go Package & Module Architecture on Atharva Pandey

Lesson 7: go.work and Workspace Mode — Developing multiple modules without replace hacks

Tue, 25 Feb 2025 00:00:00 +0000

Before go.work existed, developing across multiple local Go modules was genuinely painful. You were working on a library in one directory and an application that depended on it in another. Every time you changed the library, you had to add a replace directive to the application’s go.mod, run your tests, and then remember — always remember — to remove the replace before committing. I have seen replace directives committed to production go.mod files more times than I would like to admit.

Lesson 6: Dependency Direction — Always depend inward, never outward

Thu, 02 Jan 2025 00:00:00 +0000

We fixed cycles in lesson 2. But removing cycles is a necessary condition for good architecture, not a sufficient one. You can have a perfectly cycle-free dependency graph where every arrow points in the wrong direction, and the result is still a system that is painful to test, extend, and reason about.

Dependency direction is about more than just “does A import B.” It is about which layer owns the core business rules and which layers are allowed to know about which other layers. Get this wrong and your domain logic ends up tangled with your database driver. Get it right and you can replace your entire HTTP layer, or swap Postgres for a different store, without changing a single line of business logic.

Lesson 5: Monolith vs Multi-Module — One go.mod or many? It depends.

Fri, 08 Nov 2024 00:00:00 +0000

When I first started structuring larger Go projects, I defaulted to what felt natural: one repository, one go.mod. It worked for a long time. Then I joined a project with four services in a single repo, each with different dependency requirements, and suddenly the single go.mod was pulling in every dependency of every service for every build. Tests for the email service were slow because the go test run was loading the ML inference library needed only by the recommendation service. That was when I started thinking seriously about module boundaries, not just package boundaries.

Lesson 4: Interface Placement — Define interfaces where they're used, not where they're implemented

Sat, 28 Sep 2024 00:00:00 +0000

This is the Go idiom that surprises people coming from Java or C# the most. In those languages, you define an interface in the same place as (or even before) the implementation, and consumers import the interface. Go’s approach is the exact opposite, and it takes a while to internalize why. Once it clicks, it changes how you think about dependencies fundamentally.

The rule is: define an interface in the package that needs it, not in the package that satisfies it. It sounds backwards. It is not. It is one of the most powerful design decisions the language enables.

Lesson 3: internal/ Usage Patterns — Compiler-enforced encapsulation

Sun, 18 Aug 2024 00:00:00 +0000

Go does not have access modifiers in the Java or Kotlin sense. There is no protected, no package-private, no friend classes. You get exactly two visibility levels: exported (capital letter) and unexported (lowercase letter). That simplicity is a feature. But it creates a gap: how do you share something across packages within your own module without accidentally exposing it to the outside world?

The answer is internal/. It is one of the most underused and underappreciated tools in Go’s package system, and it is enforced by the compiler itself.

Lesson 2: Avoiding Cyclic Dependencies — If packages import each other, your design is wrong

Fri, 12 Jul 2024 00:00:00 +0000

The Go compiler refuses to build a program with a cyclic import. It is not a warning. It is not a lint violation. It is a hard failure. I used to find this annoying when I was newer to the language. Now I consider it one of Go’s greatest gifts. The compiler is telling you something important: if package A needs package B and package B needs package A, you have not yet understood what the relationship between these two concepts really is.

Lesson 1: Package Boundaries — One package, one responsibility, zero excuses

Mon, 03 Jun 2024 00:00:00 +0000

I have refactored a lot of Go codebases — my own included. And the single most common structural mistake I see is the utils package. Or helpers. Or common. Or sometimes the worst offender of all: a package named after the entire application domain with fifty unrelated files sitting inside it. When I first started writing Go seriously, I made all of these mistakes. This lesson is about why package boundaries matter and how to get them right.