Modular Monolith Architecture #

// internal/user/api.go — the public API of the User module
// This is the only file other modules are allowed to import
package user

import "context"

// API is the public contract of the User module
// ✓ Other modules depend on this interface, not its implementation
type API interface {
	GetByID(ctx context.Context, id string) (*UserDTO, error)
	ValidateActive(ctx context.Context, id string) error
	GetFullName(ctx context.Context, id string) (string, error)
}

// UserDTO is the DTO shared with other modules
// ✓ Not the internal domain entity — only a data transfer object
type UserDTO struct {
	ID       string
	FullName string
	Email    string
	IsActive bool
}

// Module is the User module entry point exposing its API
type Module struct {
	api     *service  // internal implementation, not exposed
	handler *handler
}

func NewModule(db *sql.DB) *Module {
	repo := newPostgresRepository(db)
	svc := newService(repo)
	h := newHandler(svc)
	return &Module{api: svc, handler: h}
}

// API returns the implementation of the API interface
// ✓ The return type is an interface, not *service
func (m *Module) API() API {
	return m.api
}

// RegisterRoutes registers this module's HTTP routes
func (m *Module) RegisterRoutes(mux *http.ServeMux) {
	mux.HandleFunc("POST /users", m.handler.create)
	mux.HandleFunc("GET /users/{id}", m.handler.getByID)
	mux.HandleFunc("PUT /users/{id}/deactivate", m.handler.deactivate)
}

// internal/user/service.go — internal implementation, NOT exposed to other modules
package user

import (
	"context"
	"errors"
	"time"
)

// service implements the API interface
// This is the internal implementation detail of the User module
type service struct {
	repo repository
}

func newService(repo repository) *service {
	return &service{repo: repo}
}

// GetByID implements API.GetByID
func (s *service) GetByID(ctx context.Context, id string) (*UserDTO, error) {
	u, err := s.repo.findByID(ctx, id)
	if err != nil {
		return nil, err
	}
	return &UserDTO{
		ID:       u.id,
		FullName: u.fullName,
		Email:    u.email,
		IsActive: u.isActive,
	}, nil
}

// ValidateActive implements API.ValidateActive
func (s *service) ValidateActive(ctx context.Context, id string) error {
	u, err := s.repo.findByID(ctx, id)
	if err != nil {
		return err
	}
	if !u.isActive {
		return errors.New("user is inactive")
	}
	return nil
}

func (s *service) GetFullName(ctx context.Context, id string) (string, error) {
	u, err := s.repo.findByID(ctx, id)
	if err != nil {
		return "", err
	}
	return u.fullName, nil
}

// user is the INTERNAL domain entity — not exposed to the outside
type user struct {
	id        string
	fullName  string
	email     string
	isActive  bool
	createdAt time.Time
}

func (u *user) deactivate() error {
	if !u.isActive {
		return errors.New("user is already inactive")
	}
	u.isActive = false
	return nil
}

// internal/shared/eventbus/eventbus.go — shared component
package eventbus

import (
	"context"
	"fmt"
	"sync"
)

// Event is the interface for all domain events
type Event interface {
	EventName() string
}

// Handler is the function handling an event
type Handler func(ctx context.Context, event Event) error

// EventBus is an in-process event bus for inter-module communication
type EventBus struct {
	mu       sync.RWMutex
	handlers map[string][]Handler
}

func New() *EventBus {
	return &EventBus{
		handlers: make(map[string][]Handler),
	}
}

// Subscribe registers a handler for a specific event
func (b *EventBus) Subscribe(eventName string, handler Handler) {
	b.mu.Lock()
	defer b.mu.Unlock()
	b.handlers[eventName] = append(b.handlers[eventName], handler)
}

// Publish publishes an event to all subscribers
// ✓ The publisher does not know who the subscribers are
func (b *EventBus) Publish(ctx context.Context, event Event) error {
	b.mu.RLock()
	handlers := b.handlers[event.EventName()]
	b.mu.RUnlock()

	var errs []error
	for _, handler := range handlers {
		if err := handler(ctx, event); err != nil {
			errs = append(errs, err)
		}
	}
	if len(errs) > 0 {
		return fmt.Errorf("%d handlers failed to process event %s", len(errs), event.EventName())
	}
	return nil
}

// internal/order/events.go — domain events published by the Order module
package order

import "time"

