Layered Architecture & MV*

Layered architecture organises code into horizontal slabs — presentation, application, domain, infrastructure — where each layer only talks to the one directly below it. MV* (MVC, MVP, MVVM) is the same idea applied to UI: separate what you see from what you do from what you store. This is the pattern most developers learn first, and the one they apply whether it fits or not.

It works because it maps cleanly to how teams think. Handlers handle. Services orchestrate. Repositories persist. The pattern earns its reputation early — on a greenfield codebase with a small team and a clear domain, it's genuinely productive.

It breaks in a specific and predictable way. The domain model — the User, the Invoice, the Order — becomes a passive data container. Methods drift. Validation logic that belongs on the model ends up in the service because the service is where engineers spend their time. Business rules that should be enforced at the domain level leak into HTTP handlers because that's where the request context lives. Six months later you have a UserService with twelve methods, a User struct with no methods, and handlers that know too much about business logic. The layers are still there. They're just not doing what they were supposed to do.

// repository.go — data access only, no business logic
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, u *User) error
}

// service.go — business logic, not pass-through boilerplate
type UserService struct{ repo UserRepository }

func (s *UserService) Activate(ctx context.Context, id string) error {
    u, err := s.repo.FindByID(ctx, id)
    if err != nil { return err }
    u.Activate() // domain logic lives on the model, not in the service
    return s.repo.Save(ctx, u)
}

// handler.go — HTTP concerns only, zero business logic
func (h *Handler) ActivateUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    if err := h.svc.Activate(r.Context(), id); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

Event-Driven Architecture & CQRS

Event-Driven Architecture models the system as a stream of things that happened rather than things that should be done. Components emit events; other components react. CQRS — Command Query Responsibility Segregation — is a natural companion: separate the write model (commands that change state) from the read model (queries optimised for display). Neither is inherently tied to the other, but they're commonly paired because an event log makes it trivial to maintain multiple read projections.

This is the pattern that solves real problems — audit logs, temporal decoupling, independent scaling of read and write paths — and creates real problems: eventual consistency becomes a product requirement, your debugging surface area multiplies, and onboarding a new engineer into a pure event-sourced system is a multi-day exercise. Go in with eyes open.

// command.go — write side: intent to change state
type Command interface{ CommandName() string }

type ActivateUserCmd struct{ UserID string }
func (ActivateUserCmd) CommandName() string { return "user.activate" }

type CommandBus struct{ handlers map[string]func(context.Context, Command) error }

func (b *CommandBus) Dispatch(ctx context.Context, cmd Command) error {
    h, ok := b.handlers[cmd.CommandName()]
    if !ok { return fmt.Errorf("no handler: %s", cmd.CommandName()) }
    return h(ctx, cmd)
}

// event.go — something that happened (immutable fact)
type UserActivated struct{
    UserID     string
    OccurredAt time.Time
}

// projection.go — read side, optimised purely for queries
type ActiveUsersProjection struct{
    mu    sync.RWMutex
    users map[string]bool
}

func (p *ActiveUsersProjection) On(e UserActivated) {
    p.mu.Lock(); defer p.mu.Unlock()
    p.users[e.UserID] = true
}
func (p *ActiveUsersProjection) IsActive(id string) bool {
    p.mu.RLock(); defer p.mu.RUnlock()
    return p.users[id]
}

Microkernel

Microkernel is the pattern you reach for when you've shipped version one of your product and discovered that your biggest customers all want something slightly different. Not "different design" different. "Different compliance rules, different data sources, different notification channels, different everything at the edges while the core logic stays identical" different. That's the specific problem microkernel solves — and it solves it better than any alternative.

The core defines a contract. Extensions implement it. The core doesn't care how many extensions exist, who wrote them, or what they do internally. VS Code's language server protocol is microkernel. Jenkins' build pipeline is microkernel. The SafeOps365 notification and reporting system is microkernel — because an energy operator in Aberdeen has different alerting requirements than one in Texas, and those differences should never live in an if statement in the core codebase.

The failure mode is specific: teams apply microkernel to their own internal variation and discover they've built a framework nobody asked for. If every plugin is written by your team, for your own product, you don't need a plugin system — you need a well-factored package. Microkernel earns its overhead when the extension boundary is a real organisational boundary: a customer, a third party, a team that deploys independently.

// plugin.go — the contract the core enforces
type Plugin interface {
    Name()    string
    Version() string
    Init(cfg map[string]string) error
}

type NotifierPlugin interface {
    Plugin
    Notify(ctx context.Context, event string, payload any) error
}

// registry.go — the core kernel: stable, minimal
type Registry struct{ notifiers map[string]NotifierPlugin }

func (r *Registry) Register(p NotifierPlugin, cfg map[string]string) error {
    if err := p.Init(cfg); err != nil { return err }
    r.notifiers[p.Name()] = p
    return nil
}

func (r *Registry) Broadcast(ctx context.Context, event string, payload any) {
    for _, n := range r.notifiers {
        if err := n.Notify(ctx, event, payload); err != nil {
            log.Printf("plugin %s error: %v", n.Name(), err)
        }
    }
}

// slack_plugin.go — an extension; the core never imports this package
type SlackNotifier struct{ webhookURL string }

