Modular Monolith
by Domain

Folder bukan kosmetik, ia menentukan arah dependency dan kecepatan tim

Struktur folder bukan urusan rapi-rapi belaka. Di Go, ia menentukan import path, visibilitas identifier, dan arah dependency, jadi keputusan folder hari ini akan menempel di kode bertahun-tahun.

Di React, kamu mungkin pernah melihat folder components/, hooks/, dan services/ membengkak sampai ratusan file, sampai mencari satu fitur berarti membuka empat folder sekaligus. Di Laravel, app/Http/Controllers, app/Services, app/Models, dan app/Repositories terasa rapi saat aplikasi kecil. Tetapi di backend bisnis seperti online shop skincare, pertanyaan harian developer biasanya bukan “handler ada di mana”, melainkan “fitur checkout ada di mana”, “kenapa harga di cart beda dengan harga di order”, atau “siapa yang boleh mengurangi stok”.

Dalam Go, satu direktori adalah satu package, dan satu package adalah unit visibilitas terkecil. Identifier huruf besar (Product) terlihat dari luar package, identifier huruf kecil (scanProduct) tidak. Maka struktur folder langsung menjadi struktur arsitektur: kalau kamu menaruh semua kode katalog di internal/product/, compiler ikut membantu menjaga agar detail internal katalog tidak bocor ke domain lain. Modul ini mengikuti panduan resmi Organizing a Go module dan Effective Go, lalu menerapkannya ke sembilan domain proyek skincare: product, cart, order, payment, inventory, user, promotion, review, dan notification.

Folder utama menjawab area bisnis, layer jadi file di dalamnya

By-domain berarti folder tingkat pertama menjawab “fitur bisnis apa”, bukan “jenis teknis file apa”. Layer (handler, service, repository) tetap ada, tetapi posisinya turun menjadi file di dalam folder domain.

Struktur by-layer global terlihat rapi di hari pertama karena semua handler berkumpul di satu tempat. Masalahnya muncul saat fitur bertambah: untuk memahami satu alur checkout, developer harus membuka controllers/order_controller.go, services/order_service.go, repositories/order_repository.go, dan models/order.go yang tersebar jauh. Lebih parah lagi, karena semua handler hidup di package yang sama, tidak ada penghalang teknis yang mencegah cart_handler memanggil fungsi internal payment_service. Boundary bisnis bocor diam-diam.

Struktur by-domain membalik prioritas. Semua kode product tinggal dekat product, semua kode order tinggal dekat order, dan karena tiap domain adalah package terpisah, dependency antar domain menjadi import yang eksplisit dan bisa diatur.

Sembilan domain skincare di proyek ini punya tanggung jawab yang jelas dan tidak saling tumpang tindih. Inilah peta mental yang akan kita pakai sampai akhir roadmap.

Direktori bernama internal punya arti khusus yang ditegakkan compiler

Folder internal/ bukan sekadar nama yang kita pilih. Di Go, internal adalah kata ajaib yang dimengerti compiler: package di dalamnya hanya boleh di-import oleh kode yang berbagi parent direktori dengan internal, bukan oleh project lain.

Artinya, semua package di internal/ (seperti internal/product, internal/order) hanya bisa di-import oleh code di dalam module github.com/kamu/skincare-backend. Kalau ada orang lain meng-import module-mu untuk dipakai sebagai library, mereka tidak akan bisa menyentuh internal/. Ini adalah pagar pertama: detail backend skincare tidak menjadi API publik yang tak sengaja dipakai orang luar dan jadi tak bisa diubah.

Aturan import internal/Salin
github.com/kamu/skincare-backend/
  cmd/api/main.go              # BOLEH import internal/* (satu module, di atas internal)
  internal/product/service.go  # BOLEH import internal/order? (lihat section 06)
github.com/orang-lain/app/
  main.go                      # DILARANG import skincare-backend/internal/*

