Architecture & Design Patterns Chapter 05

5.1 Monorepo Structure

Service Directory Convention

Every service under apps/ follows an identical directory layout. This convention means a developer who understands one service can navigate any other without a learning curve.

apps/{service-name}/
├── cmd/
│   ├── server/main.go     # HTTP server entry point
│   ├── worker/main.go     # Kafka consumer (if needed)
│   ├── seed/main.go       # Database seeder
│   └── scheduler/main.go  # CronJob entry point
├── config/
│   └── config.go          # Env var loading → typed Config struct
├── internal/
│   ├── domain/            # Interface contracts (Service + Repository)
│   ├── model/             # GORM models / DTOs
│   ├── repository/        # Data access (GORM)
│   ├── service/           # Business logic
│   ├── handler/           # HTTP handlers
│   ├── db/                # Database connection factory
│   ├── worker/            # Job dispatcher (broadcast-service only)
│   ├── ratelimit/         # Rate limiting (broadcast-service only)
│   └── job/               # Job definitions (broadcast-service only)
└── migrations/            # SQL migrations (goose)

Shared Packages (pkg/)

Cross-service code lives in pkg/ and is imported by any service that needs it. Each package has a single, well-defined responsibility:

5.2 Layered Architecture (Clean Architecture)

The 4-Layer Flow

Every request passes through exactly four layers, each with a single responsibility:

Real Wiring: auth-service

Dependencies are assembled in main.go using plain constructor injection — no DI framework, no reflection, no magic:

// 1. Create the concrete repository (depends on *gorm.DB)
userRepo := repository.NewUserRepository(gormDB)

// 2. Create the service (depends on domain.UserRepository interface)
userService := service.NewUserService(userRepo, emailWorker, feUrl, kafkaProducer, internalUrl)

// 3. Create the handler (depends on domain.UserService interface)
userHandler := handler.NewUserHandler(userService)

Domain Interface Contract

Interfaces are defined in the domain/ package, which has zero dependencies:

// internal/domain/user.go
type UserService interface {
    Register(ctx context.Context, req model.RegisterRequest) (*model.User, error)
    Login(ctx context.Context, req model.LoginRequest) (*model.TokenPair, error)
    FindAll(ctx context.Context, tenantID string) (*[]model.User, error)
    // ...
}

type UserRepository interface {
    Create(user *model.User) error
    FindByEmail(email string) (*model.User, error)
    FindAll(tenantID string) (*[]model.User, error)
    // ...
}

5.3 API Gateway Pattern

The gateway-service is the single entry point for all client traffic. It acts as a reverse proxy that handles authentication, tenant identification, role-based access control, and request routing — so downstream services don't have to.

1. Route Configuration

Routes are defined declaratively in YAML, mapping URL prefixes to backend services:

routes:
  - path: "/api/v1/auth"
    target_url: "http://localhost:8081"
    auth_required: false

  - path: "/api/v1/admin"
    target_url: "http://localhost:8082"
    auth_required: true
    roles: ["Platform Admin"]

  - path: "/api/v1/broadcast"
    target_url: "http://localhost:8083"
    auth_required: true

2. Router.ServeHTTP Flow

The gateway's router implements http.Handler with prefix matching, JWT validation, role checking, and reverse proxying:

func (rtr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // 1. Find matching route by URL prefix
    route := rtr.findRoute(r.URL.Path)
    if route == nil {
        http.Error(w, "Not Found", 404)
        return
    }

    // 2. If route requires auth, validate JWT and inject tenant headers
    if route.AuthRequired {
        tenantCtx := rtr.validateAndInjectTenantHeaders(w, r)
        if tenantCtx == nil {
            return  // 401 already sent
        }

        // 3. Check role-based access if route specifies allowed roles
        if len(route.Roles) > 0 && !containsRole(route.Roles, tenantCtx.Role) {
            http.Error(w, "Forbidden", 403)
            return
        }
    }

    // 4. Proxy the request to the target service
    rtr.proxyRequest(w, r, route)  // uses httputil.ReverseProxy
}

3. Middleware Stack

The gateway applies middleware in order (outermost executes first):

5.4 Multitenancy Implementation

3 Layers of Tenant Identification

Tenant context is established through three complementary layers, each adding more information:

Data Isolation — Row-Level Filtering

Every repository query filters by tenant_id. There is no database-per-tenant isolation; instead, all tenants share the same database with row-level filtering:

func (r *UserRepository) FindAll(tenantID string) (*[]model.User, error) {
    var users []model.User
    query := r.db.Preload("Role")

    if tenantID != "" {
        // Tenant user: only see own tenant's data
        query = query.Where("tenant_id = ?", tenantID)
    } else {
        // Platform admin: see platform-level records
        query = query.Where("tenant_id IS NULL OR tenant_id = '00000000-0000-0000-0000-000000000000'")
    }

    return &users, query.Find(&users).Error
}

Platform Admin

A special "zero UUID" tenant represents the platform operator. Platform admins can access any tenant's data via ownership bypass:

const PlatformAdminTenantID = "00000000-0000-0000-0000-000000000000"

func IsPlatformAdmin(tc TenantContext) bool {
    return tc.TenantID == PlatformAdminTenantID
}

func RequireTenantOwnership(tc TenantContext, targetID string) error {
    if IsPlatformAdmin(tc) {
        return nil  // platform admin bypasses ownership check
    }
    if tc.TenantID != targetID {
        return Forbidden("access denied")
    }
    return nil
}