// OrderPlacedEvent is published when an order is successfully created
// ✓ Other modules (notification, inventory) subscribe to this event
type OrderPlacedEvent struct {
	OrderID    string
	CustomerID string
	TotalCents int64
	Items      []OrderItemEvent
	OccurredAt time.Time
}

type OrderItemEvent struct {
	ProductID string
	Quantity  int
}

func (e OrderPlacedEvent) EventName() string { return "order.placed" }

// OrderCancelledEvent is published when an order is cancelled
type OrderCancelledEvent struct {
	OrderID    string
	CustomerID string
	Reason     string
	OccurredAt time.Time
}

func (e OrderCancelledEvent) EventName() string { return "order.cancelled" }

// internal/order/service.go — the Order module uses the User API and EventBus
package order

import (
	"context"
	"errors"
	"time"

	"myapp/internal/shared/eventbus"
	"myapp/internal/user" // ✓ only imports the user package for its types
)

type Service struct {
	repo     Repository
	userAPI  user.API       // ✓ interface from the User module, not a concrete struct
	eventBus *eventbus.EventBus
}

func NewService(repo Repository, userAPI user.API, bus *eventbus.EventBus) *Service {
	return &Service{repo: repo, userAPI: userAPI, eventBus: bus}
}

type PlaceOrderInput struct {
	CustomerID string
	Items      []PlaceOrderItem
}

type PlaceOrderItem struct {
	ProductID  string
	Quantity   int
	PriceCents int64
}

func (s *Service) PlaceOrder(ctx context.Context, input PlaceOrderInput) (*Order, error) {
	// Validate the customer via the User module API
	if err := s.userAPI.ValidateActive(ctx, input.CustomerID); err != nil {
		return nil, errors.New("invalid customer: " + err.Error())
	}

	// Create the order
	order := &Order{
		ID:         generateID(),
		CustomerID: input.CustomerID,
		Status:     StatusPending,
		CreatedAt:  time.Now(),
	}

	total := int64(0)
	items := make([]OrderItem, len(input.Items))
	for i, item := range input.Items {
		items[i] = OrderItem{
			ProductID:  item.ProductID,
			Quantity:   item.Quantity,
			PriceCents: item.PriceCents,
		}
		total += item.PriceCents * int64(item.Quantity)
	}
	order.Items = items
	order.TotalCents = total

	if err := s.repo.Save(ctx, order); err != nil {
		return nil, err
	}

	// Publish the event — the Notification and Inventory modules will respond
	// ✓ Order does not know who subscribes
	eventItems := make([]OrderItemEvent, len(items))
	for i, item := range items {
		eventItems[i] = OrderItemEvent{ProductID: item.ProductID, Quantity: item.Quantity}
	}
	_ = s.eventBus.Publish(ctx, OrderPlacedEvent{
		OrderID:    order.ID,
		CustomerID: order.CustomerID,
		TotalCents: order.TotalCents,
		Items:      eventItems,
		OccurredAt: time.Now(),
	})

	return order, nil
}

// internal/notification/module.go — the Notification module subscribes to Order events
package notification

import (
	"context"
	"fmt"

	"myapp/internal/order"
	"myapp/internal/shared/eventbus"
	"myapp/internal/user"
)

type Module struct {
	userAPI user.API
	bus     *eventbus.EventBus
}

func NewModule(userAPI user.API, bus *eventbus.EventBus) *Module {
	m := &Module{userAPI: userAPI, bus: bus}
	m.registerHandlers()
	return m
}

// registerHandlers registers all event handlers
// ✓ Notification subscribes to events from other modules without direct coupling
func (m *Module) registerHandlers() {
	m.bus.Subscribe("order.placed", m.handleOrderPlaced)
	m.bus.Subscribe("order.cancelled", m.handleOrderCancelled)
}

func (m *Module) handleOrderPlaced(ctx context.Context, event eventbus.Event) error {
	e, ok := event.(order.OrderPlacedEvent)
	if !ok {
		return fmt.Errorf("unexpected event type")
	}

	// Get the customer's name from the User module
	fullName, err := m.userAPI.GetFullName(ctx, e.CustomerID)
	if err != nil {
		return err
	}

	// Send the notification
	fmt.Printf("[Notification] Order %s created by %s, total: Rp%.2f\n",
		e.OrderID, fullName, float64(e.TotalCents)/100)
	return nil
}