Visibilitas Go bekerja di dua lapis yang saling melengkapi. Lapis pertama adalah huruf awal identifier: huruf besar berarti exported (terlihat dari package lain), huruf kecil berarti unexported (terkunci di dalam package). Lapis kedua adalah folder internal/ yang mengunci seluruh package agar tak bisa di-import dari luar module. Gabungan keduanya membuat kita bisa memilih dengan presisi: apa yang publik untuk seluruh module, apa yang privat untuk satu domain saja.

Satu repository, satu module Go, sembilan domain plus shared

Satu go.mod di root, dua entry point di cmd/, sembilan domain di internal/, dan satu internal/shared/ kecil untuk kode lintas domain yang benar-benar stabil.

Go module yang bersih meletakkan go.mod di root repository, memisahkan command entry point di cmd/, dan menaruh seluruh package aplikasi di internal/. Tidak semua domain butuh file selengkap product. Domain inti seperti product, cart, dan order punya handler HTTP, service, repository, sampai routes. Domain pendukung seperti notification mungkin hanya punya service dan dijalankan worker, tanpa handler HTTP sama sekali. Struktur mengikuti kebutuhan, bukan template seragam.

Dua binary, satu module, domain yang sama dipakai ulang

Folder cmd/ berisi program yang bisa dijalankan, bukan business logic. Proyek skincare punya dua: cmd/api melayani HTTP request customer, dan cmd/worker menjalankan tugas latar yang tidak boleh memperlambat request.

Memisahkan API dari worker adalah keputusan arsitektur, bukan hanya rapi-rapi file. Request checkout harus cepat: customer menunggu di halaman pembayaran. Mengirim email konfirmasi, memanggil ulang status gateway, atau menulis ke sistem akuntansi adalah tugas lambat yang tidak perlu ditunggu customer. API menulis pekerjaan ke antrian atau ke tabel pending, lalu worker mengambilnya di proses terpisah. Keduanya berbagi domain yang sama persis (satu module, satu codebase), hanya entry point dan dependency yang berbeda.

flowchart LR
  Customer["React Storefront"] -->|HTTP JSON| API["cmd/api"]
  Gateway["Payment Gateway"] -->|webhook| API
  API -->|tulis order pending| DB[("PostgreSQL")]
  API -->|enqueue job| Q[["Job: tabel pending / queue"]]
  Worker["cmd/worker"] -->|poll / consume| Q
  Worker -->|kirim email| Email["notification.Sender"]
  Worker -->|sinkron status| DB

Gambar 1. API merespons cepat ke customer dan webhook gateway, lalu menitipkan pekerjaan lambat. Worker memprosesnya di proses terpisah, sehingga lonjakan email atau retry gateway tidak pernah memperlambat halaman checkout.

cmd/api/main.go adalah composition root: ia boleh tahu semua domain karena tugasnya merakit. Ia membaca config, membuka pool, membangun repository, service, dan handler tiap domain, lalu menyusun router. Domain seperti internal/product tidak pernah tahu siapa yang menjalankannya.

go.modSalin
module github.com/kamu/skincare-backend

go 1.26

cmd/api/main.goSalin
package main

import (
	"context"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"

	"github.com/kamu/skincare-backend/internal/cart"
	"github.com/kamu/skincare-backend/internal/order"
	"github.com/kamu/skincare-backend/internal/payment"
	"github.com/kamu/skincare-backend/internal/product"
	"github.com/kamu/skincare-backend/internal/shared/config"
	"github.com/kamu/skincare-backend/internal/shared/database"
	"github.com/kamu/skincare-backend/internal/shared/domain"
	"github.com/kamu/skincare-backend/internal/shared/logger"
)

func main() {
	if err := run(); err != nil {
		slog.Error("api fatal", "error", err)
		os.Exit(1)
	}
}

