SSOT — Single Source of Truth #

// ANTI-PATTERN: user status redefined in every place that uses it
// Each claims authority over the meaning of "active user"

// order/handler.go
func canPlaceOrder(userStatus string) bool {
    return userStatus == "ACTIVE" // assumption: "ACTIVE" = active
}

// notification/worker.go
func shouldSendPromo(userStatus string) bool {
    return userStatus == "ENABLED" // different assumption: "ENABLED" = active
}

// billing/service.go
func canCharge(userStatus string) bool {
    return userStatus == "active" // case-sensitive typo that's syntactically valid
}

// report/query.go — direct SQL with string literals
// WHERE status = 'ACTIVE' OR status = 'enabled' -- emergency patch

// Result: four different "truths" about what an active user means
// Bug: a user with status "ENABLED" doesn't get promos,
//      but can place orders — technically valid inconsistency

// CORRECT: one definition, everyone uses the same one
// domain/user/status.go
package user

// Status is a typed string to prevent arbitrary string literals
type Status string

const (
    StatusActive    Status = "ACTIVE"
    StatusInactive  Status = "INACTIVE"
    StatusSuspended Status = "SUSPENDED"
    StatusPending   Status = "PENDING"
)

// IsActive becomes the single definition of "what it means to be active"
func (s Status) IsActive() bool {
    return s == StatusActive
}

// CanReceiveNotification is a domain rule attached to the status
func (s Status) CanReceiveNotification() bool {
    return s == StatusActive || s == StatusPending
}

// CanPlaceOrder is another domain rule
func (s Status) CanPlaceOrder() bool {
    return s == StatusActive
}

// IsValid validates that an externally received status is a known value
func (s Status) IsValid() bool {
    switch s {
    case StatusActive, StatusInactive, StatusSuspended, StatusPending:
        return true
    }
    return false
}

// All consumers use the same definition
// order/handler.go
func canPlaceOrder(u user.User) bool {
    return u.Status.CanPlaceOrder() // no string literals
}

// notification/worker.go
func shouldSendNotification(u user.User) bool {
    return u.Status.CanReceiveNotification() // the same definition
}

// billing/service.go
func canCharge(u user.User) bool {
    return u.Status.CanPlaceOrder() // consistent
}

// ANTI-PATTERN: business rules scattered without a single source

// order/service.go
func applyDiscount(price float64, userTier string) float64 {
    switch userTier {
    case "gold":
        return price * 0.85   // 15% discount
    case "platinum":
        return price * 0.75   // 25% discount
    default:
        return price
    }
}

// cart/service.go — thinks the rules are the same, but there's a subtle difference
func calculateCartTotal(items []Item, userTier string) float64 {
    total := 0.0
    for _, item := range items {
        total += item.Price
    }
    switch userTier {
    case "gold":
        return total * 0.80   // ← 20%, not 15%! Unintended divergence
    case "platinum":
        return total * 0.75
    default:
        return total
    }
}

// invoice/generator.go — a third version with yet another format
func applyMemberDiscount(subtotal float64, tier string) float64 {
    discountRates := map[string]float64{
        "gold":     0.15,
        "platinum": 0.25,
    }
    rate, ok := discountRates[tier]
    if !ok {
        return subtotal
    }
    return subtotal * (1 - rate)
}
// order and cart use multipliers, invoice uses rates — different ways, different numbers

// CORRECT: one domain model as the SSOT for all pricing rules

// domain/pricing/membership.go
package pricing

// MemberTier represents a membership tier with all its business rules
type MemberTier string

const (
    TierRegular  MemberTier = "regular"
    TierGold     MemberTier = "gold"
    TierPlatinum MemberTier = "platinum"
)

// DiscountRate is the only official definition of discount per tier
func (t MemberTier) DiscountRate() float64 {
    switch t {
    case TierGold:
        return 0.15 // 15% — the only place this number is defined
    case TierPlatinum:
        return 0.25 // 25% — the only place this number is defined
    default:
        return 0
    }
}

// Apply applies the discount to a price and returns the result with details
func (t MemberTier) Apply(price float64) DiscountResult {
    rate := t.DiscountRate()
    discount := price * rate
    return DiscountResult{
        OriginalPrice: price,
        DiscountRate:  rate,
        DiscountAmount: discount,
        FinalPrice:    price - discount,
    }
}