func (m *Module) handleOrderCancelled(ctx context.Context, event eventbus.Event) error {
	e, ok := event.(order.OrderCancelledEvent)
	if !ok {
		return fmt.Errorf("unexpected event type")
	}
	fmt.Printf("[Notification] Order %s cancelled: %s\n", e.OrderID, e.Reason)
	return nil
}

// internal/order/internal/domain/order.go
// ✓ The "internal" sub-package can only be accessed within the order package
// The Go compiler prevents imports from outside
package domain

// Order is an internal module entity — inaccessible from outside the order module
type Order struct {
	id         string
	customerID string
	status     Status
	items      []Item
}

// Verify inter-module dependencies with a Go build tag
// Create file: internal/order/check_deps_test.go

//go:build deps_check

package order_test

import (
	// ✓ Allowed: importing shared packages
	_ "myapp/internal/shared/eventbus"

	// ✓ Allowed: importing another module's public API
	_ "myapp/internal/user"

	// ✗ Not allowed: importing another module's internal packages
	// _ "myapp/internal/user/internal/domain"  ← compiler error
	// _ "myapp/internal/payment/service"       ← compiler error
)

// cmd/server/main.go
package main

import (
	"database/sql"
	"log"
	"net/http"

	_ "github.com/lib/pq"

	"myapp/internal/notification"
	"myapp/internal/order"
	"myapp/internal/payment"
	"myapp/internal/shared/eventbus"
	"myapp/internal/user"
)

func main() {
	db, err := sql.Open("postgres", "postgres://localhost/myapp?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// Shared event bus — one for the whole application
	bus := eventbus.New()

	// Initialize modules — each module only receives the dependencies it needs
	userModule := user.NewModule(db)
	orderModule := order.NewModule(db, userModule.API(), bus)
	paymentModule := payment.NewModule(db, orderModule.API(), bus)
	notificationModule := notification.NewModule(userModule.API(), bus)

	// All modules ready — notification has already subscribed to events via its constructor

	// Set up the router
	mux := http.NewServeMux()
	userModule.RegisterRoutes(mux)
	orderModule.RegisterRoutes(mux)
	paymentModule.RegisterRoutes(mux)
	// notification has no HTTP routes — it is only an event subscriber

	_ = notificationModule // keep it in scope so it is not GC'd

	log.Println("Modular monolith running on :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

// ✗ Direct imports into another module's internals
package order

import "myapp/internal/user/service" // ✗ importing the user package's internals

func (s *Service) PlaceOrder(customerID string) error {
	// ✗ accessing the user module's internal implementation
	userSvc := service.NewUserService(s.db)
	user, _ := userSvc.FindByID(customerID)
	_ = user
	return nil
}

// ✓ Use the API interface exposed by the module
package order

func (s *Service) PlaceOrder(ctx context.Context, customerID string) error {
	// ✓ only using the public API interface
	if err := s.userAPI.ValidateActive(ctx, customerID); err != nil {
		return err
	}
	return nil
}

// ✗ Cross-schema database JOINs
// repository.go in the order module
func (r *repo) GetOrdersWithUserName(ctx context.Context) ([]OrderWithUser, error) {
	// ✗ JOIN into user_module tables — violates schema isolation
	return r.db.QueryContext(ctx, `
		SELECT o.id, o.total_cents, u.full_name
		FROM order_module.orders o
		JOIN user_module.users u ON u.id = o.customer_id
	`)
}

// ✓ Fetch data from other modules via API, not via JOINs
func (s *Service) GetOrdersWithUserName(ctx context.Context) ([]OrderDisplay, error) {
	orders, err := s.repo.FindAll(ctx)
	if err != nil {
		return nil, err
	}

	result := make([]OrderDisplay, len(orders))
	for i, order := range orders {
		name, _ := s.userAPI.GetFullName(ctx, order.CustomerID) // ✓ via API
		result[i] = OrderDisplay{OrderID: order.ID, CustomerName: name}
	}
	return result, nil
}

// ✗ Shared mutable state in event handlers — race condition
var processedEvents = map[string]bool{} // ✗ shared without a lock

func handleEvent(ctx context.Context, event eventbus.Event) error {
	processedEvents[event.EventName()] = true // ✗ data race
	return nil
}

// ✓ Use sync.Map or avoid shared state in event handlers
var processed sync.Map

func handleEventSafe(ctx context.Context, event eventbus.Event) error {
	processed.Store(event.EventName(), true) // ✓ thread-safe
	return nil
}