Modular Monolith

Module Structure

app/
├── modules/
│   ├── payment/
│   │   ├── api.go          # Public interface
│   │   ├── service.go      # Business logic
│   │   ├── repository.go   # Data access
│   │   ├── models.go       # Domain models
│   │   └── events.go       # Domain events
│   ├── billing/
│   │   ├── api.go
│   │   ├── service.go
│   │   └── ...
│   └── notification/
│       └── ...
├── shared/
│   ├── database.go
│   ├── logger.go
│   └── http.go
└── main.go

Module Public API

// payment/api.go — the ONLY exported interface
type PaymentService interface {
    ProcessPayment(ctx context.Context, req PaymentRequest) (PaymentResult, error)
    GetPaymentStatus(ctx context.Context, id string) (PaymentStatus, error)
}

Inter-Module Communication via Events

// payment/events.go
type PaymentCompletedEvent struct {
    PaymentID string
    Amount    int64
    Timestamp time.Time
}

// billing/service.go — subscribes, never imports payment internals
func (s *BillingService) OnPaymentCompleted(event PaymentCompletedEvent) error {
    return s.createInvoice(event.PaymentID, event.Amount)
}

Schema Isolation

-- Each module owns its schema
CREATE SCHEMA payment;
CREATE TABLE payment.transactions (...);

CREATE SCHEMA billing;
CREATE TABLE billing.invoices (...);

-- NO cross-schema joins in application code

Anti-Patterns

• Shared database tables: Two modules reading/writing the same table
• Premature microservices: Splitting into services before understanding domain boundaries
• Technical layer separation: Organizing by controllers/services/repos instead of by domain
• Circular module dependencies: Module A imports Module B which imports Module A
• God module: One module that knows about everything else
• Shared domain models: Using the same struct across module boundaries instead of mapping
• Direct database access: One module querying another module's tables directly

Checklist

• Each module has a defined public API (interface/contract)
• No cross-module database access
• Dependencies between modules are one-directional
• Shared code contains zero business logic
• Module boundaries map to business domains
• Cross-module communication uses events or explicit API calls
• Modules can be tested in isolation
• No circular dependencies (enforced by tooling if possible)