func run() error {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	cfg, err := config.Load()
	if err != nil {
		return err
	}

	log := logger.New(cfg.LogLevel)

	pool, err := database.NewPool(ctx, cfg.DatabaseURL)
	if err != nil {
		return err
	}
	defer pool.Close()

	// --- Wiring per domain: repository -> service -> handler ---
	productRepo := product.NewPostgresRepository(pool)
	productSvc := product.NewService(pool, productRepo)
	productHandler := product.NewHandler(productSvc)

	cartRepo := cart.NewPostgresRepository(pool)
	cartSvc := cart.NewService(pool, cartRepo, productSvc)
	cartHandler := cart.NewHandler(cartSvc)

	paymentRepo := payment.NewPostgresRepository(pool)
	paymentSvc := payment.NewService(pool, paymentRepo)
	paymentHandler := payment.NewHandler(paymentSvc)

	// order butuh membaca product dan cart, serta membuat payment.
	// Ia menerima interface kecil, bukan struct konkret, lihat section 06.
	// productSvc mengembalikan product.Product, sedangkan order.ProductReader
	// minta order.ProductSnapshot, jadi composition root menyisipkan adapter
	// kecil yang memetakan satu tipe ke tipe lainnya (lihat productReaderAdapter).
	orderRepo := order.NewPostgresRepository(pool)
	orderSvc := order.NewService(pool, orderRepo, cartSvc, productReaderAdapter{productSvc}, paymentSvc)
	orderHandler := order.NewHandler(orderSvc)

	r := chi.NewRouter()
	r.Use(middleware.RequestID)
	// middleware.RealIP sudah deprecated di chi v5 (rawan IP spoofing). Untuk server
	// yang berdiri langsung di internet pakai ClientIPFromRemoteAddr; di belakang
	// reverse proxy tepercaya pakai ClientIPFromXFFTrustedProxies(n) sesuai infra.
	r.Use(middleware.ClientIPFromRemoteAddr)
	r.Use(middleware.Recoverer)

	r.Route("/v1", func(r chi.Router) {
		productHandler.Routes(r)
		cartHandler.Routes(r)
		orderHandler.Routes(r)
		paymentHandler.Routes(r)
	})

	srv := &http.Server{
		Addr:              cfg.HTTPAddr,
		Handler:           r,
		ReadHeaderTimeout: 5 * time.Second,
	}

	go func() {
		<-ctx.Done()
		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
		defer cancel()
		if err := srv.Shutdown(shutdownCtx); err != nil {
			log.Error("graceful shutdown", "error", err)
		}
	}()

	log.Info("api listening", "addr", cfg.HTTPAddr)
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		return err
	}
	return nil
}

// productReaderAdapter membungkus *product.Service agar memenuhi order.ProductReader.
// product.Service mengembalikan product.Product dan product.Variant (model katalog),
// sedangkan order minta order.ProductSnapshot (potret sempit untuk checkout).
// Adapter inilah satu-satunya tempat pemetaan ke ProductSnapshot terjadi: nama dari
// Product, sedangkan harga, SKU, dan variantID dari Variant (price_rupiah ada di varian).
type productReaderAdapter struct {
	svc *product.Service
}

func (a productReaderAdapter) GetProduct(ctx context.Context, id domain.ProductID) (order.ProductSnapshot, error) {
	p, err := a.svc.GetProduct(ctx, id)
	if err != nil {
		return order.ProductSnapshot{}, err
	}
	v, err := a.svc.GetSellableVariant(ctx, id)
	if err != nil {
		return order.ProductSnapshot{}, err
	}
	return order.ProductSnapshot{
		ProductID:   p.ID,
		VariantID:   v.ID,
		Name:        p.Name,
		SKU:         v.SKU,
		PriceRupiah: v.PriceRupiah,
		IsActive:    p.Status == "active" && v.IsActive,
	}, nil
}

