Architecture Decision Records on Go Micro

Adr 001 Plugin Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Microservices frameworks need to support multiple infrastructure backends (registries, brokers, transports, stores). Different teams have different preferences and existing infrastructure.

Hard-coding specific implementations:

Limits framework adoption
Forces migration of existing infrastructure
Prevents innovation and experimentation

Decision

Go Micro uses a pluggable architecture where:

Core interfaces define contracts (Registry, Broker, Transport, Store, etc.)
Multiple implementations live in the same repository under interface directories
Plugins are imported directly and passed via options
Default implementations work without any infrastructure

Structure

go-micro/
├── registry/ # Interface definition
│ ├── registry.go
│ ├── mdns.go # Default implementation
│ ├── consul/ # Plugin
│ ├── etcd/ # Plugin
│ └── nats/ # Plugin
├── broker/
├── transport/
└── store/

Consequences

Positive

No version hell: Plugins versioned with core framework
Discovery: Users browse available plugins in same repo
Consistency: All plugins follow same patterns
Testing: Plugins tested together
Zero config: Default implementations require no setup

Negative

Repo size: More code in one repository
Plugin maintenance: Core team responsible for plugin quality
Breaking changes: Harder to evolve individual plugins independently

Neutral

Plugins can be extracted to separate repos if they grow complex
Community can contribute plugins via PR
Plugin-specific issues easier to triage

Alternatives Considered

Separate Plugin Repositories

Used by go-kit and other frameworks. Rejected because:

Adr 004 Mdns Default Registry

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Service discovery is critical for microservices. Common approaches:

Central registry (Consul, Etcd) - Requires infrastructure
DNS-based (Kubernetes DNS) - Platform-specific
Static configuration - Doesn’t scale
Multicast DNS (mDNS) - Zero-config, local network

For local development and getting started, requiring infrastructure setup is a barrier. Production deployments typically have existing service discovery infrastructure.

Decision

Use mDNS as the default registry for service discovery.

Adr 009 Progressive Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Microservices frameworks face a paradox:

Beginners want “Hello World” to work immediately
Production needs sophisticated configuration

Too simple: Framework is toy, not production-ready Too complex: High barrier to entry, discourages adoption

Decision

Implement progressive configuration where:

Zero config works for development
Environment variables provide simple overrides
Code-based options enable fine-grained control
Defaults are production-aware but not production-ready

Levels of Configuration

Level 1: Zero Config (Development)

svc := micro.NewService("hello")
svc.Run()

Uses defaults:

Adr 010 Unified Gateway

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted Date: 2026-02-11 Authors: Go Micro Team

Context

Previously, the go-micro CLI had two separate gateway implementations:

micro run gateway (cmd/micro/run/gateway/) - Simple HTTP-to-RPC proxy for development
micro server gateway (cmd/micro/server/) - Production gateway with authentication, web UI, and API documentation

This duplication created several problems:

Code maintenance: Gateway logic (HTTP-to-RPC translation, service discovery, health checks) was implemented twice
Feature parity: Improvements to one gateway didn’t automatically benefit the other
Complexity: New features (like MCP integration) would need to be implemented twice
Testing burden: Each gateway required separate testing

Decision

We unified the gateway implementation by: