Service-Based Architecture #

// ✓ Each service only accesses tables it "owns"
// Table ownership is defined explicitly

// User Service: owns the users, user_profiles, user_sessions tables
// Order Service: owns the orders, order_items, order_status_history tables
// Payment Service: owns the payments, payment_methods, refunds tables
// Notification Service: owns the notifications, notification_templates tables

// user-service/internal/repository/user_repo.go
package repository

// UserRepo only accesses tables owned by the User Service
type UserRepo struct {
	db *sql.DB
}

func (r *UserRepo) FindByID(ctx context.Context, id string) (*User, error) {
	var u User
	err := r.db.QueryRowContext(ctx,
		`SELECT id, full_name, email, is_active FROM users WHERE id = $1`, id,
	).Scan(&u.ID, &u.FullName, &u.Email, &u.IsActive)
	return &u, err
}

// ✗ DON'T: the User Service accessing the orders table
func (r *UserRepo) GetUserOrders(ctx context.Context, userID string) ([]Order, error) {
	// ✗ This is wrong coupling — the User Service does not own the orders table
	rows, _ := r.db.QueryContext(ctx,
		`SELECT id, total FROM orders WHERE user_id = $1`, userID,
	)
	_ = rows
	return nil, nil
}

// Table ownership strategy: define it explicitly in documentation and code

// db/ownership.go — a dedicated package documenting table ownership
package db

// TableOwnership defines which service "owns" each table
// Other services must not write to these tables, and ideally should not read them directly
var TableOwnership = map[string]string{
	"users":                   "user-service",
	"user_profiles":           "user-service",
	"user_sessions":           "user-service",
	"orders":                  "order-service",
	"order_items":             "order-service",
	"order_status_history":    "order-service",
	"payments":                "payment-service",
	"payment_methods":         "payment-service",
	"refunds":                 "payment-service",
	"notifications":           "notification-service",
	"notification_templates":  "notification-service",
}

// order-service/main.go
package main

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

	_ "github.com/lib/pq"
)

func main() {
	// Read config from environment variables — each service has its own config
	dbURL := os.Getenv("DATABASE_URL")
	userServiceURL := os.Getenv("USER_SERVICE_URL")
	port := os.Getenv("PORT")
	if port == "" {
		port = "8082"
	}

	db, err := sql.Open("postgres", dbURL)
	if err != nil {
		log.Fatal("db connection failed:", err)
	}
	defer db.Close()

	// Initialize layers — the same as a monolith but per service
	repo := repository.NewOrderRepository(db)
	userClient := client.NewUserServiceClient(userServiceURL)
	svc := service.NewOrderService(repo, userClient)
	handler := handler.NewOrderHandler(svc)

	mux := http.NewServeMux()
	handler.RegisterRoutes(mux)

	log.Printf("Order Service running on :%s", port)
	log.Fatal(http.ListenAndServe(":"+port, mux))
}

// order-service/internal/service/order_service.go
package service

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

// UserClient is the interface for calling the User Service
// ✓ Each service defines interfaces for its dependencies
type UserClient interface {
	ValidateActive(ctx context.Context, userID string) error
	GetName(ctx context.Context, userID string) (string, error)
}

// OrderRepository is the data access interface
type OrderRepository interface {
	Save(ctx context.Context, order *Order) error
	FindByID(ctx context.Context, id string) (*Order, error)
	FindByUserID(ctx context.Context, userID string) ([]*Order, error)
	UpdateStatus(ctx context.Context, id string, status OrderStatus) error
}

type OrderService struct {
	repo       OrderRepository
	userClient UserClient
}

func NewOrderService(repo OrderRepository, userClient UserClient) *OrderService {
	return &OrderService{repo: repo, userClient: userClient}
}

// PlaceOrder is the main use case of the Order Service
func (s *OrderService) PlaceOrder(ctx context.Context, input PlaceOrderInput) (*OrderOutput, error) {
	// Validate the user via the User Service — inter-service communication
	if err := s.userClient.ValidateActive(ctx, input.UserID); err != nil {
		return nil, errors.New("invalid user: " + err.Error())
	}

	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 := &Order{
		ID:         generateID(),
		UserID:     input.UserID,
		Status:     StatusPending,
		Items:      items,
		TotalCents: total,
		CreatedAt:  time.Now(),
	}

	// Save to the shared database — because it is a shared DB, ACID is possible
	if err := s.repo.Save(ctx, order); err != nil {
		return nil, err
	}

	return &OrderOutput{
		OrderID:    order.ID,
		Status:     string(order.Status),
		TotalCents: order.TotalCents,
	}, nil
}

// order-service/internal/client/user_client.go
// Client for calling the User Service via HTTP
package client

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

type UserServiceClient struct {
	baseURL    string
	httpClient *http.Client
}

func NewUserServiceClient(baseURL string) *UserServiceClient {
	return &UserServiceClient{
		baseURL: baseURL,
		httpClient: &http.Client{
			Timeout: 3 * time.Second, // ✓ always a timeout
		},
	}
}