func (SlackNotifier) Name()    string { return "slack" }
func (SlackNotifier) Version() string { return "1.0.0" }
func (s *SlackNotifier) Init(cfg map[string]string) error {
    s.webhookURL = cfg["webhook_url"]; return nil
}

Microservices Architecture

Microservices decomposes the system into small, independently deployable services each owning a single bounded context. Each service has its own data store, exposes an API, and is deployed, scaled, and versioned independently. Amazon, Netflix, and Uber did it. Half the industry followed without having Amazon's engineering headcount or Netflix's traffic.

The productivity argument goes: independent deployment means independent teams moving fast. The reality is that distributed systems introduce failure modes — network partitions, partial failures, cascading timeouts — that simply don't exist in a monolith. You've traded simple in-process function calls for network I/O, serialisation, service discovery, distributed tracing, and coordinated deployments. Do that trade consciously, not by default.

// server.go — owns its own data, exposes its own API
type Server struct{ addr string; store NotificationStore }

func (s *Server) routes() http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("POST /v1/notifications", s.create)
    mux.HandleFunc("GET /v1/notifications/{id}", s.get)
    mux.HandleFunc("GET /healthz", s.health)
    return mux
}

func (s *Server) Run(ctx context.Context) error {
    srv := &http.Server{
        Addr: s.addr, Handler: s.routes(),
        ReadTimeout: 5 * time.Second, WriteTimeout: 10 * time.Second,
    }
    go func() { <-ctx.Done(); srv.Shutdown(context.Background()) }()
    return srv.ListenAndServe()
}

// client.go — calling this service from another service
type NotificationClient struct{ base string; http *http.Client }

func (c *NotificationClient) Send(ctx context.Context, n Notification) error {
    b, _ := json.Marshal(n)
    req, _ := http.NewRequestWithContext(ctx, http.MethodPost,
        c.base+"/v1/notifications", bytes.NewReader(b))
    req.Header.Set("Content-Type", "application/json")
    resp, err := c.http.Do(req)
    if err != nil { return err }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusCreated {
        return fmt.Errorf("notification service: %d", resp.StatusCode)
    }
    return nil
}

Monolithic Architecture

A monolith is a single deployable unit. Everything — API, business logic, data access, background jobs — runs in one process. The word has become a pejorative, which tells you more about the industry's fashion cycle than about the pattern's merit. GitHub was a monolith for years. Basecamp still is. Shopify ran on a Rails monolith until they had very good reasons to change it.

The monolith's sins are mostly sins of undisciplined development, not of the pattern itself. A well-structured monolith is simpler to develop, deploy, debug, and reason about than a premature microservices architecture. If your team is spending more time on infrastructure than product features, the monolith deserves a serious re-evaluation.

// main.go — one binary, everything wired in one place
func main() {
    cfg := loadConfig()

    db, err := sql.Open("pgx", cfg.DatabaseURL)
    if err != nil { log.Fatal(err) }

    userRepo    := postgres.NewUserRepo(db)
    invoiceRepo := postgres.NewInvoiceRepo(db)
    mailer      := smtp.NewMailer(cfg.SMTP)

    userSvc    := user.NewService(userRepo, mailer)
    invoiceSvc := invoice.NewService(invoiceRepo, userSvc)

    mux := http.NewServeMux()
    user.RegisterRoutes(mux, userSvc)
    invoice.RegisterRoutes(mux, invoiceSvc)

    go jobs.RunInvoiceReminders(invoiceSvc) // background work, same process

    log.Fatal((&http.Server{Addr: cfg.Addr, Handler: mux}).ListenAndServe())
}

Modular Monolith

The modular monolith is a monolith with enforced internal boundaries. Each module owns its domain, exposes a public API, hides its internals, and refuses to let other modules reach into its database tables. It deploys as a single binary. It develops as if it were multiple services. You get the operational simplicity of a monolith and the organisational structure of microservices — without the distributed systems tax.

This is the pattern that Sam Newman — who literally wrote the book on microservices — now recommends as a starting point. When the seams become load-bearing and a module needs to scale independently, you extract it into a service. The modular monolith is the precondition for a clean microservices migration, not a consolation prize.

// internal/billing/service.go — billing's public contract
// Nothing outside this package tree can import billing's internals
package billing

type Service interface {
    CreateInvoice(ctx context.Context, req InvoiceRequest) (Invoice, error)
    GetInvoice(ctx context.Context, id string) (Invoice, error)
}

// InvoiceRequest is billing's public input — other modules construct this
type InvoiceRequest struct{
    CustomerID string
    LineItems  []LineItem
}

// internal/billing/postgres.go — private to billing, invisible outside
type invoiceRow struct{
    id, customerID string
    total          int64
    createdAt      time.Time
}

// app/wire.go — modules communicate through interfaces, never internals
func Wire(db *sql.DB) http.Handler {
    // each module owns its own schema — no cross-module table access
    users   := user.NewService(db)
    billing := billing.NewService(db)
    orders  := order.NewService(db, billing) // interface dep, not internals

    mux := http.NewServeMux()
    user.RegisterRoutes(mux, users)
    billing.RegisterRoutes(mux, billing)
    order.RegisterRoutes(mux, orders)
    return mux
}