Go Software Architecture

Section 01

Architecture Categories & Landscape

Structural Patterns

How the codebase is organized

MonolithicLayeredCleanHexagonalDDD

Deployment Patterns

How services are deployed & scaled

MicroservicesSOAServerless

Communication Patterns

How components communicate & coordinate

Event-DrivenCQRS

🏛️

Monolithic

Structural

Single deployable unit. All modules in one process.

🔬

Microservices

Deployment

Independent services, each owning its domain & data.

⚡

Event-Driven

Communication

Async event streams decouple producers from consumers.

🎯

Clean Arch

Structural

Dependency inversion: domain at center, infra at edge.

🥞

Layered (N-Tier)

Structural

Strict horizontal layers: Presentation → Business → Data.

⬡

Hexagonal

Structural

Ports & Adapters. Application core with plug-in interfaces.

⚖️

CQRS

Communication

Commands (write) and Queries (read) on separate models.

☁️

Serverless

Deployment

Functions-as-a-Service. No server management.

🕸️

SOA

Deployment

Enterprise services over a shared ESB/message bus.

🌐

DDD

Structural

Domain model drives architecture. Bounded contexts.

          Architecture Selection by Project Scale & Complexity

Small Project

1-5 devs · MVP · Startup

Monolithic

Layered

Medium Project

5-20 devs · Growing SaaS

Clean Arch

Hexagonal

DDD

Large Project

20-100+ devs · Enterprise

Microservices

Event-Driven

CQRS

Hyper-Scale

100+ devs · Platform

SOA

Serverless

Microservices

Architecture 01 · Structural

Monolithic Architecture

🏛️

Monolithic Architecture

Structural · Single Deployable Unit · GoF Foundation

An application where all functionality is bundled into a single deployable binary. All modules — HTTP handlers, business logic, database access, authentication — exist in one Go binary, run in one process, and are deployed together. The default starting architecture for most projects.

Deployment: Single binary Process: One DB: Typically one shared Best team size: 1–15

What Is It?

Everything lives in one codebase, one binary, one process. A Go monolith might have packages like /handlers, /services, /repository, /models — all compiled into a single go build output. No network calls between components; they call each other as regular Go function calls.

A well-structured monolith uses internal package boundaries to enforce modularity — the "modular monolith" variant is the best starting point for most production Go systems.

Characteristics

Single process: all goroutines share the same memory
In-process calls: function calls, not HTTP/gRPC — zero latency
Shared database: one schema, one connection pool
Unified deployment: one go build, one Docker image
Vertical scaling: bigger machine → bigger monolith
Simple debugging: one stack trace, one log stream

How It Works (Go)

HTTP Request enters

Gin/Echo/Chi router in main.go receives the request.

Handler layer

/handlers/order.go parses, validates request, calls service.

Service / Business layer

/services/order.go applies business rules — direct function call, zero overhead.

Repository / Data layer

/repository/order.go queries PostgreSQL. Returns to handler. HTTP response.

Complexity & Scale Metrics

Setup complexity

Very Low

Dev velocity

Very High

Operational cost

Very Low

Horizontal scale

Limited

Team scalability

Limited

Debugging ease

Excellent

Project Suitability

✓ Startup MVP ✓ Small SaaS ✓ Internal Tools ✓ Blog / CMS ✓ Small E-commerce ~ Medium REST API ~ ERP (early stage) ✗ Multi-team Platform ✗ High-scale Real-time ✗ Independent deploy cycles Small ✓ Medium ✓ Large ✗

monolith/main.go — Modular Monolith Structure

// Recommended Go Modular Monolith project structure:
          // myapp/
          // ├── cmd/server/main.go ← Entry point — wires everything
          // ├── internal/
          // │ ├── handlers/ ← HTTP layer (Gin/Echo)
          // │ │ ├── order.go
          // │ │ └── menu.go
          // │ ├── services/ ← Business logic (pure Go, no HTTP deps)
          // │ │ ├── order.go
          // │ │ └── menu.go
          // │ ├── repository/ ← Data access (SQL, Redis)
          // │ │ ├── postgres/
          // │ │ └── redis/
          // │ ├── domain/ ← Types, interfaces, business entities
          // │ └── config/ ← App config loading
          // └── pkg/ ← Shared utilities (logging, errors)

          package main

          import (
          "github.com/gin-gonic/gin"
          "myapp/internal/handlers"
          "myapp/internal/repository/postgres"
          "myapp/internal/services"
          )

          func main() {
          // Manual Dependency Injection — wired at startup
          db := postgres.New(cfg.DatabaseURL)
          repo := postgres.NewOrderRepo(db)
          svc := services.NewOrderService(repo)
          hdlr := handlers.NewOrderHandler(svc)

          r := gin.Default()
          r.POST("/orders", hdlr.Create)
          r.GET("/orders/:id", hdlr.Get)
          r.Run(":8080")
          // No service discovery. No network calls between modules.
          // Everything: one process, one binary, one deploy.
          }
        

⚠ BOTTLENECKS & KNOWN ISSUES

Scaling bottleneck: Must scale the entire app even if only one module is under load
Deployment bottleneck: One bug in any module can take down the entire system
Team bottleneck: Merge conflicts increase as team size grows past ~15 developers
Technology bottleneck: Entire app must use same Go version, same dependencies
Memory: Single process means one large heap — high-frequency GC pauses at scale

✓ ADVANTAGES

Simplest possible architecture — YAGNI-compliant
Zero network latency between modules (in-process calls)
One log stream, one debugger, one deployment unit
Trivial local development — one go run command
ACID transactions across entire system trivially
No service discovery, no distributed tracing overhead
Best for early-stage products where speed matters most
Easy to refactor — compiler catches all breakage

✗ DISADVANTAGES

One module failure can crash entire application
Cannot scale individual modules independently
Merge conflicts and coordination overhead at large team sizes
Tech stack locked — no module-level polyglot
Long build/test times as codebase grows
Deploy all-or-nothing — risky for large releases
Tight coupling risk: modules can call each other freely

🍕

