Understanding the Domain and Building the Team: The Foundations of Change (II)

Embarking on a complex project necessitates comprehensive context gathering while simultaneously approaching domain knowledge from a fresh perspective, leveraging domain expert insights. This approach aligns the technical team with business objectives and establishes a foundational roadmap for informed decision-making throughout the product lifecycle.

Initial knowledge-gathering sessions with the previous team and current application users proved unproductive. We briefly considered proceeding independently, despite the inherent risks.

EventStorming: Unveiling the Domain

As tech lead, I championed a domain-driven approach from the outset, given the project's complexity and the team's need for ownership. This centered the domain, fostering a shared understanding (ubiquitous language) that streamlined communication and facilitated mapping the application's current state.

We initiated EventStorming sessions using a Miro template, providing structure and a legend for effective focus. Prior familiarity with EventStorming concepts, either through pre-session preparation or initial explanations, is highly beneficial.

Our structured EventStorming process comprised:

1. Exploring Domain Events (Big Picture): Identifying, chronologically ordering, and validating key system events with domain experts, highlighting gaps and dependencies.
2. Refinement and Analysis: Adding explanatory notes, documenting questions, deeply analyzing each event, and pinpointing critical decision points.
3. Domain Modeling: Identifying aggregates and boundaries, defining actors and roles, establishing triggering commands, documenting policies and business rules, and identifying internal/external event triggers.
4. Documentation and Validation: Organizing and cleaning collected information, establishing clear relationships, validating the model with stakeholders, and creating reference documentation.

EventStorming provided not only domain understanding but also a foundation for applying Domain-Driven Design (DDD) principles strategically and tactically.

Strategic Domain-Driven Design

A crucial initial step involved strategically structuring the domain. The system's complexity and the need for technical/business alignment led to adopting DDD principles. Context Mapping proved invaluable, even within our monolith awaiting refactoring. We identified Bounded Contexts, operating within a single technical context with a shared kernel. This analysis, while not deeply explored, guided the project toward a domain-oriented architecture, improving both technical development and cross-team collaboration.

Defining Boundaries (Bounded Contexts)

Identifying Bounded Contexts clarified inter-system and external system relationships, simplifying complexity and establishing a foundation for future modularization. These initial decisions will guide the monolith's decomposition into manageable components aligned with defined contexts. This also facilitated prioritization and identification of areas for simplification, decoupling, or elimination. We focused on implementing Anti-Corruption Layers (ACL) for external system interaction, preserving system integrity.

Five key contexts were identified:

• Order Assignment
• Label Generation
• Order Preparation
• E-commerce Integration
• Bulk Order Preparation

These decisions fostered sustainable architecture and aligned development with business needs.

Ubiquitous Language

Establishing a robust ubiquitous language proved vital. The benefits of a shared language, created through collaboration between domain experts and developers, far outweigh translation efforts or misinterpretations. This living resource connected the technical team with domain experts, improving communication, reducing misunderstandings, and ensuring accurate domain representation in the code. This fostered efficient, business-aligned technical solutions.

Tactical Domain-Driven Design

Following the strategic framework, we implemented tactical DDD principles to structure the code, reflecting domain reality and ensuring long-term sustainability.

Entities and Value Objects

Understanding the distinction between Entities and Value Objects is crucial.

Entities

Entities possess a unique, persistent identity, even with attribute changes. Examples include:

• Order
• Product
• Carrier
• Shop
• Customer

Value Objects

Value Objects lack individual identity; their value defines them. Identical attributes signify equivalence. They are immutable and ideal for encapsulating concepts appearing across the domain. Examples include:

• ProductReference
• ProductEan13
• OrderReference
• Price
• Weight
• ShippingNumber

This approach created more understandable and modular code with clearly defined responsibilities.

Example Value Object:

<?php
readonly class ProductEan13
{
    public string $value;

    public function __construct(string $value)
    {
        $pattern = '/^\d{13}$/';
        if (!preg_match($pattern, $value)) {
            throw new \Exception('Invalid product Ean13');
        }
        $this->value = $value;
    }
}

Services

Services are categorized by purpose and implemented patterns.

Domain Services

Domain Services encapsulate business logic not fitting into entities or values, operating strictly within domain rules without infrastructure dependencies.

<?php
readonly class ProductEan13
{
    public string $value;

    public function __construct(string $value)
    {
        $pattern = '/^\d{13}$/';
        if (!preg_match($pattern, $value)) {
            throw new \Exception('Invalid product Ean13');
        }
        $this->value = $value;
    }
}

Application Services

Application Services coordinate domain operations with external interactions, centralizing complex operations and separating domain and infrastructure. These include Use Cases, Command Handlers, and Event Handlers.

Infrastructure Services

Infrastructure Services handle external component interactions (databases, file systems, etc.), acting as adapters to maintain domain agnosticism.

<?php
class CheapestCarrierGetter
{
    public function get(
        DeliveryOptionCarrierCollection $deliveryOptionCarriers,
        Weight $orderWeight,
        Country $country,
        PostalCode $postalCode,
        bool $isCashOnDelivery = false,
    ): Carrier {
        // Logic to get the cheapest carrier
    }
}

Service Classification

Services are classified by function and associated design patterns: Transformers, Builders, Factories, Presenters, Notifiers, Validators, and Clients.

This initial domain modeling, though incomplete and iterative, fostered team participation and commitment. Further refinement and restructuring were anticipated.

Recommended DDD resources:

• "Domain-Driven Design: Tackling Complexity in the Heart of Software" by Eric Evans
• "Implementing Domain-Driven Design" by Vaughn Vernon
• "Domain-Driven Design in PHP" by Carlos Buenosvinos, Christian Soronellas & Keyvan Akbary

Building the Team: Tuckman's Stages

DDD adoption paralleled team formation, following Tuckman's stages (Forming, Storming, Norming, Performing).

Forming

Initial team members reviewed the project, documented operations, and established technical and organizational foundations (processes, standards, tools).

Storming

Minor disagreements led to defining working styles, communication methods, and decision-making processes.

Norming

Team agreements, coding standards, development processes, WIP limits, deployment rules, technical debt management, and ADRs were established.

Performing

The established framework enabled efficient product development, prioritizing valuable initiatives, and fostering a culture of continuous improvement.

Documentation: The Diátaxis Model

Documentation was managed using GitLab Pages and Jekyll with the Just the Docs theme, following the Diátaxis model: Tutorials, Guides, Explanations, and References. Automating documentation using Event Catalog and AsyncAPI was planned but not fully implemented.

The above is the detailed content of Understanding the Domain and Building the Team: The Foundations of Change (II). For more information, please follow other related articles on the PHP Chinese website!