Saved Content

Your bookmarked patterns and highlighted notes.
Saved Pages

No saved content yet.
Click "Save for later" on any page to save it here.
Generate CLAUDE.md

Drop this file in your Go project root. Claude Code will use it as context when helping with architecture decisions.
# Go Architecture — Claude Reference

> Generated from Intentional Code · https://intentionalcode.com
> Drop this file in your project root as `CLAUDE.md`.
> Claude Code will use it as context when helping with architecture decisions.

## Design principles

Apply these principles using Go's idioms:
- **Accept interfaces, return structs.** High-level code depends on small interfaces; infrastructure satisfies them.
- **Keep interfaces to one or two methods.** Go's implicit interface satisfaction makes this nearly free — a single-method interface is the norm, not the exception.
- **Prefer composition over inheritance.** Go has no inheritance. Embed types or accept interfaces to build behavior from small pieces.
- **Write a failing test before writing the function.** Go's implicit interfaces let you use simple fake structs instead of mocking frameworks — a `type FakeRepo struct` with the right methods is all you need.
- **Errors are values.** Return them, wrap them with `fmt.Errorf("context: %w", err)`, and handle them at the right level. Panic only for programmer errors, never for runtime conditions.

## Pattern reference

When reviewing or writing code, recognise these signals and suggest the appropriate pattern:

### Abstract Factory (creational)
**Signal:** Provide an interface whose methods each return related product interfaces, so families of related objects can be created without specifying their concrete types.
**Go approach:** An interface whose methods each return related product interfaces; one struct per family.
**See also:** factory-method, builder

### Builder (creational)
**Signal:** Construct complex objects step by step, separating construction from representation so the same process can create different results.
**Go approach:** Prefer the functional options pattern (func WithTimeout(d) Option); also show classic chained builder.
**See also:** factory-method, abstract-factory

### Factory Method (creational)
**Signal:** Define an interface for creating an object, but let the calling code decide which concrete type to instantiate via constructor functions returning an interface.
**Go approach:** Constructor functions returning an interface; selection via map of constructors, not a class hierarchy.
**See also:** abstract-factory, builder, prototype

### Prototype (creational)
**Signal:** Create new objects by cloning an existing instance, avoiding the cost of building from scratch and decoupling code from concrete types.
**Go approach:** A Clone() method; be explicit about shallow vs deep copy with pointers, slices, maps.
**See also:** factory-method, memento

### Singleton (creational)
**Signal:** Ensure a type has only one instance and provide a global point of access to it.
**Go approach:** Package-level value + sync.Once; then argue against it (testability) and show dependency injection.
**See also:** factory-method, builder

### Adapter (structural)
**Signal:** Convert the interface of an existing type into another interface clients expect, letting incompatible types work together.
**Go approach:** A wrapper struct that satisfies the target interface by delegating to the adaptee.
**See also:** bridge, decorator, facade, proxy

### Bridge (structural)
**Signal:** Split a large type into two separate hierarchies — abstraction and implementation — that can vary independently.
**Go approach:** Split abstraction and implementation into two interfaces composed by struct fields.
**See also:** adapter, strategy

### Composite (structural)
**Signal:** Compose objects into tree structures so clients can treat individual objects and compositions uniformly through a single interface.
**Go approach:** One interface implemented by both leaf and composite types; tree of nodes; recursion.
**See also:** decorator, iterator, visitor

### Decorator (structural)
**Signal:** Attach additional behavior to an object dynamically by wrapping it in another object that implements the same interface.
**Go approach:** Wrap an interface to add behavior; canonical Go example: http.Handler / RoundTripper middleware.
**See also:** adapter, composite, proxy, chain-of-responsibility

### Facade (structural)
**Signal:** Provide a simple, unified interface to a complex subsystem, shielding clients from internal complexity.
**Go approach:** A struct exposing a small API over several subsystem packages.
**See also:** adapter, mediator

### Flyweight (structural)
**Signal:** Minimize memory usage by sharing as much data as possible between similar objects, separating intrinsic from extrinsic state.
**Go approach:** Share immutable intrinsic state via interning and lookup map; mention sync.Pool as a related but different reuse tool.
**See also:** composite, singleton

### Proxy (structural)
**Signal:** Provide a surrogate or placeholder for another object to control access, add lazy initialization, logging, or caching.
**Go approach:** Same-interface wrapper for lazy init, access control, logging, caching; contrast with Decorator.
**See also:** adapter, decorator

### Chain of Responsibility (behavioral)
**Signal:** Pass a request along a chain of handlers, where each handler decides whether to process it or pass it to the next handler.
**Go approach:** A slice or linked list of handlers, or composed middleware that may pass to next.
**See also:** decorator, command

### Command (behavioral)
**Signal:** Encapsulate a request as an object (or function value), letting you parameterize clients, queue requests, and support undo operations.
**Go approach:** A function value, or a struct with Execute(); queue/undo via a stack of commands.
**See also:** chain-of-responsibility, memento, strategy

### Iterator (behavioral)
**Signal:** Provide a way to access elements of a collection sequentially without exposing its underlying representation.
**Go approach:** Go 1.23 range-over-func (iter.Seq[T]) as primary form; also channel-based and explicit iterator struct.
**See also:** composite, visitor