cmd/worker/main.go memakai domain yang sama, tetapi entry point berbeda. Ia tidak meng-import net/http, chi, route, atau handler sama sekali. Background job tidak perlu tahu apa pun soal HTTP, dan kalau worker rontok, API tetap melayani customer.

cmd/worker/main.goSalin
package main

import (
	"context"
	"log/slog"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/kamu/skincare-backend/internal/notification"
	"github.com/kamu/skincare-backend/internal/order"
	"github.com/kamu/skincare-backend/internal/payment"
	"github.com/kamu/skincare-backend/internal/shared/config"
	"github.com/kamu/skincare-backend/internal/shared/database"
	"github.com/kamu/skincare-backend/internal/shared/logger"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	cfg, err := config.Load()
	if err != nil {
		slog.Error("load config", "error", err)
		os.Exit(1)
	}

	log := logger.New(cfg.LogLevel)

	pool, err := database.NewPool(ctx, cfg.DatabaseURL)
	if err != nil {
		log.Error("open pool", "error", err)
		os.Exit(1)
	}
	defer pool.Close()

	// Worker merakit dependency yang ia butuh saja: tidak ada handler, tidak ada chi.
	paymentRepo := payment.NewPostgresRepository(pool)
	paymentSvc := payment.NewService(pool, paymentRepo)

	emailSender := notification.NewSMTPSender(cfg.SMTP)
	notifySvc := notification.NewService(emailSender)

	orderRepo := order.NewPostgresRepository(pool)
	orderWorker := order.NewWorker(pool, orderRepo, paymentSvc, notifySvc)

	ticker := time.NewTicker(5 * time.Second)
	defer ticker.Stop()

	log.Info("worker started")
	for {
		select {
		case <-ctx.Done():
			log.Info("worker stopped")
			return
		case <-ticker.C:
			if err := orderWorker.ProcessPendingOrders(ctx); err != nil {
				log.Error("process pending orders", "error", err)
			}
		}
	}
}

Domain tingkat tinggi memakai interface kecil, bukan struct konkret tetangga

Boundary yang baik bukan sekadar folder terpisah, tetapi aturan: domain mana boleh import domain mana, dan dalam bentuk apa. Kunci agar dependency tetap longgar adalah interface kecil yang dideklarasikan di sisi pemakai.

Dalam proyek skincare, internal/product berdiri paling rendah: ia tidak import domain lain karena katalog tidak perlu tahu soal cart atau order. Sebaliknya, internal/order berada lebih tinggi karena checkout perlu membaca product, membaca cart, dan membuat payment. Arah dependency mengikuti alur bisnis: yang lebih tinggi boleh bergantung pada yang lebih rendah, tidak boleh sebaliknya.

flowchart TD
  API["cmd/api"] --> Product["internal/product"]
  API --> Cart["internal/cart"]
  API --> Order["internal/order"]
  API --> Payment["internal/payment"]
  Worker["cmd/worker"] --> Order
  Worker --> Payment
  Worker --> Notification["internal/notification"]
  Cart -->|interface ProductReader| Product
  Order -->|interface ProductReader| Product
  Order -->|interface CartReader| Cart
  Order -->|interface PaymentCreator| Payment
  Order -->|interface StockReserver| Inventory["internal/inventory"]
  Product -. "DILARANG import" .-> Order
  Product -. "DILARANG import" .-> Cart

Gambar 2. Entry point boleh merakit semua domain. Antar domain, dependency mengalir satu arah dari tinggi ke rendah lewat interface kecil. Product di paling rendah tidak boleh mengenal cart atau order.

Trik idiomatik Go adalah mendeklarasikan interface di package yang memakainya, bukan di package yang mengimplementasikannya. order mendefinisikan ProductReader berisi hanya method yang ia butuhkan, lalu sebuah adapter kecil di composition root yang memenuhinya. Penting dicatat: order.ProductReader.GetProduct mengembalikan order.ProductSnapshot (potret sempit yang relevan untuk checkout), sedangkan product.Service.GetProduct mengembalikan product.Product (model penuh katalog). Karena return type berbeda, *product.Service tidak otomatis memenuhi order.ProductReader. Inilah pekerjaan adapter: ia memetakan product.Product menjadi order.ProductSnapshot di cmd/api, sehingga order tetap cukup tahu kontrak sempit ini tanpa import detail product.