Domino's-style Restaurant Ordering Platform (Early Stage)

A single Go binary handles: online menu browsing, cart management, order placement, payment processing (Stripe), kitchen notification, driver dispatch, and admin dashboard. All modules share a PostgreSQL connection pool and Redis cache. One deploy, one server, one codebase. Team of 5 ships features daily without coordination overhead. When order volumes hit 10K/day, deploy on a bigger VM — no architectural change needed until that VM is maxed out.

Online Ordering Menu Management Payment (Stripe) Kitchen Dashboard Single Deploy

Architecture 02 · Deployment

Microservices Architecture

🔬

Microservices Architecture

Deployment Pattern · Independent Services · Cloud-Native

An application structured as a collection of small, autonomous services — each owning its own data, deployed independently, communicating over the network (HTTP/gRPC/message queues). Each service is a separate Go binary. The gold standard for large-scale, multi-team systems.

Deployment: Independent binaries Communication: gRPC / HTTP / Events DB: One DB per service Best team: 2-pizza rule per service

What Is It?

Instead of one big Go binary, you have 10-50+ small Go binaries: order-service, menu-service, payment-service, notification-service, each in its own repo. They communicate via gRPC (internal) or REST (external). Each owns its own PostgreSQL schema/database. Each can be deployed, scaled, and failed independently.

Core Principles

Single Responsibility: each service does ONE thing well
Data isolation: no shared databases — each service owns its data
Deploy independence: update order-service without touching menu-service
Failure isolation: payment-service failure doesn't crash menu browsing
Technology freedom: one service can be Go, another Python (rarely needed)
Owned by one team: Amazon "two-pizza" rule

Key Requirements

Service Discovery: Consul, etcd, or Kubernetes DNS
API Gateway: Kong, Traefik, or custom Go gateway
Distributed Tracing: OpenTelemetry + Jaeger / Zipkin
Centralized Logging: ELK / Loki / Datadog
Circuit Breakers: Sony gobreaker / Hystrix-go
Health checks + readiness probes on every service
Container orchestration: Kubernetes (standard)

Complexity Metrics

Setup complexity

Very High

Dev velocity

Medium

Operational cost

Very High

Horizontal scale

Excellent

Team scalability

Excellent

Debugging ease

Hard

Project Suitability

✓ Large E-Commerce (Amazon) ✓ Fintech Platform ✓ Multi-team SaaS ✓ High-scale API Platform ✓ Netflix/Uber-style apps ~ Growing startup with product-market fit ✗ Solo developer / Small team ✗ MVP / Prototype ✗ Simple CRUD app Large ✓ Enterprise ✓

microservices/order-service/main.go — gRPC Server

// Each microservice is a standalone Go binary
          // order-service/
          // ├── cmd/main.go ← gRPC + HTTP server startup
          // ├── internal/
          // │ ├── handler/ ← gRPC handlers
          // │ ├── service/ ← Business logic
          // │ └── repository/ ← This service's OWN database
          // ├── proto/ ← Protobuf definitions
          // └── go.mod ← INDEPENDENT module — own dependencies!

          package main

          import (
          "google.golang.org/grpc"
          "go.opentelemetry.io/otel" // Distributed tracing
          orderpb "order-service/proto/order"
          )

          func main() {
          // Each service: its own config, its own DB, its own port
          db := connectOwnDatabase(cfg.DatabaseURL)
          svc := service.New(db)

          // gRPC server with interceptors (tracing, logging, recovery)
          grpcServer := grpc.NewServer(
          grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),
          grpc.UnaryInterceptor(loggingInterceptor),
          )
          orderpb.RegisterOrderServiceServer(grpcServer, svc)

          // Health check for Kubernetes probes
          go serveHealthCheck(":8090")

          grpcServer.Serve(lis)

          // To call another service (e.g. payment-service):
          // conn, _ := grpc.Dial("payment-service:9090", grpc.WithInsecure())
          // paymentClient := paymentpb.NewPaymentServiceClient(conn)
          }
        

⚠ BOTTLENECKS & DISTRIBUTED SYSTEM CHALLENGES

Network latency: What was a function call is now an RPC — adds 1-10ms per hop
Distributed transactions: No ACID across services — must use Saga Pattern or 2PC
Service mesh complexity: Istio/Linkerd adds operational overhead
Data consistency: Eventual consistency is the norm — harder to reason about
Debugging: A single request spans 5+ services — requires distributed tracing
Test environment: Running full system locally requires Docker Compose or Minikube

✓ ADVANTAGES

