GoIntentional Code

Intentional Code with Go

You don't have to be a software architect to find yourself architecting software.

Most developers stumble into architecture. One day you're writing a script, the next you're responsible for a system with users and consequences. Then the decisions start to pile up: where should this logic live, how should these parts talk to each other, and why did a small change suddenly become a whole afternoon?

This is a focused reference to the patterns and principles that help you answer those questions in idiomatic Go. If you're not sure where to start, read the Design Philosophy section first. It gives the rest of the catalog some shape. If you already know the pain but not the pattern name, the tags will get you there faster.

Featured

Hexagonal Architecture

Place business logic at the centre, define ports (interfaces) for everything the application drives or is driven by, and provide adapters that connect the outside world to those ports.

Define an interface for creating an object, but let the calling code decide which concrete type to instantiate via constructor functions returning an interface.

Provide a simple, unified interface to a complex subsystem, shielding clients from internal complexity.

Pattern catalog

Design Philosophy

Design Philosophy

Software architecture isn't a set of rules to follow. It's a way of thinking about code.

SOLID Principles

The five SOLID principles, reinterpreted for Go's implicit-interface, composition-first model.

Test-Driven Development

The red/green/refactor loop in Go — and how design pressure naturally produces patterns.

Creational Patterns

Abstract Factory

Provide an interface whose methods each return related product interfaces, so families of related objects can be created without specifying their concrete types.

Construct complex objects step by step, separating construction from representation so the same process can create different results.

Define an interface for creating an object, but let the calling code decide which concrete type to instantiate via constructor functions returning an interface.

Create new objects by cloning an existing instance, avoiding the cost of building from scratch and decoupling code from concrete types.

Ensure a type has only one instance and provide a global point of access to it.

Structural Patterns

Convert the interface of an existing type into another interface clients expect, letting incompatible types work together.

Split a large type into two separate hierarchies — abstraction and implementation — that can vary independently.

Compose objects into tree structures so clients can treat individual objects and compositions uniformly through a single interface.

Attach additional behavior to an object dynamically by wrapping it in another object that implements the same interface.

Provide a simple, unified interface to a complex subsystem, shielding clients from internal complexity.

Minimize memory usage by sharing as much data as possible between similar objects, separating intrinsic from extrinsic state.

Provide a surrogate or placeholder for another object to control access, add lazy initialization, logging, or caching.

Behavioral Patterns

Chain of Responsibility

Pass a request along a chain of handlers, where each handler decides whether to process it or pass it to the next handler.

Encapsulate a request as an object (or function value), letting you parameterize clients, queue requests, and support undo operations.

Provide a way to access elements of a collection sequentially without exposing its underlying representation.

Define an object that encapsulates how a set of objects interact, promoting loose coupling by keeping objects from referring to each other directly.

Capture and externalize an object's internal state so it can be restored later, without violating encapsulation.

Define a one-to-many dependency between objects so that when one changes state, all dependents are notified automatically.

Let an object alter its behavior when its internal state changes, appearing to change its type.

Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.

Template Method

Define the skeleton of an algorithm in a base operation, deferring some steps to subclasses — but in Go, use composition and injected hook functions instead.

Separate an algorithm from the object structure it operates on by using double dispatch.

Architectural Patterns

Circuit Breaker

Prevent cascading failures by wrapping remote calls in a state machine that fails fast when a downstream service is unhealthy and probes for recovery.

Clean Architecture

Structure code in concentric rings, Entities, Use Cases, Interface Adapters, Frameworks, enforcing a strict inward dependency rule so the domain never imports infrastructure.

Separate the model used for writing state (Commands) from the model used for reading it (Queries), allowing each side to be optimised independently.

Domain-Driven Design

Model software around the business domain using Entities, Value Objects, Aggregates, Repositories, and Domain Events, keeping the ubiquitous language consistent across code and conversation.

Event-Driven Architecture

Decouple services by having producers emit domain events and consumers react to them asynchronously, without either knowing about the other.

Hexagonal Architecture

Place business logic at the centre, define ports (interfaces) for everything the application drives or is driven by, and provide adapters that connect the outside world to those ports.

Layered Architecture

Organise code into horizontal layers, Handler, Service, Repository, Infrastructure, where each layer depends only on the layer below it.

Isolate domain logic from data persistence by defining an interface for storage operations and providing concrete implementations for each backend.