internal/product/service.goSalin
package product

import (
	"context"

	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/kamu/skincare-backend/internal/shared/database"
	"github.com/kamu/skincare-backend/internal/shared/domain"
)

type Repository interface {
	FindByID(ctx context.Context, db database.Querier, id domain.ProductID) (Product, error)
	FindSellableVariant(ctx context.Context, db database.Querier, id domain.ProductID) (Variant, error)
	ListActive(ctx context.Context, db database.Querier, filter ListFilter) ([]Product, error)
}

type Service struct {
	pool *pgxpool.Pool
	repo Repository
}

func NewService(pool *pgxpool.Pool, repo Repository) *Service {
	return &Service{pool: pool, repo: repo}
}

// GetProduct dikembalikan sebagai struct konkret Product (model penuh katalog).
func (s *Service) GetProduct(ctx context.Context, id domain.ProductID) (Product, error) {
	return s.repo.FindByID(ctx, s.pool, id)
}

// GetSellableVariant mengembalikan varian aktif yang siap dijual untuk sebuah
// produk, lengkap dengan harga rupiah. Harga hidup di Variant (product_variants),
// bukan di Product, sesuai skema kanonik proyek (lihat R3C10).
func (s *Service) GetSellableVariant(ctx context.Context, id domain.ProductID) (Variant, error) {
	return s.repo.FindSellableVariant(ctx, s.pool, id)
}

internal/order/service.goSalin
package order

import (
	"context"

	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/kamu/skincare-backend/internal/shared/domain"
)

// ProductReader adalah interface yang DIDEFINISIKAN order, bukan product.
// Order hanya butuh membaca harga dan status produk saat checkout.
type ProductReader interface {
	GetProduct(ctx context.Context, id domain.ProductID) (ProductSnapshot, error)
}

// CartReader dan PaymentCreator dideklarasikan dengan cara yang sama:
// sempit, sesuai kebutuhan order, dipenuhi service tetangga secara implisit.
type CartReader interface {
	GetActiveCart(ctx context.Context, userID domain.UserID) (CheckoutCart, error)
}

type PaymentCreator interface {
	CreatePayment(ctx context.Context, orderID domain.OrderID, amountRupiah int64) (domain.PaymentID, error)
}

type Service struct {
	pool    *pgxpool.Pool
	repo    Repository
	product ProductReader
	cart    CartReader
	payment PaymentCreator
}

func NewService(pool *pgxpool.Pool, repo Repository, cart CartReader, product ProductReader, payment PaymentCreator) *Service {
	return &Service{pool: pool, repo: repo, cart: cart, product: product, payment: payment}
}

Perhatikan satu detail penting yang menyelaraskan modul ini dengan skema kanonik proyek: harga dibawa sebagai int64 rupiah (amountRupiah int64, ProductSnapshot.PriceRupiah), bukan float64 dan bukan satuan cent. Saat checkout, order menyalin harga ke order_items.unit_price_rupiah sebagai snapshot, agar perubahan harga katalog di masa depan tidak mengubah harga order yang sudah jadi.

internal/order/model.goSalin
package order

import "github.com/kamu/skincare-backend/internal/shared/domain"

// ProductSnapshot adalah potret produk yang order butuhkan saat checkout.
// Order tidak mengenal seluruh Product, cukup yang relevan untuk harga dan validasi.
type ProductSnapshot struct {
	ProductID   domain.ProductID
	VariantID   domain.VariantID
	Name        string
	SKU         string
	PriceRupiah int64 // integer rupiah, bukan float, bukan cent
	IsActive    bool
}

