ADR-0004: Shared kernel + Anti-Corruption Layer for inter-module user lookup

Status

Accepted

Decision

Modules must not import each other’s domain packages. Cross-module data access goes through a shared kernel interface in internal/shared/application/port/. The implementing module provides an adapter; wiring happens only in main.go.

Why

Direct module-to-module imports create tight coupling: a breaking change in the user module ripples into every module that imports it, circular dependency risk grows, and independent deployment becomes impossible. The Shared Kernel + ACL pattern breaks this: modules depend on a lightweight interface (no implementation), the owning module provides one adapter, and main.go is the only place that knows which adapter is wired.

Structure

internal/shared/application/port/user_lookup.go   ← shared kernel (interface + DTO only)
internal/modules/user/adapter/outbound/external/user_lookup_adapter.go  ← ACL adapter
internal/app/container.go                          ← holds sharedPort.UserLookupService
cmd/server/main.go                                 ← wires adapter into container

The leave module (and any other consumer) imports only shared/application/port — never the user module.

Trade-offs


True loose coupling	No direct module dependencies
Microservice-ready	Swap adapter from PostgreSQL → gRPC without touching business logic
Easy to test	Mock the shared interface; no module dep in test
One more indirection	Slightly more files per cross-module dependency

Rules for agents

Never import another module’s domain/ or application/ package from inside a different module
Cross-module data access: define an interface in internal/shared/application/port/, add an adapter in the owning module, wire in main.go
The shared kernel contains interfaces and DTOs only — no implementation, no framework imports
Only main.go imports module-specific adapters; all other files depend on the shared interface
To swap to microservice mode, replace the adapter in main.go with an HTTP/gRPC client that implements the same interface — no other files change

Bad pattern (do not generate)

// leave module directly importing user module's domain
import userPorts "github.com/waynecheah/go-core/internal/modules/user/application/port"

type Container struct {
    UserService userPorts.UserService // tight coupling
}

Good pattern

// shared kernel — interface only, no module dependency
// internal/shared/application/port/user_lookup.go
type UserLookupService interface {
    GetUserInfo(ctx context.Context, userID string) (*UserInfo, error)
}

// container depends on shared interface
type Container struct {
    UserLookup sharedPort.UserLookupService
}

// main.go: only place that knows about the adapter
container.UserLookup = userAdapters.NewUserLookupAdapter(userModule.Service)

Architecture Decision Records

Digital Worker

Fieldforce Mobile (Flutter)

0004 shared kernel anti corruption layer

ADR-0004: Shared kernel + Anti-Corruption Layer for inter-module user lookup

Status

Tags

Decision

Why

Structure

Trade-offs

Rules for agents

Bad pattern (do not generate)

Good pattern

​ADR-0004: Shared kernel + Anti-Corruption Layer for inter-module user lookup

​Status

​Tags

​Decision

​Why

​Structure

​Trade-offs

​Rules for agents

​Bad pattern (do not generate)

​Good pattern

ADR-0004: Shared kernel + Anti-Corruption Layer for inter-module user lookup

Status

Tags

Decision

Why

Structure

Trade-offs

Rules for agents

Bad pattern (do not generate)

Good pattern