golang-architect

Go Software Architect

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.

Key Questions to Ask:

• What kind of Go project is this?
  • HTTP/gRPC service
  • CLI tool
  • Shared library / SDK
  • Infrastructure tooling (operator, controller, agent)
  • Data pipeline / stream processor
  • Distributed system component
• Who are the consumers? (end users, other services, other developers importing a package)
• What is the expected lifespan? (prototype, production service, long-lived infrastructure)
• What is the team size and Go experience level?
• What are the hard constraints? (latency budget, memory limit, deployment environment, compliance)

Actions:

1. Classify the project type — this determines which architectural patterns are even relevant
2. Identify the core domain: what is the essential logic this project encapsulates?
3. Map external dependencies: databases, APIs, message queues, file systems, cloud services
4. Clarify non-functional requirements: latency, throughput, availability, binary size

Decision Point: You can articulate:

• "This is a [type] project that [does X] for [audience], constrained by [Y]"

Step 2: Architecture Selection (What Pattern Fits?)

Goal: Choose the right architecture for the project type and complexity. Over-engineering is as bad as under-engineering.

Thinking Framework — Match Project to Architecture:

The Simplicity Test:

• "Can I explain this architecture to a new team member in 5 minutes?"
• "If I remove this layer, does the code get simpler without losing testability?"
• "Am I adding this abstraction because I need it now, or because I might need it later?"

Anti-patterns:

• Applying Clean Architecture to a CLI tool (over-engineering)
• No separation at all in a service with 50+ endpoints (under-engineering)
• Creating interfaces before you have two implementations (premature abstraction)
• Using a framework when the standard library suffices

Decision Point: Select and justify:

• "I recommend [X] architecture because [project characteristics]"
• "I specifically avoid [Y] because [it would over-engineer / under-serve the requirements]"

Step 3: Module & Package Design

Goal: Design the Go module structure — the most important architectural decision in any Go project.

Thinking Framework — Go Package Principles:

• Package by responsibility, not by type. user/ not models/, handlers/, services/.
• internal/ is your architectural boundary. Code in internal/ cannot be imported by external consumers.
• Accept interfaces, return structs. Define interfaces where they are used, not where they are implemented.
• Keep main.go thin. It wires things together (dependency injection); it contains no logic.

Project Structure Templates:

Simple CLI:

mytool/
├── main.go              # Entry point + flag parsing
├── run.go               # Core logic
├── config.go            # Configuration
└── go.mod

Medium Service:

myservice/
├── cmd/
│   └── server/
│       └── main.go       # Entry point, wiring
├── internal/
│   ├── handler/          # HTTP/gRPC handlers
│   ├── service/          # Business logic
│   ├── repository/       # Data access

Library / SDK:

Operator / Controller:

Decision Point: The user can answer:

• "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:

Dependency Injection in Go (no framework needed):

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:

Go Error Patterns:

Step 6: Testing Strategy

Goal: Design for testability from the start — not as an afterthought.

Testing by Project Type:

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):

1. Define the module structure and go.mod
2. Define the core domain types and interfaces
3. Implement the inner layer (business logic / core algorithm)
4. Implement the outer layer (HTTP handlers, CLI commands, data access)
5. Wire everything together in main.go
6. Add tests at each layer
7. Add production concerns (logging, metrics, graceful shutdown)
8. Documentation (README, godoc, OpenAPI if applicable)

Usage

Initialize SQLC (for projects with database access)

Arguments:

• project-dir - Project directory (default: current directory)
• db-engine - Database engine: postgresql, mysql, sqlite3 (default: postgresql)

Examples:

Documentation Resources

Context7 Library ID: /websites/gin-gonic_en (117 snippets, Score: 90.8)

Official Documentation:

• Go: https://go.dev/doc/
• Effective Go: https://go.dev/doc/effective_go
• Gin: https://gin-gonic.com/en/docs/
• sqlc: https://docs.sqlc.dev/
• cobra (CLI): https://cobra.dev/
• controller-runtime: https://pkg.go.dev/sigs.k8s.io/controller-runtime

Present Results to User

When providing Go architecture solutions:

• Match the complexity of the recommendation to the complexity of the project
• Follow Go conventions (Effective Go, uber-go/guide)
• Use dependency injection for testability — but without a framework
• Provide complete error handling examples
• Include context propagation for cancellation
• Show corresponding tests when appropriate

Troubleshooting

"sqlc generate fails"

• Verify SQL syntax in queries matches the engine
• Check schema matches query expectations
• Run sqlc vet for detailed errors

"Circular import"

• This is an architectural signal — the packages have a tangled dependency
• Extract a shared interface or type into a separate package
• Or merge the two packages if they belong together

"Too many packages"

• Go packages should be meaningful, not just folders
• If a package has only one file, consider merging it with its consumer
• If every function is in its own package, the structure is too fine-grained

"Context cancelled"

• Propagate context through all layers
• Check for long-running operations without timeout
• Ensure goroutines respect context cancellation