### Mediator (behavioral)
**Signal:** Define an object that encapsulates how a set of objects interact, promoting loose coupling by keeping objects from referring to each other directly.
**Go approach:** A coordinator struct that colleagues call instead of each other.
**See also:** facade, observer

### Memento (behavioral)
**Signal:** Capture and externalize an object's internal state so it can be restored later, without violating encapsulation.
**Go approach:** Capture/restore via an opaque type with unexported fields; originator owns save/restore.
**See also:** command, prototype

### Observer (behavioral)
**Signal:** Define a one-to-many dependency between objects so that when one changes state, all dependents are notified automatically.
**Go approach:** Subscriber interface slice or channels; cover unsubscribe and goroutine/lifecycle concerns.
**See also:** mediator, command

### State (behavioral)
**Signal:** Let an object alter its behavior when its internal state changes, appearing to change its type.
**Go approach:** A State interface; context holds current state and delegates, transitions return the next state.
**See also:** strategy, command

### Strategy (behavioral)
**Signal:** Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
**Go approach:** A function type is the idiomatic form; show interface-based too and say when each fits.
**See also:** bridge, state, template-method, command

### Template Method (behavioral)
**Signal:** 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.
**Go approach:** Fights Go (no inheritance); implement via composition + injected hook funcs or an interface.
**See also:** strategy, factory-method

### Visitor (behavioral)
**Signal:** Separate an algorithm from the object structure it operates on by using double dispatch.
**Go approach:** Double dispatch via Accept(Visitor); be honest about verbosity and present type-switch as the Go alternative.
**See also:** composite, iterator

### Circuit Breaker (architectural)
**Signal:** Prevent cascading failures by wrapping remote calls in a state machine that fails fast when a downstream service is unhealthy and probes for recovery.
**Go approach:** A CircuitBreaker struct with Closed/Open/HalfOpen states; wraps any func() error call; uses sync/atomic or a mutex for thread-safe state transitions.
**See also:** proxy, decorator

### Clean Architecture (architectural)
**Signal:** Structure code in concentric rings, Entities, Use Cases, Interface Adapters, Frameworks, enforcing a strict inward dependency rule so the domain never imports infrastructure.
**Go approach:** Domain types and use-case interfaces in an inner package; HTTP handlers and DB adapters in outer packages that import inward, never the reverse.
**See also:** hexagonal, layered, repository, domain-driven-design

### CQRS (architectural)
**Signal:** Separate the model used for writing state (Commands) from the model used for reading it (Queries), allowing each side to be optimised independently.
**Go approach:** Command handler functions that accept a command struct and return an error; query functions that accept filter params and return read-model DTOs.
**See also:** event-driven, domain-driven-design, repository

### Domain-Driven Design (architectural)
**Signal:** Model software around the business domain using Entities, Value Objects, Aggregates, Repositories, and Domain Events, keeping the ubiquitous language consistent across code and conversation.
**Go approach:** Structs for entities and value objects; aggregate roots as the only entry point for mutations; domain events as plain structs dispatched after state changes.
**See also:** repository, event-driven, clean-architecture, cqrs

### Event-Driven Architecture (architectural)
**Signal:** Decouple services by having producers emit domain events and consumers react to them asynchronously, without either knowing about the other.
**Go approach:** In-process: Go channels or a simple event bus struct. Cross-service: publish to Kafka/NATS/SQS; consumers implement an idempotent handler interface.
**See also:** cqrs, domain-driven-design, observer

### Hexagonal Architecture (architectural)
**Signal:** 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.
**Go approach:** Driving ports as use-case interfaces called by HTTP handlers; driven ports as repository and notifier interfaces implemented by DB and queue adapters.
**See also:** clean-architecture, layered, repository

### Layered Architecture (architectural)
**Signal:** Organise code into horizontal layers, Handler, Service, Repository, Infrastructure, where each layer depends only on the layer below it.
**Go approach:** Separate packages per layer; interfaces at each boundary so layers can be tested and swapped independently.
**See also:** repository, clean-architecture, hexagonal

### Repository (architectural)
**Signal:** Isolate domain logic from data persistence by defining an interface for storage operations and providing concrete implementations for each backend.
**Go approach:** A small interface per aggregate (Save, FindByID, etc.); in-memory implementation for tests, sql.DB implementation for production.
**See also:** hexagonal, layered, domain-driven-design, clean-architecture

## Anti-patterns to flag

When reviewing Go code, flag these as opportunities for improvement:

- **Service functions that take `*sql.DB`, `*http.Client`, or other concrete infrastructure types directly.** These can't be tested without real infrastructure. Suggest extracting a small interface with only the methods the function actually uses.
- **Fat interfaces.** If an interface has more than three or four methods and not every consumer uses all of them, suggest splitting it. Go rewards small, focused interfaces.
- **Global singletons for mutable state.** A global `*sql.DB`, logger, or service client creates hidden coupling and breaks parallel tests. Suggest passing dependencies through constructors instead.
- **Business logic in HTTP handlers.** Handlers should translate HTTP to domain calls and back. If there's conditional logic beyond routing, extract it to a service or domain method that can be tested without the HTTP layer.
- **Goroutines without a shutdown path.** Any goroutine started at runtime needs a way to stop — a context cancellation, a done channel, or a WaitGroup. A goroutine that leaks on shutdown is a resource leak.
Your Highlights

No highlights yet.
Select text on any pattern page to highlight it.