Add domain layer core-concepts documentation

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.

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.
+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.

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.

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;
 }

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