Skip to content
Software Architecture Guide

Module

Explanation

Section titled “Explanation”

A person can only think about a limited number of things at once. Modules respond to that limit. They split a large model into smaller groups, so you can reason about one group without holding the rest in your head.

Modules divide concepts, not just code. Code often gets split by technical aspects of the architecture or by developer work assignments. Module guidance pushes against this. The question is not “who works on this?” but “which ideas belong together?”

Two rules guide the choice:

  • High cohesion. Each module holds a set of concepts that fit together. (See the articles High Cohesion and Coupling and Cohesion.)
  • Low coupling. Modules depend on each other as little as possible. Here, low coupling means concepts you can understand and reason about independently. It is not only a code metric.

Pick modules that tell the story of the system. A reader who sees the module names should learn what the system is about.

Module names should also enter the ubiquitous language, the shared vocabulary of the team (see the article Ubiquitous Language). If people say “Billing” in conversation and the structure says the same, the two match.

Domain-Driven Design also divides large models into bounded contexts with explicit relationships (see the article Bounded Context). Both ideas serve one goal: keeping a big model manageable.

When you implement a domain model, conceptual clarity comes before technical complexity.

Example

Section titled “Example”

A team builds a system for shipping goods. One option splits the code into “data access,” “services,” and “screens.” Every business idea is then spread across all three. Another option creates modules named after business ideas: “Customer,” “Billing,” and “Shipping.” Each module holds the concepts that belong together. The names are short, the team uses them in conversation, and a newcomer learns what the system does by reading them.

Trade-offs

Section titled “Trade-offs”

Clear concepts and minimal coupling can conflict. The facts support one direction: conceptual clarity should come before technical complexity. Accept some extra dependency if it keeps a module understandable as one idea.

Checks

Section titled “Checks”
  • Module names appear in the glossary and the team uses them as part of its shared vocabulary.
  • Modules are grouped by concepts of the domain, not by technical aspects or developer work assignments.
  • Each module holds a cohesive set of concepts, and the module list tells the story of the system.
  • Coupling between modules is judged by whether concepts can be understood independently.
Section titled “Related”

Sources

Section titled “Sources”