diff --git a/docs/core-concepts/building-blocks/domain-services.md b/docs/core-concepts/building-blocks/domain-services.md new file mode 100644 index 00000000..c5706cbb --- /dev/null +++ b/docs/core-concepts/building-blocks/domain-services.md @@ -0,0 +1,43 @@ +# Domain Services + +Domain services encapsulate domain logic that doesn't naturally fit within an +aggregate, entity or value object. Domain services are used to model operations +and behaviors that involve multiple entities. + +Domain services help to maintain a clean and organized domain model by +offloading operations that don't belong to any specific entity. + +## Facts + +### Domain Services encapsulate domain logic. { data-toc-label="Encapsulate Domain Logic" } +Domain services contain business logic that spans multiple entities or value +objects. They provide a place for operations that can't be naturally assigned +to a single entity. + +### Domain Services enforce business rules. { data-toc-label="Enforce Business Rules" } +Domain services can enforce business rules that apply to operations spanning +multiple entities. They ensure that the rules are consistently applied across +the domain model. + +### Domain Services should follow Ubiquitous Language. { data-toc-label="Service Names" } +The names of domain services should clearly indicate their purpose. A +meaningful name helps to communicate the service's role within the domain model. + +### Domain Services coordinate operations. { data-toc-label="Handle Complexity" } +Domain services often coordinate complex operations that involve multiple +entities or value objects. They orchestrate the interactions between these +objects to achieve a specific outcome. + +### Domain Services are stateless. { data-toc-label="Stateless" } +Domain services typically do not hold state. They operate on data provided to +them and persist or return results without maintaining internal state between +calls. + +### Domain Services define clear interfaces. { data-toc-label="Expose Interfaces" } +Domain services define clear and explicit interfaces, named to reflect the +business functionality. These interfaces describe the operations that the +service provides, making the service's role and capabilities clear. + +### Domain Services are invoked by application services. { data-toc-label="Used by Application Services" } +Services in the application layer, like Application services, Command handlers, +or Event handlers, invoke domain services to perform domain operations. diff --git a/docs/core-concepts/building-blocks/entities.md b/docs/core-concepts/building-blocks/entities.md index 43692ba3..e1d9b6d2 100644 --- a/docs/core-concepts/building-blocks/entities.md +++ b/docs/core-concepts/building-blocks/entities.md @@ -1,6 +1,59 @@ # Entities -Entities in one domain can be a Value Object in another. For example, a seat is -an Entity in the Theatre domain if the theatre allocate seat numbers to patrons. -If visitors are not allotted specific seats, then a seat can be considered a -ValueObject, as one seat can be exchanged with another. Value Objects are in detail further in this section. \ No newline at end of file +Entities are very similar to Aggregates in nature and purpose. In fact, +an Aggregate is nothing but an entity chosen to represent the entire cluster. + +Entities are mutable and encapsulate both state and behavior. They have +distinct identity. This identity remains consistent throughout +the life of the entity, regardless of changes to its attributes. + +## Facts + +### Entities have an identity. { data-toc-label="Identity" } +The primary characteristic of an entity is its unique identity, which +distinguishes it from other objects. This identity is independent of the +entity's attributes and remains constant throughout the entity's lifecycle. + +### Entities are mutable. { data-toc-label="Mutability" } +Entities can change state over time while maintaining their identity. +This mutability is essential for modeling real-world objects that undergo +various state changes. + +### Entities can contain other entities or value objects. { data-toc-label="Composition" } +Entities can compose other entities and value objects, enabling the modeling of +complex domain relationships. However, care should be taken to manage the +complexity and maintain the boundaries of aggregates. + +### Entities enforce business rules. { data-toc-label="Business Rules" } +Entities are responsible for ensuring that business rules and invariants are +upheld within their scope. They encapsulate the logic necessary to maintain +domain integrity. + +### Entities in one domain can be value objects in another. { data-toc-label="Entity or Value Object?" } +Entities in one domain can be a [Value Object](./value-objects.md) in another. + +For example, a seat is an Entity in the Theatre domain if the theatre allocate +seat numbers to patrons. If visitors are not allotted specific seats, then a +seat can be considered a ValueObject, as one seat can be exchanged with another. + +### Aggregates handle entity persistence. { data-toc-label="Persistence" } +Entities are persisted and retrieved through their aggregates. They should not +be queried or updated directly, as it can lead to an invalid state because of +unsatisfied domain invariants. + +### Entities are related through associations. { data-toc-label="Associations" } +Associations define how entities are connected. These associations are +typically managed within the context of an aggregate to ensure consistency and +integrity. + +### Entities can contain nested entities and value objects. { data-toc-label="Nested Objects" } +Entities can nest other entities and value objects to form hierarchical +structures. These nested objects are managed as part of the aggregate's +lifecycle and contribute to the overall state of the entity. + +### Entity graphs should be kept manageable. { data-toc-label="Nesting" } +While entities can form complex graphs, it is crucial to maintain manageable +structures to avoid excessive complexity. To ensure performance and +manageability, entities should be part of aggregates that are appropriately +sized. If an aggregate becomes too large, consider splitting it into smaller, +more manageable aggregates. diff --git a/docs/core-concepts/building-blocks/value-objects.md b/docs/core-concepts/building-blocks/value-objects.md new file mode 100644 index 00000000..8e260ba3 --- /dev/null +++ b/docs/core-concepts/building-blocks/value-objects.md @@ -0,0 +1,50 @@ +# Value Objects + +Value objects are immutable domain elements that are distinguished by their +properties rather than their identity. They are used to represent concepts in +the domain that have no unique identity but are defined by their attributes. + +Value objects help to create a rich domain model by encapsulating concepts +that are often represented as simple types. + +## Facts + +### Value Objects are immutable. { data-toc-label="Immutable" } +Once created, the state of a value object cannot be changed. This immutability +ensures that value objects preserve their integrity and consistency. + +### Value Objects are defined by their attributes. { data-toc-label="Data-based definition" } +The identity of a value object is based entirely on its attributes. +Two value objects with the same attribute values are considered equal, +regardless of their instance. + +### Value Objects are often used for descriptive purposes. { data-toc-label="Descriptive" } +Value objects are ideal for representing descriptive aspects of the domain, +such as measurements, monetary values, or other concepts that are defined by +their values. + +### Value Objects enforce business rules. { data-toc-label="Enclose Business Rules" } +Value objects can encapsulate business rules and constraints related to their +attributes. They ensure that the values they hold are always valid and +consistent. + +### Value Objects are nested within entities. { data-toc-label="Enclosed in Entities" } +Value objects are enclosed within aggregates and entities to represent +complex attributes. + +### Value Objects are persisted with entities. { data-toc-label="Persisted within Entities" } +Value objects are typically persisted as part of the entities or aggregates +they belong to. Their persistence is managed implicitly through the enclosing +entity or aggregate. + +When an entity is persisted, any value objects it contains +are also persisted. This ensures that the complete state of the entity, +including its descriptive attributes, is stored. + +### Value Objects can be composed of Value Objects. { data-toc-label="Nesting" } +Value objects can be composed to form complex types, but they do not have +independent identity and are always part of entities or aggregates. + +### Value Objects do not reference entities. { data-toc-label="No References" } +Value objects should not hold references to entities. They are self-contained +and defined solely by their attributes. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 2d6f9081..ce767212 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -12,20 +12,27 @@ p { line-height: 1.75em; } -a, a:hover, a:visited, a:active { +/* Don't change link color on visits */ +a, a:hover, a:visited { text-decoration: none; } +/* Bold links */ p a, article ul li a { font-weight: 600; } -.md-typeset h1, .md-typeset h2 { +/* Primary color and tighter space */ +.md-typeset h1, .md-typeset h2, .md-typeset h3 { color: var(--md-primary-fg-color); - font-weight: 800; letter-spacing: -.025em; } +/* Heavier fonts */ +.md-typeset h1, .md-typeset h2 { + font-weight: 800; +} + .md-typeset h1 { font-size: 1.875em; } @@ -39,14 +46,18 @@ p a, article ul li a { font-size: 1.25em; } +/* Spacing between nav links */ .md-nav { line-height: 1.5em; } -.md-nav__link { - color: var(--md-primary-fg-color) !important; +/* Change nav links color on the left nav bar */ +.md-nav--primary .md-nav__item--section label.md-nav__link, +.md-nav--lifted>.md-nav__list>.md-nav__item>[for] { + color: var(--md-primary-fg-color); } +/* Change nav title color */ .md-nav__title { color: var(--md-primary-fg-color) !important; } \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 296a58f2..0d785437 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,9 +82,9 @@ nav: - Building Blocks: - core-concepts/building-blocks/index.md - core-concepts/building-blocks/aggregates.md - # - core-concepts/building-blocks/entities.md - # - core-concepts/building-blocks/value-objects.md - # - core-concepts/building-blocks/domain-services.md + - core-concepts/building-blocks/entities.md + - core-concepts/building-blocks/value-objects.md + - core-concepts/building-blocks/domain-services.md # - core-concepts/building-blocks/commands.md # - core-concepts/building-blocks/command-handlers.md - core-concepts/building-blocks/events.md