Independent scaling per service (scale only what's under load)
Independent deployments — one team doesn't block another
Fault isolation — one service failure doesn't cascade
Teams own their service end-to-end (full autonomy)
Technology choice per service (rarely needed, but possible)
Smaller codebases per service — easier to understand
Industry standard for large cloud-native platforms

✗ DISADVANTAGES

Massive operational complexity (K8s, service mesh, observability)
Distributed system fallacies — network is NOT reliable
Inter-service testing and integration test complexity
Data consistency and distributed transactions are hard
Latency overhead from network calls
Significant infrastructure cost vs monolith
Requires mature DevOps/platform engineering team

🚀

Uber Eats / Large Food Platform (Scale)

At Uber-scale: restaurant-service (menu, hours, onboarding) → search-service (Elasticsearch, geo-search) → order-service (placement, lifecycle) → pricing-service (surge, discounts) → payment-service (Stripe, wallets) → dispatch-service (driver matching, routing) → notification-service (push, SMS, email) → analytics-service (Kafka consumer, data warehouse). Each team deploys 10x/day independently. Each service scales to handle its own peak load.

Independent Deploy Per-Service Scaling gRPC Internal Kubernetes Fault Isolation

Architecture 03 · Communication

Event-Driven Architecture

⚡

Event-Driven Architecture (EDA)

Communication Pattern · Asynchronous · Reactive

Components communicate by producing and consuming events asynchronously via a message broker (Kafka, NATS, RabbitMQ). Producers don't know who consumes their events. Consumers don't know who produced. Maximum decoupling — perfect for systems where actions trigger cascading reactions across many services.

Communication: Async events Broker: Kafka / NATS / RabbitMQ Coupling: Very Low Consistency: Eventual

Core Concepts

Event: Immutable fact — "OrderPlaced", "PaymentFailed", "UserSignedUp"
Producer: Service that emits events (doesn't know consumers)
Consumer: Service that subscribes to topics (doesn't know producer)
Topic/Channel: Named stream — "orders.placed", "payments.completed"
Event Store: Append-only log (Kafka topic = ordered, replayed)
Dead Letter Queue: Failed events routed for retry/inspection

How It Works

Action triggers event

Order service places order → publishes OrderPlaced event to Kafka topic orders.placed.

Broker persists event

Kafka durably stores the event in ordered partition. Consumers can replay from any offset.

Consumers react independently

Kitchen, inventory, analytics, notification services each consume in parallel — at their own pace.

Each consumer may produce

Kitchen service consumes OrderPlaced, produces CookingStarted. Notification consumes that, pushes to customer.

EDA Styles in Go

Simple Pub/Sub: NATS JetStream — fastest, zero persistence, ideal for real-time
Event Streaming: Kafka — durable, ordered, replayable — fintech/audit logs
Message Queuing: RabbitMQ — work queues, routing, dead-letter
In-process channels: Go channels for single-service event bus
Event Sourcing: Events ARE the source of truth — replay to rebuild state

Complexity Metrics

Setup complexity

High

Coupling level

Very Low

Throughput

Excellent

Consistency

Eventual

Debugging

Hard

Resilience

Very High

event-driven/kafka_consumer.go — Go Kafka Consumer

package consumer

          import (
          "context"
          "encoding/json"
          "github.com/segmentio/kafka-go"
          )

          type OrderPlacedEvent struct {
          OrderID string `json:"order_id"`
          CustomerID string `json:"customer_id"`
          Items []Item `json:"items"`
          Total float64 `json:"total"`
          }

          // KitchenConsumer — reacts to order.placed events
          type KitchenConsumer struct {
          reader *kafka.Reader
          printer TicketPrinter
          }

          func NewKitchenConsumer(brokers []string) *KitchenConsumer {
          return &KitchenConsumer{
          reader: kafka.NewReader(kafka.ReaderConfig{
          Brokers: brokers,
          Topic: "orders.placed",
          GroupID: "kitchen-service", // consumer group
          MinBytes: 10e3,
          MaxBytes: 10e6,
          }),
          }
          }

          func (c *KitchenConsumer) Run(ctx
          context.Context) {
          for {
          msg, err := c.reader.ReadMessage(ctx) // blocks until event
            arrives
          if err != nil { break }

          var evt OrderPlacedEvent
          json.Unmarshal(msg.Value, &evt)

          // React to the event — no knowledge of who produced it
          c.printer.PrintKitchenTicket(evt)
          // This consumer can be added/removed without changing Order Service
          }
          }

          // Producer side — Order Service publishes event:
          // kafka.NewWriter → writer.WriteMessages(ctx, kafka.Message{
          // Topic: "orders.placed",
          // Value: json.Marshal(OrderPlacedEvent{...}),
          // })
        

✓ ADVANTAGES

Maximum decoupling — producers/consumers unaware of each other
Extreme throughput — Kafka handles millions of events/sec
Event replay — rebuild state, replay for new consumers
Resilience — consumers process events when ready
Audit trail — every event is an immutable log entry
Natural fit for real-time analytics, IoT, finance

✗ DISADVANTAGES

Eventual consistency — system state may be temporarily inconsistent
Complex debugging — event chains are hard to trace
Message ordering guarantees can be tricky
Schema evolution requires care (Protobuf/Avro helps)
Broker adds operational complexity
Testing event flows requires more setup

💳

Fintech Payment Platform — Real-Time Transaction Processing

Every payment triggers an event chain: PaymentInitiated → fraud-detection-service consumes → FraudCheckPassed → payment-processor-service charges card → PaymentCompleted → ledger-service records → notification-service alerts → analytics-service aggregates → compliance-service logs for regulators. All async, all parallel, all independently scalable. Kafka retains 30 days of events for replay and audit.

KafkaEvent SourcingAudit TrailReal-time AlertsNATS for low-latency

Architecture 04 · Structural

Clean Architecture (Go-style)

🎯

Clean Architecture

Structural Pattern · Robert C. Martin (Uncle Bob) · Go-Idiomatic

Organizes code into concentric layers with a strict dependency rule: dependencies only point inward. The domain/business logic at the center knows nothing of HTTP, SQL, or frameworks. The outermost layers handle I/O. Go's interfaces make this architecture natural and testable.

Core Rule: Dependencies → inward only Domain: framework-free Testability: Maximum Best for: Long-lived systems

The 4 Layers (Go)

Domain / Entities: Pure Go structs and interfaces. Zero imports from outer layers. Business rules live here.
Use Cases / Interactors: Application-specific business logic. Calls domain interfaces. Knows nothing of HTTP or SQL.
Interface Adapters: Controllers (HTTP handlers), Presenters, Gateways. Converts between use case format and outer world format.
Frameworks & Drivers: Gin, GORM, Redis, Kafka. The outermost ring — details that can be swapped.

The Dependency Rule

Source code dependencies must always point inward toward higher-level policy. Nothing in an inner circle can know about something in an outer circle. The domain never imports Gin. The use case never imports GORM. Outer layers implement interfaces defined by inner layers.

              Frameworks → Adapters → Use Cases → Domain
            

Go Folder Structure

myapp/
├── domain/
                       ← Entities, interfaces
├── usecase/
                     ← Application logic
├── adapter/
├── handler/   ← HTTP (Gin)
└── repo/     ← DB impl
└── infrastructure/
├── postgres/
└── redis/

Complexity Metrics

Initial setup

Medium

Testability

Maximum

Boilerplate

Medium-High

Maintainability

Very High

New dev onboard

Moderate

clean/domain/order.go + usecase/place_order.go

// ── Domain Layer: zero framework imports
            ───────────────────────
          package domain

          type Order struct {
          ID string
          Items []OrderItem
          Total float64
          Status OrderStatus
          }

          // Interface defined in domain — implemented in infrastructure layer
          type OrderRepository interface {
          Save(ctx context.Context, o *Order)
          error
          FindByID(ctx context.Context, id string) (*Order, error)
          }

          // ── Use Case Layer: orchestrates domain, no HTTP/DB knowledge ──
          package usecase

          type PlaceOrderUseCase struct {
          orders domain.OrderRepository // interface, not
            implementation
          payment domain.PaymentGateway // interface, not Stripe
          events domain.EventPublisher // interface, not Kafka
          }

          func (uc *PlaceOrderUseCase) Execute(ctx context.Context, req PlaceOrderRequest) (*PlaceOrderResponse, error) {
          order := domain.NewOrder(req.Items) // pure domain logic
          if err := order.Validate(); err != nil { return nil, err }
          if err := uc.payment.Charge(ctx, order.Total); err != nil {
          return nil, err }
          uc.orders.Save(ctx, order)
          uc.events.Publish("orders.placed", order)
          return &PlaceOrderResponse{OrderID: order.ID}, nil
          }
          // ← This use case is 100% testable with mocks — no DB, no HTTP, no Kafka

          // ── Adapter Layer: HTTP handler wires use case ─────────────────
          package handler

          func (h *OrderHandler) PlaceOrder(c
          *gin.Context) {
          var req usecase.PlaceOrderRequest
          c.ShouldBindJSON(&req)
          resp, err := h.useCase.Execute(c.Request.Context(), req)
          if err != nil { c.JSON(500, gin.H{"error": err}); return }
          c.JSON(201, resp)
          }
        

✓ ADVANTAGES

Maximum testability — use cases testable without any framework
Framework-agnostic — swap Gin for Echo with zero domain changes
DB-agnostic — swap PostgreSQL for MongoDB at infra layer
Clear architectural boundaries — easy to onboard new devs
Business logic protected from external changes
Industry standard for long-lived enterprise Go systems

✗ DISADVANTAGES

More boilerplate than simple layered architecture
Interfaces for everything — can feel over-engineered for simple apps
Data mapping between layers adds code
Learning curve — new devs may be confused by layer boundaries
Overkill for small/short-lived projects

Architecture 05 · Structural

Layered Architecture (N-Tier)

🥞

Layered Architecture (N-Tier)

Structural Pattern · Traditional · Most Common in Go Industry

Organizes code into horizontal layers where each layer has a specific role and only communicates with the layer directly below it. Handler → Service → Repository → Database. The most widely adopted pattern in Go REST APIs — the pragmatic default for most backend systems.

Layers: 3-5 horizontal tiers Rule: Each layer calls layer below Adoption: Most common Go pattern Learning curve: Very low

The 4-Layer Go Stack

Presentation Layer (handler/): HTTP handlers, request parsing, response formatting. Uses Gin/Echo.
Business / Service Layer (service/): Business rules, orchestration, validation. Pure Go, no HTTP.
Repository / Data Layer (repository/): Database access, queries, CRUD. Hides SQL from services.
Domain / Model Layer (domain/): Shared structs, interfaces, constants. Used by all layers.

Rules

Layer N can only call layer N-1 (strict downward dependency)
No skipping layers — handler must never query DB directly
Each layer is replaceable independently
Business logic must NOT live in handlers or repositories
HTTP concepts (request/response) must NOT leak into services
Database concerns must NOT leak into business layer

vs. Clean Architecture

Layered architecture allows any inner layer to depend on a lower one — including service knowing about database types. Clean Architecture enforces that domain never depends on anything. Layered is pragmatic and easier; Clean is stricter and more testable. Most Go teams start with Layered and migrate to Clean when needed.

Suitability

✓ REST APIs (any size) ✓ ERP/CRM systems ✓ SaaS backends ✓ Admin panels ✓ Team default architecture ~ Microservice internals Small ✓ Medium ✓ Large ✓ (with discipline)

layered/service/order_service.go — Business Layer

// ── Handler Layer (Presentation)
            ───────────────────────────────
          func (h *OrderHandler) CreateOrder(c
          *gin.Context) {
          var req CreateOrderRequest
          if err := c.ShouldBindJSON(&req); err != nil { c.JSON(400, err); return }
          order, err := h.service.CreateOrder(c, req) // ← calls service, not
            repo
          if err != nil { c.JSON(500, err);
          return }
          c.JSON(201, order)
          }

          // ── Service Layer (Business Logic) ─────────────────────────────
          type OrderService struct {
          repo OrderRepository // interface
          menu MenuRepository
          payment PaymentGateway
          }

          func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderRequest) (*Order, error) {
          // Business rules: check stock, apply pricing, validate items
          items, err := s.menu.GetItems(ctx, req.ItemIDs)
          if err != nil { return nil, ErrMenuItemsNotFound }

          order := buildOrder(items, req) // business logic
          if err := s.payment.Charge(ctx, order.Total); err != nil {
          return nil, err }

          return s.repo.Create(ctx, order) // ← calls
            repo, not DB directly
          }

          // ── Repository Layer (Data Access) ─────────────────────────────
          func (r *PostgresOrderRepo) Create(ctx context.Context, o *Order)
          (*Order, error) {
          // Only layer that knows SQL — completely hidden from service
          var id string
          err := r.db.QueryRowContext(ctx,
          "INSERT INTO orders (total, status) VALUES ($1, $2) RETURNING id",
          o.Total, o.Status,
          ).Scan(&id)
          o.ID = id
          return o, err
          }
        

✓ ADVANTAGES

Most familiar pattern — every Go dev knows it instantly
Clear separation of concerns by layer
Easy to onboard new developers
Works for any project size with proper discipline
Good IDE navigation — layers map to packages
Pragmatic — less boilerplate than Clean Architecture

✗ DISADVANTAGES

Risk of "sinkhole" anti-pattern — layers just pass data through
Domain can become dependent on infrastructure types
Business logic can leak into handlers or repos
Less strict than Clean Architecture — discipline required
Can become "Big Ball of Mud" without code reviews

Architecture 06 · Structural

Hexagonal Architecture (Ports & Adapters)

⬡

Hexagonal Architecture

Structural Pattern · Alistair Cockburn · Ports & Adapters

Places the application core at the center with defined ports (interfaces) on each side. Adapters plug into these ports to connect the core to the outside world — HTTP, CLI, gRPC, Kafka, PostgreSQL. The application core never changes regardless of what drives or is driven by it.

Core: Application logic Ports: Go interfaces Adapters: Implementations Testability: Maximum

Ports vs Adapters

Driving Ports (Primary): Interfaces the app exposes — HTTP REST, gRPC, CLI, GraphQL all plug in here without changing core
Driven Ports (Secondary): Interfaces the app uses — OrderRepository, PaymentGateway, EmailSender — implemented by adapters
Adapters: Concrete implementations of ports — GinHTTPAdapter, PostgresOrderRepo, StripeAdapter

vs Clean Architecture

Hexagonal and Clean Architecture express the same dependency rule but with different metaphors. Hexagonal uses the hexagon shape to show that there are many equivalent sides (ports) — there's no "top" or "bottom", just inside and outside. Go's implicit interface satisfaction makes Hexagonal effortless to implement.

Key Benefits

Same app can be driven by HTTP, CLI, or message queue — just swap adapter
Tests drive the app via InMemoryAdapter — no DB, no HTTP
Add new delivery mechanisms (gRPC, WebSocket) without touching core
Swap PostgreSQL for MongoDB — swap adapter only
Core is framework-free — pure Go business logic

Suitability

✓ Multi-protocol services ✓ Long-lived domain systems ✓ DDD projects ✓ Healthcare / Fintech ~ Medium SaaS backends ✗ Simple CRUD API Medium ✓ Large ✓

✓ ADVANTAGES

Same core works with HTTP, gRPC, CLI, Kafka — no core changes
Swap any adapter (DB, payment, email) without touching business logic
Tests use InMemory adapters — blazing fast, no infra needed
Natural fit with Domain-Driven Design
Very high maintainability for long-lived systems

✗ DISADVANTAGES

Highest boilerplate of all structural patterns
Concept overhead — ports/adapters language can confuse newcomers
Data mapping at every boundary adds verbose conversion code
Over-engineering for small/medium-sized services

Architecture 07 · Communication

CQRS — Command Query Responsibility Segregation

⚖️

CQRS

Communication Pattern · Greg Young · Often Paired with Event Sourcing

Separates the model for reading data (Query) from the model for writing data (Command). Commands mutate state. Queries return data — never mutate. Read and write models are optimized independently. Often uses separate databases: write-optimized PostgreSQL + read-optimized Elasticsearch or Redis.

Commands: Write / mutate state Queries: Read only Models: Separate read/write Best with: Event Sourcing

The Core Split

Commands: PlaceOrderCommand, UpdateMenuCommand — mutate state, return void or error
Queries: GetOrderQuery, SearchMenuQuery — pure reads, return projections
Write DB: Normalized PostgreSQL — optimized for transactional writes
Read DB: Denormalized Elasticsearch/Redis — optimized for complex queries
Projections: Event handlers that update read models from write events

Why Separate?

Read and write workloads have fundamentally different needs. Writes need ACID transactions, foreign keys, strong consistency. Reads need fast aggregations, full-text search, denormalized joins, caching. CQRS lets you optimize each side independently — scale read replicas, use Elasticsearch for complex queries, Redis for hot data — without compromising write integrity.

Suitability

✓ High read/write ratio imbalance ✓ Complex query requirements ✓ E-commerce search + order ✓ Analytics dashboards ✓ Fintech reporting ~ Any system with audit requirements ✗ Simple CRUD (severe overkill) Large ✓

Complexity Metrics

Overall complexity

Very High

Read performance

Excellent

Write performance

Excellent

Consistency

Eventual

Infra cost

High

cqrs/command/place_order.go + query/get_orders.go

// ── COMMAND SIDE — Writes to PostgreSQL (normalized)
            ──────────
          type PlaceOrderCommand struct {
          CustomerID string
          Items []OrderItem
          PaymentToken string
          }

          func (h *PlaceOrderHandler) Handle(ctx context.Context, cmd PlaceOrderCommand) error {
          order := domain.NewOrder(cmd)
          if err := h.writeRepo.Save(ctx, order); err != nil { return err }
          // Emit event → projector updates read DB (Elasticsearch)
          h.eventBus.Publish("order.placed", OrderPlacedEvent{Order: order})
          return nil
          }

          // ── QUERY SIDE — Reads from Elasticsearch (denormalized) ──────
          type GetOrdersQuery struct {
          CustomerID string
          Status string
          DateFrom time.Time
          Page int
          }

          type OrderReadModel struct { // Denormalized — pre-joined for fast read
          OrderID string
          CustomerName string // pre-joined from customers table
          ItemNames []string // pre-joined from menu items
          RestaurantName string
          Total float64
          }

          func (h *GetOrdersHandler) Handle(ctx
          context.Context, q GetOrdersQuery) ([]OrderReadModel, error) {
          // Query Elasticsearch directly — no joins needed (already denormalized)
          return h.readRepo.Search(ctx, q) // blazing
            fast full-text + filter
          }
        

✓ ADVANTAGES

Read and write models optimized independently
Scale reads and writes independently
Complex queries without polluting write model
Natural audit trail (events drive projections)
Excellent for reporting, analytics, search-heavy apps

✗ DISADVANTAGES

Eventual consistency — read model may lag behind write
Significant complexity — two models, two DBs, projections
Overkill for 80% of applications
Testing both sides doubles surface area
Projection synchronization bugs are subtle

Architecture 08 · Deployment

Serverless / FaaS Architecture

☁️

Serverless Architecture (FaaS)

Deployment Pattern · Functions-as-a-Service · Event-triggered

Application logic is deployed as stateless functions triggered by events (HTTP, cron, queue message). No server management, infinite auto-scaling, pay-per-execution billing. In Go — compile to a tiny binary, deploy to AWS Lambda, GCP Cloud Functions, or Cloudflare Workers.

Runtime: AWS Lambda / GCF / CF Workers Scaling: Automatic ∞ Billing: Per invocation State: External (DB/Cache)

How It Works

Write a Go function that accepts a specific event type (APIGatewayProxyRequest, S3Event)
Compile: GOARCH=amd64 GOOS=linux go build -o bootstrap
Deploy ZIP or container to Lambda/Cloud Functions
Platform provisions, scales, and terminates compute automatically
Cold start: ~100-500ms for Go (much faster than JVM)
Warm invocation: microseconds overhead

Go's Advantage for Serverless

Go compiles to a single native binary — no runtime, no JVM startup. Cold starts are 10x faster than Java, 2-3x faster than Python. The binary is tiny (~10MB). Go's goroutine model handles concurrent invocations efficiently within a single container. AWS Lambda supports Go natively with the aws-lambda-go SDK.

Best Use Cases

API backends with unpredictable/bursty traffic
Scheduled jobs (cron — nightly reports, cleanup)
Event processing (S3 upload → resize image)
Webhook receivers (Stripe, GitHub, Slack)
Background tasks (send email, generate PDF)
Edge functions (Cloudflare Workers)

Suitability

✓ Bursty/unpredictable traffic ✓ Webhook processing ✓ Scheduled tasks ✓ Startup / MVP cost savings ~ Microservice add-ons ✗ Long-running connections (WebSocket) ✗ High-frequency low-latency APIs Small ✓ Medium ✓

serverless/lambda/order_webhook.go — AWS Lambda Handler

package main

          import (
          "context"
          "encoding/json"
          "github.com/aws/aws-lambda-go/events"
          "github.com/aws/aws-lambda-go/lambda"
          )

          // Stripe webhook handler — deployed as Lambda function
          func handleWebhook(ctx context.Context, req events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
          // Verify Stripe signature
          event, err := stripe.ConstructEvent(
          []byte(req.Body),
          req.Headers["Stripe-Signature"],
          os.Getenv("STRIPE_WEBHOOK_SECRET"),
          )
          if err != nil {
          return events.APIGatewayProxyResponse{StatusCode: 400}, nil
          }

          switch event.Type {
          case "payment_intent.succeeded":
          fulfillOrder(ctx, event) // trigger fulfillment
          case "payment_intent.payment_failed":
          notifyFailure(ctx, event) // alert customer
          }

          return events.APIGatewayProxyResponse{StatusCode: 200}, nil
          }

          func main() { lambda.Start(handleWebhook) }

          // Build: GOARCH=amd64 GOOS=linux go build -o bootstrap ./lambda/
          // Deploy: zip function.zip bootstrap && aws lambda update-function-code
          // Cost: $0.0000002 per request — scale to millions free tier
        

✓ ADVANTAGES

Zero server management — focus on code only
Infinite auto-scaling — handles any traffic spike
Pay per use — cost $0 when idle
Go cold starts are very fast (~100ms)
Perfect for event-driven workloads
Integrated with cloud services (S3, SQS, DynamoDB)

✗ DISADVANTAGES

Cold starts add latency (unacceptable for SLA-bound APIs)
No persistent connections (DB pooling is tricky)
Vendor lock-in (AWS Lambda API is proprietary)
15-minute max execution time (AWS)
Local development and testing is more complex
Debugging is harder — no persistent process

Architecture 09 · Deployment

Service-Oriented Architecture (SOA)

🕸️

Service-Oriented Architecture (SOA)

Deployment Pattern · Enterprise · Pre-Microservices

Structures software as a set of interoperable services communicating over a shared enterprise bus (ESB). Services are coarser-grained than microservices and often share data via a central bus or shared database. The enterprise predecessor to microservices — still dominant in large legacy organizations.

Services: Coarse-grained Communication: ESB / Message Bus Data: Often shared DB Context: Large enterprise

SOA vs Microservices

Service size: SOA services are coarser — "OrderManagementService" vs micro's "order-service"
Communication: SOA uses ESB (Enterprise Service Bus) — often SOAP/XML or proprietary
Data sharing: SOA often allows shared databases between services
Governance: SOA has heavy central governance; microservices are autonomous
Technology: SOA often mixed with Java EE, BPEL, WSDL

When SOA in Go?

Modern Go teams rarely build classic SOA but may integrate with enterprise SOA systems. Go services often serve as lightweight, performant adapters to legacy SOA — exposing modern REST/gRPC endpoints while consuming legacy SOAP/XML services internally. A Go API gateway might sit in front of a Java ESB.

Suitability

✓ Large enterprise (banks, telcos) ✓ Legacy system integration ✓ Government IT systems ~ ERP integration middleware ✗ Greenfield projects ✗ Startup / small team Enterprise ✓

Go in SOA Context

Go as lightweight API gateway / facade over legacy services
Go adapter translating REST → SOAP for legacy consumers
Go service consuming Kafka/ActiveMQ ESB messages
Go replacing a slow Java service in an existing SOA ecosystem
Using encoding/xml for SOAP parsing in Go

🏦

Banking Core System Integration

A major bank runs 20-year-old COBOL core banking on an IBM mainframe. New Go-based mobile banking API sits in front: Go service exposes modern REST JSON API to mobile apps, internally calls the legacy SOAP-based CoreBanking ESB via XML. Go handles authentication (JWT), rate limiting, response caching, modern error handling — while the SOA layer handles actual account transactions. This is the most common "Go in SOA" pattern in enterprise.

Legacy BridgeSOAP/XML AdapterESB IntegrationGo REST Facade

✓ ADVANTAGES

Reuse existing enterprise services
Central governance and service catalog
Works with existing legacy infrastructure
SOAP services have strong typing (WSDL contracts)
Mature tooling in enterprise environments

✗ DISADVANTAGES

ESB is a single point of failure and bottleneck
Heavy XML/SOAP overhead vs gRPC/JSON
Tight coupling through shared bus
Slow to change — central governance slows evolution
Not cloud-native — hard to containerize ESB

Architecture 10 · Structural / Philosophical

Domain-Driven Design (DDD)

🌐

Domain-Driven Design (DDD)

Structural Philosophy · Eric Evans · Bounded Contexts

DDD is not a single architecture but a philosophy for modeling software around the business domain. The model reflects how domain experts think. Bounded Contexts divide the domain into explicit boundaries — each with its own model, language, and Go package/service. Often combined with Clean/Hexagonal Architecture.

Focus: Business domain modeling Key: Ubiquitous Language Unit: Bounded Context Pairs with: Clean, Hexagonal, CQRS

Core DDD Concepts in Go

Entity: Go struct with identity — Order{ID string}. Same ID = same entity.
Value Object: Immutable, no identity — Money{Amount, Currency}. Equal by value.
Aggregate: Cluster of entities with one root — Order containing OrderItems.
Repository: Go interface for aggregate persistence.
Domain Service: Business logic that doesn't belong to one entity.
Domain Event: OrderPlaced, PaymentFailed — things that happened.

Bounded Contexts

Different parts of the system have different models of the same concept. In an e-commerce app, Order in the Shopping Context has cart items and discounts. Order in the Fulfillment Context has warehouse locations and picking status. Order in the Billing Context has invoice numbers and payment terms. DDD says: keep these models separate. Don't unify them.

Ubiquitous Language

Domain experts and developers use the same words in code. If the chef calls it a "Kitchen Ticket" — your struct is KitchenTicket, not OrderNotification. If accountants say "Invoice" — not "BillingDocument". This alignment reduces translation errors and makes code readable to domain experts. In Go, package names and type names should reflect domain language exactly.

DDD in Go — Practical

Each Bounded Context → separate Go package or service
Aggregates enforce invariants in their methods (not services)
Value objects use methods, not setters — immutable
Domain events emitted from aggregate root methods
Repository interface in domain package, implementation in infra
Anti-Corruption Layer (ACL) when integrating bounded contexts

ddd/domain/order_aggregate.go — Aggregate with Domain Events

package ordering // Package name = Bounded
            Context name

          // Value Object — immutable, no identity, equal by value
          type Money struct { amount int64; currency string } // unexported
            fields!

          func NewMoney(amount int64, currency
          string) (Money, error) {
          if amount < 0 { return Money{}, errors.New("amount cannot be
              negative") }
            return Money{amount, currency}, nil
            }
            func (m Money) Add(other Money) (Money, error) { /* validate currencies match */ }

            // Aggregate Root — enforces invariants for the entire aggregate
            type Order struct {
            id OrderID // identity
            items []OrderItem // child entities — only accessible via
              Order
            total Money // value object
            status OrderStatus
            events []DomainEvent // domain events accumulated during
              operation
            }

            // Business method on aggregate — enforces invariants
            func (o *Order) AddItem(item MenuItem, qty int) error {
            if o.status != StatusDraft {
            return errors.New("cannot add items to
              non-draft order")
            }
            if qty <= 0 { return errors.New("quantity must be positive") }
              o.items = append(o.items, OrderItem{MenuItem: item, Qty:
              qty})
              o.total, _ = o.total.Add(NewMoney(item.Price * int64(qty), "BDT"))
              return nil
              }

              func (o *Order) Place() error {
              if len(o.items) == 0 { return
              errors.New("order must have items") }
              o.status = StatusPlaced
              o.events = append(o.events, OrderPlacedEvent{OrderID:
              o.id})
              return nil
              // Aggregate emits events — repository publishes them after save
              }
        

✓ ADVANTAGES

Code directly reflects business domain — reduces translation errors
Aggregates enforce business invariants at the right layer
Bounded contexts prevent model corruption across domains
Natural fit with Clean Architecture and microservices
Domain logic is rich, testable, and framework-free
Ubiquitous language reduces developer/domain-expert gap

✗ DISADVANTAGES

Steep learning curve — concepts like Aggregates, Value Objects take time
Requires deep domain understanding (long discovery phase)
Over-engineering for CRUD-heavy, domain-lite applications
Lots of boilerplate (Value Objects, Events, Repositories)
Risk of modeling the domain incorrectly early on

🏥

Hospital Management System — Multiple Bounded Contexts

Patient Context: Patient aggregate — demographics, medical history, allergies. Appointment Context: Appointment aggregate — patient (just ID here, not full model), doctor, slot, status. Billing Context: Invoice aggregate — line items, insurance, payment. Each context has its own "Patient" concept — they don't share the model. Anti-Corruption Layers translate between them. Ubiquitous Language: doctors say "Ward Round" → code has WardRound struct, not DailyVisit.

Bounded ContextsUbiquitous LanguageAggregatesValue ObjectsDomain Events

Section 12 — Final Summary

Complete Architecture Comparison Table

Criteria	🏛️ Monolithic	🔬 Microservices	⚡ Event-Driven	🎯 Clean Arch	🥞 Layered	⬡ Hexagonal	⚖️ CQRS	☁️ Serverless	🕸️ SOA	🌐 DDD
Type	Structural	Deployment	Communication	Structural	Structural	Structural	Communication	Deployment	Deployment	Philosophy
Team Size	1–15	15–500+	Any (infra)	5–50	Any	5–50	15–100+	Any	50–1000+	10–200+
Project Size	Small Medium	Large Enterprise	Medium Large	Medium Large	Any	Medium Large	Large Enterprise	Small Medium	Enterprise	Medium Large
Setup Complexity	Very Low	Very High	High	Medium	Low	Medium-High	Very High	Low (FaaS managed)	Very High	Medium-High
Testability	~ Integration tests	~ Contract tests	~ Event simulation	✓✓ Unit + Integration	✓ Good with interfaces	✓✓ InMemory adapters	~ Two sides to test	✓ Local SAM/Invoke	✗ ESB hard to mock	✓✓ Domain unit tests
Horizontal Scaling	Limited (full copy)	✓✓ Per service	✓✓ Consumer groups	Depends on deploy	Depends on deploy	Depends on deploy	✓✓ Read/write separately	✓✓ Infinite auto	~ Service-level	Depends on deploy
Fault Isolation	✗ One crash = all down	✓✓ Per service	✓✓ Consumers independent	~ Depends on deploy	✗ Same as monolith	~ Depends on deploy	✓ Read/write isolated	✓✓ Function isolation	~ ESB = single point	~ Context isolation
Data Consistency	Strong (ACID)	Eventual (Saga)	Eventual	Strong (ACID)	Strong (ACID)	Strong (ACID)	Eventual (projections)	Per-function strong	Eventually	Strong within agg.
Debugging Ease	Excellent	Hard (tracing needed)	Hard (event chain)	Good	Good	Good	Medium	Medium (CloudWatch)	Hard	Good (rich model)
Local Dev Ease	One command	Docker Compose needed	Broker needed	One command	One command	One command	Two DBs locally	SAM CLI needed	ESB locally hard	Good
DevOps Requirement	Minimal	Advanced (K8s, mesh)	Medium (broker ops)	Minimal-Medium	Minimal	Minimal-Medium	Medium-Advanced	Minimal (cloud-managed)	Advanced (ESB)	Minimal-Medium
Best For (Industry)	Startup · MVP · Blog · CMS	Uber · Netflix · Amazon	Fintech · IoT · Stock	Long-lived SaaS · Enterprise	REST APIs · ERP · CRM	Multi-protocol · DDD apps	Search · Reporting · Analytics	Webhooks · Scheduled jobs	Banks · Telcos · Gov	Complex domain · Healthcare
Go Frameworks/Tools	Gin, Echo, Chi, GORM	gRPC, Consul, K8s	Kafka-go, NATS, RabbitMQ	Any (framework-agnostic)	Gin, Echo, sqlx	Any (clean interfaces)	Elasticsearch, Redis	aws-lambda-go, GCF SDK	encoding/xml, SOAP libs	Any + domain packages
ERP Suitability	~ Early stage	✓ Large ERP	~ Events addon	✓✓ Ideal structure	✓✓ Very common	✓ Good	✓ Reporting module	✗ Not suitable	✓ Integration layer	✓✓ Ideal for complex
Fintech Suitability	~ Only small scale	✓✓ Per-domain services	✓✓ Transaction events	✓✓ Auditable clean code	✓ Good baseline	✓✓ Swap payment providers	✓✓ Reporting + transactions	~ Specific functions	✓ Legacy integration	✓✓ Rich financial domain
SaaS Suitability	✓✓ Early SaaS	✓ At scale	~ Feature-specific	✓✓ Best for longevity	✓✓ Default choice	✓ Good	~ When needed	✓ Background tasks	✗	✓ Complex domains
Overall Complexity	★☆☆☆☆	★★★★★	★★★★☆	★★★☆☆	★★☆☆☆	★★★☆☆	★★★★★	★★☆☆☆	★★★★★	★★★★☆

🎯 Final Architecture Decision Guide

🏛️ START HERE → Monolithic Default for any new project. Fastest to ship. Migrate to microservices when team/scale demands it. "Monolith-first" is the proven strategy.

🥞 MOST COMMON → Layered Architecture Handler → Service → Repository is the default Go REST API structure. Simple, understood by all, works at any scale with discipline.

🎯 BEST INVESTMENT → Clean / Hexagonal For systems that will live 3+ years. Higher upfront cost, massive long-term maintainability payoff. Maximum testability.

🔬 AT SCALE → Microservices When team size, deployment frequency, or independent scaling demands it. Never start here — extract from a monolith.

⚡ FOR REACTIVITY → Event-Driven When one action must trigger many reactions at scale. Combine with microservices. Use Kafka for durability, NATS for speed.

⚖️ FOR READS → CQRS When read and write workloads are fundamentally different. E-commerce search + order, analytics dashboards, fintech reporting.

☁️ FOR EVENTS → Serverless Webhooks, scheduled tasks, background processing, bursty workloads. Go's fast cold start makes it ideal for Lambda.

🌐 FOR COMPLEXITY → DDD When the domain is complex and the business model must drive the code structure. Pairs with Clean/Hexagonal. Not for CRUD apps.

10 Production-Grade Go ArchitecturesFully Mastered

What Is It?

Characteristics

How It Works (Go)

HTTP Request enters

Handler layer

Service / Business layer

Repository / Data layer

Complexity & Scale Metrics

Project Suitability

⚠ BOTTLENECKS & KNOWN ISSUES

✓ ADVANTAGES

✗ DISADVANTAGES

What Is It?

Core Principles

Key Requirements

Complexity Metrics

Project Suitability

⚠ BOTTLENECKS & DISTRIBUTED SYSTEM CHALLENGES

✓ ADVANTAGES

✗ DISADVANTAGES

Core Concepts

How It Works

Action triggers event

Broker persists event

Consumers react independently

Each consumer may produce

EDA Styles in Go

Complexity Metrics

✓ ADVANTAGES

✗ DISADVANTAGES

The 4 Layers (Go)

The Dependency Rule

Go Folder Structure

Complexity Metrics

✓ ADVANTAGES

✗ DISADVANTAGES

The 4-Layer Go Stack

Rules

vs. Clean Architecture

Suitability

✓ ADVANTAGES

✗ DISADVANTAGES

Ports vs Adapters

vs Clean Architecture

Key Benefits

Suitability

✓ ADVANTAGES

✗ DISADVANTAGES

The Core Split

Why Separate?

Suitability

Complexity Metrics

✓ ADVANTAGES

✗ DISADVANTAGES

How It Works

Go's Advantage for Serverless

Best Use Cases

Suitability

✓ ADVANTAGES

✗ DISADVANTAGES

SOA vs Microservices

When SOA in Go?

Suitability

Go in SOA Context

✓ ADVANTAGES

✗ DISADVANTAGES

Core DDD Concepts in Go

Bounded Contexts

Ubiquitous Language

DDD in Go — Practical

✓ ADVANTAGES

✗ DISADVANTAGES

🎯 Final Architecture Decision Guide

10 Production-Grade Go Architectures
Fully Mastered