type DiscountResult struct {
    OriginalPrice  float64
    DiscountRate   float64
    DiscountAmount float64
    FinalPrice     float64
}

// All consumers use MemberTier.Apply() — no scattered magic numbers
// order/service.go
func processOrderDiscount(price float64, tier pricing.MemberTier) pricing.DiscountResult {
    return tier.Apply(price)
}

// cart/service.go
func calculateCartDiscount(total float64, tier pricing.MemberTier) pricing.DiscountResult {
    return tier.Apply(total)
}

// invoice/generator.go
func generateInvoiceDiscount(subtotal float64, tier pricing.MemberTier) pricing.DiscountResult {
    return tier.Apply(subtotal)
}
// When the gold discount changes to 20%, change one line in pricing/membership.go
// All services automatically use the new value

// ANTI-PATTERN: config scattered without a single source

// db/connection.go
func connectDB() *sql.DB {
    db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL"))
    db.SetMaxOpenConns(10)  // ← hardcoded, different in staging vs production
    db.SetConnMaxLifetime(5 * time.Minute) // ← inconsistent
    return db
}

// http/client.go
func newHTTPClient() *http.Client {
    return &http.Client{
        Timeout: 30 * time.Second, // ← different from the gRPC client timeout
    }
}

// grpc/client.go
func newGRPCConn() *grpc.ClientConn {
    ctx, _ := context.WithTimeout(context.Background(), 10*time.Second) // ← 10s, not 30s
    conn, _ := grpc.DialContext(ctx, grpcAddr, grpc.WithBlock())
    return conn
}

// queue/consumer.go
func newConsumer() *kafka.Reader {
    return kafka.NewReader(kafka.ReaderConfig{
        MaxWait:     3 * time.Second,
        MaxAttempts: 3, // ← different from the HTTP client's 5 retries
    })
}

// CORRECT: all config read from one struct, shared with every component

// config/config.go
package config

import (
    "time"
    "github.com/caarlos0/env/v11"
)

type Config struct {
    Database DatabaseConfig
    HTTP     HTTPConfig
    GRPC     GRPCConfig
    Queue    QueueConfig
}

type DatabaseConfig struct {
    DSN             string        `env:"DATABASE_URL,required"`
    MaxOpenConns    int           `env:"DB_MAX_OPEN_CONNS"    envDefault:"10"`
    MaxIdleConns    int           `env:"DB_MAX_IDLE_CONNS"    envDefault:"5"`
    ConnMaxLifetime time.Duration `env:"DB_CONN_MAX_LIFETIME" envDefault:"5m"`
}

type HTTPConfig struct {
    Timeout    time.Duration `env:"HTTP_TIMEOUT"     envDefault:"30s"`
    MaxRetries int           `env:"HTTP_MAX_RETRIES" envDefault:"3"`
}

type GRPCConfig struct {
    Timeout    time.Duration `env:"GRPC_TIMEOUT"     envDefault:"10s"`
    MaxRetries int           `env:"GRPC_MAX_RETRIES" envDefault:"3"`
}

type QueueConfig struct {
    Brokers     string        `env:"KAFKA_BROKERS,required"`
    MaxWait     time.Duration `env:"KAFKA_MAX_WAIT"     envDefault:"3s"`
    MaxAttempts int           `env:"KAFKA_MAX_ATTEMPTS" envDefault:"3"`
}

func Load() (*Config, error) {
    cfg := &Config{}
    if err := env.Parse(cfg); err != nil {
        return nil, fmt.Errorf("load config: %w", err)
    }
    return cfg, nil
}

// main.go: read once, inject into every component
func main() {
    cfg, err := config.Load()
    if err != nil {
        log.Fatal(err)
    }

    db := database.Connect(cfg.Database)
    httpClient := httpclient.New(cfg.HTTP)
    grpcConn := grpcclient.New(cfg.GRPC)
    consumer := queue.NewConsumer(cfg.Queue)
    // All use the same Config struct — one source of truth
}

// ANTI-PATTERN: request/response structs redefined in every communicating
// place — producer and consumer each have their own definition

// user-service/api/handler.go (producer)
type CreateUserResponse struct {
    ID        string `json:"id"`
    Name      string `json:"name"`
    Email     string `json:"email"`
    CreatedAt string `json:"created_at"` // ← string, not time.Time
}