Go menolak import melingkar saat compile, dan itu sinyal desain

Go tidak mengizinkan dua package saling import. Kalau product import order dan order import product, build langsung gagal. Ini terasa kaku saat datang dari JS atau PHP, tetapi sebenarnya pagar pengaman yang memaksa arah dependency tetap satu arah.

Cycle paling sering muncul dari niat baik: “order butuh memanggil method di product, dan kebetulan product juga butuh satu method di order”. Begitu keduanya saling import, compiler menolak. Pesannya jelas dan tidak bisa diakali.

Terminal: error import cycleSalin
package github.com/kamu/skincare-backend/cmd/api
	imports github.com/kamu/skincare-backend/internal/order
	imports github.com/kamu/skincare-backend/internal/product
	imports github.com/kamu/skincare-backend/internal/order: import cycle not allowed

Ada tiga cara sehat memutus cycle, dari yang paling sering dipakai ke yang paling jarang. Pilih sesuai bentuk masalahnya, jangan langsung lompat ke shared package.

Contoh nyata kasus ketiga di proyek skincare: setelah order dibuat, customer perlu menerima email konfirmasi. Godaannya adalah order.Service langsung import notification.Service dan memanggilnya di dalam transaksi checkout. Itu mengikat order ke notification, memperlambat checkout, dan kalau SMTP lambat, customer ikut menunggu. Solusi yang lebih bersih: order hanya menulis baris ke tabel pending, lalu worker yang memanggil notification.

flowchart LR
  subgraph antipattern["Anti-pola: panggilan langsung"]
    O1["order.Service"] -->|import + panggil di tx| N1["notification.Service"]
    N1 -.->|kalau butuh data order| O1
  end
  subgraph clean["Pola sehat: lewat worker"]
    O2["order.Service"] -->|tulis pending| DB[("PostgreSQL")]
    W["cmd/worker"] -->|baca pending| DB
    W -->|panggil| N2["notification.Service"]
  end

Gambar 3. Kiri, order dan notification saling import dan checkout melambat. Kanan, order hanya menulis pekerjaan, worker yang memanggil notification, sehingga tidak ada cycle dan checkout tetap cepat.

Laci kecil untuk konsep lintas domain, bukan tempat buang helper

internal/shared/ adalah laci kecil untuk konsep yang benar-benar lintas domain, stabil, dan tidak membawa aturan bisnis spesifik. Ia bukan tempat sampah untuk fungsi yang bingung ditaruh di mana.

Kode yang layak masuk shared punya tiga ciri: dipakai banyak domain, jarang berubah, dan tidak memuat logika bisnis satu domain tertentu. Contohnya tipe ID kustom (UserID, ProductID), error generik, envelope response JSON, middleware auth, config loader, logger, dan pool PostgreSQL. Kalau sebuah fungsi hanya dipakai order, ia milik internal/order, bukan shared.

internal/shared/domain/id.goSalin
package domain

import "fmt"

type UserID int64
type ProductID int64
type VariantID int64
type OrderID int64
type CartID int64
type PaymentID int64

func NewProductID(v int64) (ProductID, error) {
	if v <= 0 {
		return 0, fmt.Errorf("product id must be positive")
	}
	return ProductID(v), nil
}

func (id ProductID) Int64() int64 {
	return int64(id)
}

func (id UserID) Int64() int64 {
	return int64(id)
}

Tipe ID kustom ini adalah investasi kecil dengan hasil besar. Karena UserID dan ProductID adalah tipe berbeda di mata compiler, kamu tidak bisa tidak sengaja mengoper UserID ke fungsi yang minta ProductID. Bug klasik “tertukar argumen” yang di JS dan PHP baru ketahuan saat data salah, di Go gagal saat compile.

internal/product/model.goSalin
package product

import (
	"time"

	"github.com/kamu/skincare-backend/internal/shared/domain"
)

