How do you compose multiple modules without creating a tangled architecture?

Composition is the design of module boundaries and the data that crosses them. A healthy root module reads top to bottom: network, data, application, observability. Each child exposes only what the next layer needs, so a change in one module does not ripple through every caller.

module "network" {
  source = "./modules/network"
  cidr   = "10.0.0.0/16"
}

module "app" {
  source    = "./modules/app"
  subnet_id = module.network.private_subnet_ids[0]
}

module "observability" {
  source  = "./modules/observability"
  app_arn = module.app.service_arn
}

Rules that keep composition manageable

• Pass values through outputs rather than reading another stack's state
• Keep dependencies one-directional; avoid circular module references
• Use separate state per lifecycle and blast radius
• Prefer a few focused modules over one god module with flags
• Version shared modules and test their interfaces

Passing providers explicitly is sometimes necessary for multi-region modules, but it couples the child to a provider configuration. Do it deliberately and document it. Similarly, terraform_remote_state is convenient but creates a runtime coupling to another stack's state schema and access controls.