Kafka Event Isolation

Kafka events carry TenantID as the partition key. This ensures:

• Ordered delivery per tenant — all events for tenant "acme" go to the same partition, preserving message order
• Fair scheduling — high-volume tenants don't starve others across partitions
• Consumer filtering — workers can optionally filter events by tenant

5.5 Configuration Pattern

Each service loads its configuration from environment variables using godotenv for local development and plain os.Getenv for production:

func Load() (*Config, error) {
    godotenv.Load()  // optional: loads .env file if present

    return &Config{
        Port:        getEnvOrDefault("PORT", "8081"),
        DatabaseURL: os.Getenv("DATABASE_URL"),
        Secret:      os.Getenv("JWT_SIGNING_KEY"),
    }, nil
}

func getEnvOrDefault(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}

Key Environment Variables

5.6 Database & Migrations

Database Strategy

• ORM: GORM with the PostgreSQL driver (gorm.io/driver/postgres)
• Production DB: CockroachDB (PostgreSQL wire-compatible, distributed)
• Isolation: Database per service — each service has its own schema namespace

Migrations with goose

SQL migrations live in apps/{service}/migrations/ and are managed by goose. Each migration file is a timestamped SQL file:

# Run migrations for a specific service
make migrate app=auth-service

# Create a new migration
make migration app=auth-service name=add_users_table

Connection Pool Tuning

The broadcast-service configures aggressive pool settings for high-throughput message processing:

sqlDB, _ := gormDB.DB()
sqlDB.SetMaxOpenConns(25)                  // max concurrent connections
sqlDB.SetMaxIdleConns(10)                   // keep warm connections
sqlDB.SetConnMaxLifetime(5 * time.Minute)  // prevent stale connections

5.7 Inter-Service Communication

System Architecture

                    ┌──────────────────┐
   Client ──────────►  Gateway Service  │
                    │  (Reverse Proxy)  │
                    └──┬───┬───┬───────┘
                       │   │   │
          ┌────────────┘   │   └────────────┐
          ▼                ▼                ▼
   ┌──────────┐    ┌──────────┐    ┌──────────────┐
   │   Auth   │◄──►│  Admin   │    │  Broadcast   │
   │ Service  │HTTP│ Service  │    │   Service    │
   └────┬─────┘    └────┬─────┘    └──────┬───────┘
        │               │                 │
        ▼               ▼                 ▼
   ┌─────────┐   ┌─────────┐     ┌──────────────┐
   │PostgreSQL│   │PostgreSQL│     │  PostgreSQL   │
   └─────────┘   └─────────┘     └──────────────┘
                                       │
           ┌─────────┐           ┌──────────────┐
           │  Redis   │           │    Kafka     │
           └─────────┘           └──┬───────────┘
                                    │
                              ┌─────┴──────┐
                              ▼            ▼
                       ┌──────────┐  ┌──────────────┐
                       │Broadcast │  │Meta Webhook  │
                       │ Worker   │  │  Service     │
                       └──────────┘  └──────────────┘

Synchronous Communication (HTTP)

Direct HTTP calls are used for request-response operations that need immediate results:

Asynchronous Communication (Kafka)

Events are published to Kafka for operations that don't require an immediate response:

5.8 Graceful Shutdown Pattern

Every service implements the same graceful shutdown pattern to prevent data loss and connection leaks during deployments or restarts:

// 1. Start the HTTP server in the background
go func() {
    if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        slog.Error("server error", "error", err)
    }
}()

// 2. Wait for termination signal
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
slog.Info("shutting down...")

// 3. Ordered cleanup (reverse of initialization)
cancelConsumer()           // Stop Kafka consumer first (stop accepting work)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

server.Shutdown(ctx)       // Drain in-flight HTTP requests
kafkaProducer.Close()      // Flush pending Kafka messages
shutdown(ctx)              // Flush OpenTelemetry spans

Shutdown Sequence

5.9 Observability (OpenTelemetry)

The entire system is instrumented with OpenTelemetry for distributed tracing, providing end-to-end visibility across services.

Components

Trace Context Flow

Client Request
  → Gateway (creates root span, injects W3C traceparent header)
    → Auth Service (extracts traceparent, creates child span)
      → Kafka Event (trace context injected into event headers)
        → Worker (extracts trace context from headers, creates child span)
          → External API call (child span recorded)

Setup Pattern

func InitTracer(ctx context.Context, serviceName string) (func(context.Context) error, error) {
    exporter, err := otlptracehttp.New(ctx)
    if err != nil {
        return nil, err
    }

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceNameKey.String(serviceName),
        )),
    )
    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{},
        propagation.Baggage{},
    ))

    return tp.Shutdown, nil  // returns shutdown function for graceful cleanup
}

5.10 Middleware Stack Summary

Each service has its own middleware chain, applied in order. The gateway handles cross-cutting concerns; backend services handle service-specific concerns.

gateway-service

auth-service

Protected routes additionally use JWTMiddleware and Permission(menu, action) per route group.

admin-service

All admin routes require authentication. Per-route Permission middleware enforces menu+action checks.

broadcast-service

Kafka consumer middleware: RetryableHandler → IdempotentHandler → business handler.

Middleware Responsibility Matrix

5.11 Complete API Endpoints

All routes are prefixed through the gateway. Internal routes (marked with /internal/) are not exposed through the gateway and are only callable service-to-service.

auth-service :8081

admin-service :8082

broadcast-service :8083

gateway-service :8080