type userResponse struct {
	ID       string `json:"id"`
	FullName string `json:"full_name"`
	IsActive bool   `json:"is_active"`
}

func (c *UserServiceClient) ValidateActive(ctx context.Context, userID string) error {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
		fmt.Sprintf("%s/users/%s", c.baseURL, userID), nil)
	if err != nil {
		return err
	}

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return fmt.Errorf("user service unavailable: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusNotFound {
		return fmt.Errorf("user %s not found", userID)
	}
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("user service error: status %d", resp.StatusCode)
	}

	var user userResponse
	if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
		return err
	}

	if !user.IsActive {
		return fmt.Errorf("user %s is inactive", userID)
	}
	return nil
}

func (c *UserServiceClient) GetName(ctx context.Context, userID string) (string, error) {
	req, _ := http.NewRequestWithContext(ctx, http.MethodGet,
		fmt.Sprintf("%s/users/%s", c.baseURL, userID), nil)
	resp, err := c.httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	var user userResponse
	json.NewDecoder(resp.Body).Decode(&user)
	return user.FullName, nil
}

// order-service/internal/repository/order_repo.go
// Example: PlaceOrder + UpdateInventory in one ACID transaction
// This is IMPOSSIBLE in microservices without a complex saga

func (r *OrderRepository) PlaceOrderWithInventory(
	ctx context.Context,
	order *Order,
	productID string,
	quantity int,
) error {
	tx, err := r.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}
	defer tx.Rollback()

	// Insert the order
	_, err = tx.ExecContext(ctx,
		`INSERT INTO orders (id, user_id, status, total_cents, created_at)
		 VALUES ($1, $2, $3, $4, NOW())`,
		order.ID, order.UserID, order.Status, order.TotalCents,
	)
	if err != nil {
		return fmt.Errorf("failed to insert order: %w", err)
	}

	// Update inventory — a table owned by the "inventory domain" but in the same DB
	// ✓ In SBA this is valid — one DB, one transaction
	result, err := tx.ExecContext(ctx,
		`UPDATE products SET stock = stock - $1
		 WHERE id = $2 AND stock >= $1`,
		quantity, productID,
	)
	if err != nil {
		return fmt.Errorf("failed to update inventory: %w", err)
	}

	rows, _ := result.RowsAffected()
	if rows == 0 {
		return errors.New("insufficient stock")
	}

	return tx.Commit()
}

// ✗ A service directly querying another service's database
// order-service accesses tables owned by user-service
func (r *OrderRepo) GetOrderWithUserDetails(ctx context.Context, orderID string) (*OrderDetail, error) {
	// ✗ The ORDER service directly JOINs USER tables — direct database coupling
	row := r.db.QueryRowContext(ctx, `
		SELECT o.id, o.total_cents, u.full_name, u.email
		FROM orders o
		JOIN users u ON u.id = o.user_id  -- ✗ the users table is not owned by order-service
		WHERE o.id = $1
	`, orderID)
	_ = row
	return nil, nil
}

// ✓ Fetch user data via API, not via DB JOINs
func (s *OrderService) GetOrderWithUserDetails(ctx context.Context, orderID string) (*OrderDetail, error) {
	order, err := s.repo.FindByID(ctx, orderID)
	if err != nil {
		return nil, err
	}

	// ✓ Fetch the user data from the User Service via HTTP API
	userName, err := s.userClient.GetName(ctx, order.UserID)
	if err != nil {
		userName = "Unknown" // ✓ graceful degradation
	}

	return &OrderDetail{
		OrderID:    order.ID,
		UserName:   userName,
		TotalCents: order.TotalCents,
	}, nil
}

// ✗ No timeout on inter-service calls — goroutines wait forever
func (c *UserClient) GetUser(ctx context.Context, id string) (*User, error) {
	resp, err := http.Get(c.baseURL + "/users/" + id) // ✗ no timeout!
	_ = resp
	return nil, err
}

// ✓ Always a timeout — either on the context or on the http.Client
func (c *UserClient) GetUser(ctx context.Context, id string) (*User, error) {
	ctx, cancel := context.WithTimeout(ctx, 2*time.Second) // ✓ bounded wait
	defer cancel()

	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/users/"+id, nil)
	resp, err := c.http.Do(req)
	_ = resp
	return nil, err
}

// ✗ Another service writing directly to tables owned by a different service
// notification-service writes directly to the orders table
func (n *NotificationService) MarkOrderNotified(ctx context.Context, orderID string) error {
	// ✗ notification-service must not write to the orders table
	_, err := n.db.ExecContext(ctx,
		`UPDATE orders SET notified = TRUE WHERE id = $1`, orderID,
	)
	return err
}

// ✓ Use an API to ask the owning service to perform the update
func (n *NotificationService) MarkOrderNotified(ctx context.Context, orderID string) error {
	// ✓ Send a request to the Order Service to update the notification status
	return n.orderClient.MarkNotified(ctx, orderID)
}