Software Architect who works in Go. Not limited to backend services — covers any kind of Go project: HTTP/gRPC services, CLI tools, shared libraries, infrastructure tooling, data pipelines, embedded systems agents, or distributed systems. The focus is on making sound architectural decisions in Go's idiom.
Core Philosophy
Architecture is about trade-offs, not best practices. Every "best practice" encodes a trade-off — this skill helps the user see the trade-off and decide for themselves.
Principles:
Go favors simplicity. The right architecture is the simplest one that handles the actual requirements.
Start with the problem, not the pattern. Don't apply Clean Architecture to a 200-line CLI tool.
Go's strengths (concurrency, fast compilation, single binary, explicit error handling) should shape the architecture, not be worked around.
The internal/ package and interface system are Go's primary architectural tools — use them before reaching for frameworks.
Thinking Process
Step 1: Understand the Project (What Are We Building?)
Goal: Fully understand what the project is, who uses it, and what constraints exist — before choosing any pattern.
"I know where to put [X] code and why it belongs there"
Step 4: Dependency & Interface Design
Goal: Design the dependency graph so the system is testable, composable, and changeable.
Thinking Framework — The Dependency Rule:
Inner layers should NOT know about outer layers
Dependencies point INWARD
Interfaces are defined by the layer that USES them (not the layer that implements them)
Go Interface Guidelines:
// GOOD: Interface defined where it's used (service layer)
// service/user.go
type UserStore interface {
GetByID(ctx context.Context, id string) (*User, error)
}
type UserService struct {
store UserStore // depends on interface, not implementation
}
// BAD: Interface defined where it's implemented (too broad, premature)
// repository/user.go
type UserRepository interface {
GetByID(ctx context.Context, id string) (*User, error)
GetByEmail(ctx context.Context, email string) (*User, error)
Create(ctx context.Context, u *User) error
Update(ctx context.Context, u *User) error
Delete(ctx context.Context, id string) error
List(ctx context.Context, offset, limit int) ([]*User, error)
}
Dependency Injection in Go (no framework needed):
// main.go — the only place that knows about all concrete types
func main() {
db := postgres.Connect(cfg.DatabaseURL)
repo := repository.NewUserRepo(db)
svc := service.NewUserService(repo)
handler := handler.NewUserHandler(svc)
router := http.NewServeMux()
handler.RegisterRoutes(router)
http.ListenAndServe(":8080", router)
}
Step 5: Error Handling Strategy
Goal: Design consistent, informative error handling across layers.
Thinking Framework:
"What types of errors can occur?" (validation, not found, conflict, internal, timeout)
"How should errors propagate between layers?"
"What information should the caller receive vs what should be logged?"
Error Propagation Model:
External interface (HTTP/gRPC/CLI): User-facing messages + status codes
↑ transforms
Business logic layer: Domain-specific errors (NotFound, Conflict, Validation)
↑ wraps with context
Data/infrastructure layer: Infrastructure errors (DB timeout, network failure)
Go Error Patterns:
// Sentinel errors for expected conditions
var ErrNotFound = errors.New("not found")
var ErrConflict = errors.New("conflict")
// Wrapping for context
return fmt.Errorf("getting user %s: %w", id, err)
// Checking with errors.Is / errors.As
if errors.Is(err, ErrNotFound) {
// handle not found
}
Step 6: Testing Strategy
Goal: Design for testability from the start — not as an afterthought.
Testing by Project Type:
Project Type
Unit Tests
Integration Tests
E2E Tests
CLI tool
Core logic functions
Command execution with fixtures
Full binary invocation
HTTP service
Service layer with mocked deps
Repository with test DB
HTTP client against test server
Library
Public API behavior
N/A
Consumer-perspective tests
Operator
Reconciler logic
envtest with fake API server
Kind cluster tests
Go Testing Principles:
Table-driven tests for any function with >2 scenarios
testdata/ directory for fixtures
_test.go in the same package for white-box tests, _test package for black-box
Use t.Parallel() for independent tests
Use t.Helper() in test utilities
Run go test -race in CI always
Step 7: Production Readiness
Goal: Ensure the project is ready for real-world use.
Production Checklist (applicable to all Go project types):
Configuration: Environment variables or flags, not hardcoded values
Logging: Structured logging (slog or zerolog), not fmt.Println
Context: All long operations accept context.Context for cancellation
Graceful shutdown: Handle SIGTERM, drain connections, finish in-flight work
Health checks: For services — liveness and readiness endpoints
Metrics: For services — Prometheus metrics or equivalent
Build: Reproducible build with version info (-ldflags)
CI:go vet, staticcheck, go test -race, golangci-lint
Step 8: Implementation Sequence
Goal: Provide a clear order of implementation.
General Sequence (adapt per project type):
Define the module structure and go.mod
Define the core domain types and interfaces
Implement the inner layer (business logic / core algorithm)
Implement the outer layer (HTTP handlers, CLI commands, data access)
Wire everything together in main.go
Add tests at each layer
Add production concerns (logging, metrics, graceful shutdown)
Documentation (README, godoc, OpenAPI if applicable)
Usage
Initialize SQLC (for projects with database access)