// Product memetakan tabel products. Harga TIDAK di sini, melainkan di
// product_variants.price_rupiah, sesuai skema kanonik proyek (lihat R3C10).
type Product struct {
	ID          domain.ProductID
	BrandID     int64
	CategoryID  int64
	Name        string
	Slug        string
	Description string
	Status      string // draft, active, archived
	CreatedAt   time.Time
	UpdatedAt   time.Time
	DeletedAt   *time.Time
}

// Variant adalah SKU yang benar-benar dijual, lengkap dengan harga rupiah.
type Variant struct {
	ID          domain.VariantID
	ProductID   domain.ProductID
	SKU         string
	PriceRupiah int64 // integer rupiah, bukan float, bukan cent
	IsActive    bool
}

DTO (kontrak HTTP) terpisah dari model domain dan tetap memakai price_rupiah di tag JSON, sehingga frontend React menerima angka rupiah utuh tanpa konversi.

internal/product/dto.goSalin
package product

type CreateVariantRequest struct {
	ProductID   int64  `json:"product_id"`
	SKU         string `json:"sku"`
	PriceRupiah int64  `json:"price_rupiah"`
}

type VariantResponse struct {
	ID          int64  `json:"id"`
	ProductID   int64  `json:"product_id"`
	SKU         string `json:"sku"`
	PriceRupiah int64  `json:"price_rupiah"`
	IsActive    bool   `json:"is_active"`
}

Tes lakmus: bisakah satu domain dipindahkan tanpa menyeret yang lain?

Modul yang independen adalah modul yang bisa kamu pahami, ubah, tes, dan suatu hari ekstrak menjadi service, tanpa menyentuh domain lain. Independensi tidak datang otomatis dari folder terpisah, ia dijaga dengan beberapa disiplin konkret.

Ada empat pemeriksaan yang bisa kamu jalankan untuk menilai apakah sebuah domain benar-benar independen. Kalau salah satu gagal, boundary-nya bocor dan perlu dirapikan.

Tes lakmus paling tajam adalah pertanyaan ekstraksi: kalau suatu hari notification harus menjadi service terpisah, apa yang berubah? Pada modular monolith yang sehat, jawabannya sempit: ganti pemanggilan notifySvc.SendOrderConfirmation(...) di worker dengan pemanggilan HTTP atau publish ke message broker, dan pindahkan folder internal/notification ke repository baru. Karena order tidak pernah import notification langsung (lihat section 07), order tidak ikut berubah sama sekali.

Terminal: periksa kemandirian domainSalin
# Domain rendah tidak boleh import domain tinggi
go list -deps ./internal/product/... | grep "internal/order" && echo "BOCOR: product import order"

# Service dan handler tidak boleh import pgx
grep -rn "jackc/pgx" internal/order/service.go internal/order/handler.go

# Tiap domain bisa dites mandiri dengan fake
go test ./internal/order/...

Microservice memisahkan deployment, bukan otomatis memperbaiki desain domain

Microservice memberi pemisahan deployment dan skalabilitas independen, tetapi ia tidak otomatis memperbaiki desain domain. Boundary yang buruk di monolith akan tetap buruk saat dipecah, hanya pindah dari import menjadi panggilan jaringan yang lebih mahal di-debug.

Untuk online shop skincare tahap awal, modular monolith memberi boundary kode tanpa menambah biaya operasional microservice. Kamu tetap punya satu binary API, satu pipeline deploy, satu jalur observability, dan yang terpenting satu transaction boundary. Checkout yang menyentuh cart, inventory, order, dan payment bisa berjalan dalam satu transaksi database lokal yang atomik. Di microservice, transaksi lintas service butuh saga atau outbox pattern yang jauh lebih rumit.

Split menjadi service terpisah layak dipertimbangkan saat ada alasan kuat, bukan karena tren. Pertanyaan keputusannya sederhana: apakah masalahnya benar-benar butuh proses terpisah, atau cukup package terpisah yang sudah kamu punya?