// order-service/client/user_client.go (consumer)
type UserData struct {
    ID        string    `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"` // ← time.Time, will fail to unmarshal
    // the "email" field is sometimes empty but there's no nil check — latent bug
}

// Problems:
// - These two structs are never formally compared
// - If user-service adds a "phone" field, order-service doesn't know
// - Different createdAt formats → silent parse errors in production

// CORRECT: a shared contract in one package imported by everyone

// Option 1: a shared Go module (for internal monorepos)
// pkg/contract/user/v1/user.go
package userv1

import "time"

type CreateUserRequest struct {
    Name     string `json:"name"     validate:"required,min=2,max=100"`
    Email    string `json:"email"    validate:"required,email"`
    Password string `json:"password" validate:"required,min=8"`
}

type UserResponse struct {
    ID        string    `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

// user-service uses this contract for its responses
// order-service uses the same contract for parsing
// If the struct changes, all consumers get compile errors — not silent failures

// Option 2: protobuf/gRPC for services in different languages (more common)
// user.proto — one definition file, generates code for all languages

// A caching pattern that still respects SSOT
type UserCache struct {
    client  UserServiceClient
    cache   *redis.Client
    ttl     time.Duration
}

func (c *UserCache) GetUser(ctx context.Context, id string) (*User, error) {
    // Try the cache first
    cached, err := c.cache.Get(ctx, "user:"+id).Result()
    if err == nil {
        var u User
        json.Unmarshal([]byte(cached), &u)
        return &u, nil
    }

    // Cache miss: fetch from the SSOT (User Service)
    u, err := c.client.GetUser(ctx, id)
    if err != nil {
        return nil, err
    }

    // Store in cache with a TTL — not a permanent copy
    data, _ := json.Marshal(u)
    c.cache.Set(ctx, "user:"+id, data, c.ttl)
    return u, nil
}
// A cache is a performance optimization, not SSOT duplication
// The User Service remains the only source of truth for user data

// ANTI-PATTERN: the same error message in various variations
// handler A: "email already exists"
// handler B: "email already registered"
// service C: "duplicate email"
// repository D: "email constraint violation"
// All mean the same thing, but users get different messages

// CORRECT: defined sentinel errors with consistent messages

// domain/user/errors.go
package user

import "errors"

// Sentinel errors — SSOT for all user domain errors
var (
    ErrEmailAlreadyRegistered = errors.New("email already registered")
    ErrUserNotFound           = errors.New("user not found")
    ErrInvalidCredentials     = errors.New("invalid email or password")
    ErrAccountSuspended       = errors.New("account is suspended")
    ErrWeakPassword           = errors.New("password does not meet requirements")
)

// The handler translates domain errors to HTTP statuses
// All error messages are defined in one place

// api/error_handler.go
func domainErrToHTTP(err error) (int, string) {
    switch {
    case errors.Is(err, user.ErrEmailAlreadyRegistered):
        return http.StatusConflict, err.Error()
    case errors.Is(err, user.ErrUserNotFound):
        return http.StatusNotFound, err.Error()
    case errors.Is(err, user.ErrInvalidCredentials):
        return http.StatusUnauthorized, err.Error()
    case errors.Is(err, user.ErrAccountSuspended):
        return http.StatusForbidden, err.Error()
    default:
        return http.StatusInternalServerError, "internal server error"
    }
}

// ✗ Status string literals scattered without an official type
func canOrder(status string) bool { return status == "ACTIVE" }
func canNotify(status string) bool { return status == "ENABLED" } // different!

// ✗ Business rule numbers scattered without constants
func goldDiscount(p float64) float64 { return p * 0.85 }  // order service
func goldDiscount(p float64) float64 { return p * 0.80 }  // cart service — diverged!

// ✗ Config hardcoded in every place that needs it
db.SetMaxOpenConns(10)  // db package
http.Client{Timeout: 30s} // http package — no connection between them

// ✗ Request/response structs redefined in every service
// user-service: CreateUserResponse{CreatedAt: string}
// order-service: UserData{CreatedAt: time.Time} — silent parse error

// ✗ Error messages in various variations for the same thing
// "email already exists" / "duplicate email" / "email taken" / "email registered"
// All mean the same thing; users get different messages depending on the code path

// ✗ Services directly querying another service's database
// order-service: SELECT name FROM users WHERE id = ? -- bypassing User Service