flowchart TD
  Start["Mulai proyek skincare"] --> Monolith["Satu Go module, sembilan domain"]
  Monolith --> Domain["Pisah package by domain + interface"]
  Domain --> Measure["Ukur bottleneck, ownership tim, beban deploy"]
  Measure --> Decision{"Ada alasan kuat split?"}
  Decision -->|"Belum (mayoritas kasus)"| Keep["Tetap modular monolith"]
  Decision -->|"Ya: skala tim, bottleneck spesifik, ownership"| Split["Ekstrak satu domain jadi service"]
  Split --> Contract["Ganti panggilan in-process jadi API atau event"]
  Keep --> Domain

Gambar 4. Microservice adalah keputusan evolusi yang dipicu data, bukan titik awal wajib. Karena boundary sudah berupa package dan interface, langkah split menjadi terukur, bukan operasi besar.

Pindahkan struktur by-layer menjadi by-domain tanpa mengubah behavior API

Latihan ini memindahkan struktur by-layer menjadi by-domain selangkah demi selangkah, lalu memakai compiler dan test sebagai jaring pengaman agar tidak ada behavior API yang berubah.

TerminalSalin
mkdir -p cmd/api cmd/worker
mkdir -p internal/{product,cart,order,payment,inventory,user,promotion,review,notification}
mkdir -p internal/shared/{config,domain,errors,httpx,middleware,database,logger}

go build ./...
go test ./...

Import policy berikut menjadi kontrak tim. Tuliskan di README proyek dan tegakkan dengan linter agar tidak luntur seiring waktu.

Import policy proyek skincareSalin
BOLEH   cmd/api          -> semua internal/* (composition root)
BOLEH   cmd/worker       -> order, payment, notification, shared/*
BOLEH   internal/order   -> internal/product   (lewat interface ProductReader)
BOLEH   internal/order   -> internal/cart      (lewat interface CartReader)
BOLEH   internal/order   -> internal/inventory (lewat interface StockReserver)
BOLEH   internal/cart    -> internal/product   (validasi produk aktif)
BOLEH   semua domain     -> internal/shared/*  (id, errors, httpx, database)

JANGAN  internal/product   -> internal/order, internal/cart   (arah terbalik)
JANGAN  internal/shared/*  -> internal/<domain bisnis apa pun> (shared di paling bawah)
JANGAN  internal/order     -> internal/notification            (pakai event via worker)
JANGAN  internal/*/service.go -> jackc/pgx                      (pgx hanya di pgx_repository.go)

Boundary setengah hati lebih buruk daripada tidak ada boundary sama sekali

Sebagian besar masalah modular monolith datang dari boundary yang dibuat setengah jalan: folder sudah dipisah, tetapi disiplin import dan layer belum ditegakkan. Inilah pola yang paling sering muncul saat datang dari ekosistem ORM dan framework penuh.

Modular monolith membuat proyek skincare tetap satu aplikasi yang mudah dideploy, tetapi tidak menjadi satu gumpalan kode yang mustahil diubah. Folder mengikuti domain, dependency mengalir satu arah, dan compiler ikut menjaga boundary.

Untuk proyek online shop skincare, struktur ini menjadi fondasi sebelum chapter berikutnya mengisi detailnya: configuration management agar DATABASE_URL, JWT, dan kredensial gateway aman per environment, lalu error handling strategy agar tiap domain memetakan error ke status HTTP yang konsisten, dan logging strategy agar perilaku tiap domain terlihat di produksi. Repository pattern dari R3C10 yang sudah kamu tulis tetap dipakai apa adanya di dalam tiap domain, hanya kini ia hidup dalam kerangka modular yang punya batas tegas dan arah dependency yang jelas.

Rujukan resmi yang relevan: Organizing a Go module, Effective Go, Go 1.26 release notes, dan internal packages.