DEV Community: Horse Patterns

Clean Architecture: The Four Concentric Circles Explained

Horse Patterns — Wed, 17 Sep 2025 19:36:38 +0000

In modern software development, complexity grows quickly. Without the right structure, codebases can become fragile, difficult to test, and costly to maintain. Clean Architecture offers a clear design philosophy that addresses these challenges head-on by keeping your core business logic pure, independent from frameworks, databases, and other external tools. As a result, your application remains maintainable, testable, and adaptable, even as technology evolves.

This article examines the principles of Clean Architecture, its structural organization, and a practical example of its implementation.

Defining Clean Architecture

Formal Definition:
Clean Architecture is a software design philosophy that organizes an application into distinct, independent layers. Its main goal is to separate core business rules from implementation details such as frameworks, databases, or user interfaces.

By applying this separation, you can:

Replace a database without touching your business logic.
Swap out a web framework without rewriting the entire system.
Test core rules without relying on slow, brittle external systems.

The Structure of Clean Architecture

Visualize Clean Architecture as four concentric circles, each representing a layer with a specific responsibility:

Entities – Enterprise Business Rules

Contain core domain models and rules.
Independent of frameworks, databases, or libraries.
Designed to be stable and reusable across multiple applications.

Use Cases – Application Business Rules

Define how the application responds to inputs.
Coordinate between entities and business rules.
Remain unaware of the web, UI, or database details.

Interface Adapters

Contain controllers, presenters, gateways, and mappers.
Adapt data between external systems and internal layers.
Translate input/output into forms that the core application understands.

Frameworks & Drivers

Include databases, web frameworks, file systems, or other external tools.
Considered “details” rather than the essence of the application.
Can be swapped without affecting the business logic.

The Importance of Clean Architecture

Separation of Concerns: Each layer focuses on a single purpose, making the system easier to maintain and extend.

Testability: Business rules can be tested without databases or frameworks.

Flexibility: Change frameworks, databases, or UI layers without touching the core logic.

Scalability: Supports growth and integration without sacrificing structure.

A Practical Example

The following example demonstrates how Clean Architecture principles can be applied in practice, illustrating the separation of concerns across its distinct concentric circles.

Domain Object - Entities

package com.thedevhorse.cleanarchitecture.domain;

public class Athlete {

    private String athleteId;
    private String name;
    private int age;
    private Category category;

    private Athlete(String athleteId,
                    String name,
                    int age) {
        this.athleteId = athleteId;
        this.name = name;
        this.age = age;
        setCategory(age);
    }

    public static Athlete create(final String athleteId,
                                 final String name,
                                 final int age) {
        return new Athlete(athleteId, name, age);
    }

}

Represents the core business entity. Independent from infrastructure, frameworks, or databases.

Use Case Implementation

package com.thedevhorse.cleanarchitecture.usecase;

public class AthleteUseCaseImpl implements AthleteInputPort {

    private final AthleteDaoOutputPort athleteDaoOutputPort;

    public AthleteUseCaseImpl(AthleteDaoOutputPort athleteDaoOutputPort) {
        this.athleteDaoOutputPort = athleteDaoOutputPort;
    }

    @Override
    public Athlete getAthlete(final String athleteId) {
        return athleteDaoOutputPort.getAthleteById(athleteId);
    }

    @Override
    public void createAthlete(final Athlete athlete) {
        athleteDaoOutputPort.createAthlete(athlete);
    }

    @Override
    public void updateAthlete(final Athlete athlete) {
        athleteDaoOutputPort.updateAthlete(athlete);
    }
}

Implements application-specific business rules, orchestrating actions between ports and entities.

Use Case - Input Port

package com.thedevhorse.cleanarchitecture.usecase.port.in;

public interface AthleteInputPort {

    Athlete getAthlete(String athleteId);

    void createAthlete(Athlete athlete);

    void updateAthlete(Athlete athlete);

}

Defines the contract for use cases, shielding the implementation from external dependencies.

Use Case - Output Port

package com.thedevhorse.cleanarchitecture.usecase.port.out;

public interface AthleteDaoOutputPort {

   Athlete getAthleteById(String athleteId);

   void createAthlete(Athlete athlete);

   void updateAthlete(Athlete athlete);
}

Specifies how the use case interacts with persistence layers without knowing the actual database details.

Interface Adapters – Controller

package com.thedevhorse.cleanarchitecture.infra.controller;

@RestController
@RequestMapping("/api/athletes")
public class AthleteController {

    private final AthleteInputPort athleteInputPort;

    public AthleteController(AthleteInputPort athleteInputPort) {
        this.athleteInputPort = athleteInputPort;
    }

    @GetMapping("/{athleteId}")
    public AthleteResponse getAthlete(@PathVariable String athleteId) {
        return mapToAthleteResponse(
                athleteInputPort.getAthlete(athleteId)
        );
    }

    @PostMapping
    public void createAthlete(@RequestBody AthleteRequest athleteRequest) {
        athleteInputPort.createAthlete(
                mapToAthlete(athleteRequest)
        );
    }

    @PutMapping
    public void updateAthlete(@RequestBody  AthleteRequest athleteRequest) {
        athleteInputPort.updateAthlete(
                mapToAthlete(athleteRequest)
        );
    }
}

Acts as the bridge between HTTP requests and the use case, adapting incoming and outgoing data.

Frameworks & Drivers – DB

package com.thedevhorse.cleanarchitecture.infra.repository;

@Component
public class AthleteDaoImpl implements AthleteDaoOutputPort {

    private final AthleteRepository athleteRepository;

    public AthleteDaoImpl(AthleteRepository athleteRepository) {
        this.athleteRepository = athleteRepository;
    }

    @Override
    public Athlete getAthleteById(final String athleteId) {
        return mapToAthlete(findEntityById(athleteId));
    }

    @Override
    public void createAthlete(Athlete athlete) {
        athleteRepository.save(mapToAthleteEntity(athlete));
    }

    @Override
    public void updateAthlete(Athlete athlete) {
        AthleteEntity athleteEntity = findEntityById(athlete.athleteId());
        athleteEntity.setAge(athlete.age());
        athleteEntity.setName(athlete.name());

        athleteRepository.save(athleteEntity);
    }
}

Implements persistence operations using a specific framework and database, hidden behind the output port interface.

Conclusion

By applying Clean Architecture, you build applications where:

Core business logic is isolated from technical details.
Responsibilities are clearly separated across layers.
Frameworks and tools are replaceable without rewriting the business core.

This results in flexible, maintainable, and testable systems — ready to evolve as your requirements change.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=4hVbaHeaJy4

Remember, real speed doesn't come from rushing. It comes from doing things right. As Robert C. Martin said, "The only way to go fast, is to go well."

References

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html

Microservices: Beyond the Word

Horse Patterns — Tue, 12 Aug 2025 18:33:45 +0000

The concept of microservices has gained popularity as a modern and flexible way to develop systems. However, as Martin Fowler said:

"The term 'microservice' is a label, not a description."
- Martin Fowler`

The trouble starts when the prefix "micro" is taken literally, leading teams to create overly fragmented, complex, and hard-to-maintain services. More important than size is the proper design of boundaries and service autonomy.

Beyond the Label

When we talk about microservices, the first image that comes to mind is of small, distributed chunks of code. But delivering real value requires careful design and execution.

If poorly applied, microservices can turn into a distributed monolith - with tight coupling, hard-to-manage dependencies, and complexity that grows exponentially.

To avoid this, some key principles should guide the design:

Clear boundaries: each service should represent a specific domain or subdomain, avoiding overlapping responsibilities.

Well-defined context: draw from Domain-Driven Design to ensure business rules are isolated and consistent.

True independence: each service should be developed, tested, deployed, and scaled independently, without being blocked by other teams or systems.

Single-team ownership: each service should be managed by only one team, ensuring clear responsibility and faster decision-making.

Following these principles, microservices stop being just "small bits of code" and become truly independent components, owned and managed by a single, cross-functional team, making them easier to maintain, scale, and evolve.

Conclusion

The "micro" in microservices is not about size, but about focus and independence. By thinking in terms of clear boundaries, well-defined context, and autonomy, we create systems that deliver more value to the domain and its users - without falling into the trap of excessive fragmentation.

More than following a trend, it's about applying a design that enables sustainable growth, simplified maintenance, and rapid evolution.

Additional Resources

Follow the YouTube channel for more tips about software architecture:
🟥▶️https://www.youtube.com/@HorsePatterns

Architectural Trade-offs: Making the Right Decision for Your Context

Horse Patterns — Tue, 05 Aug 2025 22:15:22 +0000

“Everything in software architecture is a trade-off.”

— First Law of Software Architecture

When it comes to software architecture, this quote couldn't be more accurate. Every architectural choice we make comes with its own set of benefits and compromises. Navigating these trade-offs thoughtfully is what separates a good system from a great one, or from one that fails to meet real-world demands.

Every architecture decision must be made with context in mind. That means carefully evaluating a variety of factors before landing on the right design for your system.

Some Considerations When Choosing an Architecture

Functional Requirements: The system must deliver the necessary features and behavior. Your architecture should support and enhance core functionality, not obstruct it.

Infrastructure Limitations and Cost: Cloud costs, data center constraints, or third-party licensing directly impact what is feasible.

Project Delivery Timeline: The architecture must support delivery within the expected time frame.

Technical Expertise of the Team: The development team has the skills and experience needed to support the chosen architecture.

Team Organization: The architecture should align with how your teams are structured and how they communicate. A good match between system design and team boundaries accelerates progress and reduces friction.

These are just some of the elements that influence architecture decisions. The right choice depends heavily on your unique situation.

Choosing the Right Fit for Your Architecture

There’s no one-size-fits-all. The right architecture depends on the team, the goals, and the constraints.

Whether you choose a Monolithic Architecture

A single codebase with a unified deployment. Simple to start with, but harder to scale and maintain as complexity grows.

A Microservices Architecture

Multiple independent services with clear responsibilities. Offers flexibility and scalability, but adds operational overhead.

Or a Shared-Kernel Architecture

A compromise between independence and shared responsibility. Encourages collaboration and reuse, but requires tight coordination.

Take the time to weigh the trade-offs and choose what best fits your team, context, and goals.

Conclusion

Software architecture is not about finding the perfect solution. It's about making the right trade-offs for your specific situation. Each decision must be grounded in a clear understanding of your requirements, limitations, and team structure.

By weighing the trade-offs of each architecture style and aligning them with your goals, you create a foundation for long-term success.

Additional Resources

Follow the YouTube channel for more tips about software architecture:
🟥▶️https://www.youtube.com/@HorsePatterns

Domain Event Pattern for Decoupled Architectures

Horse Patterns — Tue, 22 Jul 2025 22:32:54 +0000

In modern applications, different parts of a system often need to react to changes without being tightly coupled. For example, when a user registers or an order is placed, several components might need to send notifications, update analytics, or trigger workflows.

The Domain Event Pattern provides a clean solution to this problem by modeling significant business events as immutable facts. It allows systems to communicate through events in a decoupled way, making them more modular, scalable, and easier to maintain.

What is the Domain Event Pattern?

The Domain Event Pattern, a key concept in Domain-Driven Design (DDD), captures significant changes within your business domain as immutable events. A domain event represents a fact that has already occurred - such as "Order Created" or "User Registered" - and includes details like timestamps, unique IDs, and domain data. Because these events are immutable, they preserve the integrity of the system's history, making it easier to debug and audit.

The key advantage of this pattern is decoupling. When a domain event is raised, the producing code does not need to know who will handle it or how. This separation allows different parts of your application to work independently. It is especially powerful in complex systems or microservice architectures, where services can react to events without direct dependencies on each other.

Key Components of the Domain Event Pattern

Domain Event

A Domain Event represents something that has happened in the past and describes a change in the state of the domain. It must include the date of occurrence, the ID of the aggregate, and a message for subscribers. A domain event must be immutable, and its name should be written in the past to indicate that it has already occurred.

Event Publisher

The Event Publisher is responsible for broadcasting domain events. It decouples the producer, such as an order service, from consumers who might act on those events. These events can be published either synchronously or asynchronously, depending on your requirements.

Event Consumers / Handlers

Event Consumers or Handlers are components that react to domain events. For example, when an order is placed, one consumer might send a confirmation email, while another triggers a system notification.

Messaging System (Optional)

In distributed systems, a Messaging System can be introduced to carry domain events across service boundaries. Tools like Kafka or RabbitMQ are commonly used to facilitate cross-service communication, allowing different microservices to subscribe to and react to events independently.

Benefits of Domain Events

Loose Coupling: Producers and consumers do not need to know about each other, which reduces dependencies and makes your system easier to maintain and evolve.

Scalability: Asynchronous event handling enables the application to execute multiple operations concurrently, optimizing system resource utilization and improving both throughput and responsiveness.

Extensibility: Adding new event handlers becomes straightforward without altering existing code that produces events. This allows your system to adapt quickly to new requirements.

Traceability: Domain events leave a clear audit trail in your system. This means you always know what happened and when, making debugging and auditing much simpler.

Implementation Example

Now, a simple example of the Domain Event Pattern shows how all the pieces fit together to build a clean and decoupled system.

OrderMessage

We'll start with a class called OrderMessage. It's a container for order information, like ID, current status, and other relevant details. It also makes it easy to convert an Order object into an OrderMessage, allowing us to share order changes with other parts of the system.

public record OrderMessage(UUID orderId, Status status) {

    public static OrderMessage message(Order order) {
        return new OrderMessage(
                order.orderId(),
                order.status()
                ....
        );
    }
}

OrderCreated

Next up is OrderCreated, which represents our domain event. Imagine it as a notification about the newly created order so other components in the system can react appropriately. This class keeps track of a unique event ID, the order details using OrderMessage, and a timestamp indicating when the event occurred. A factory method is also provided to make the creation of these events straightforward and clean.

public record OrderCreated(UUID id, OrderMessage message, Instant occurred) implements DomainEvent {

    public static OrderCreated create(UUID id,
                                      OrderMessage message,
                                      Instant occurred) {
        return new OrderCreated(
                id,
                message,
                occurred
        );
    }
}

Order

Now let's take a look at the core domain object: the Order. It acts as an aggregate root that encapsulates business logic and key information. Any change to its status may represent a domain event, which must be propagated to other bounded contexts and external systems.

public class Order {

    private UUID orderId;
    private Status status;

    private Order(UUID orderId,
                  Status status) {
        this.orderId = orderId;
        this.status = status;
    }

    public static Order create(final UUID orderId,
                               final Status status) {
        return new Order(
                orderId,
                status
        );
    }
    ....
}

OrderServiceImpl

Finally, we have the OrderServiceImpl class, which handles the creation of orders in the system. This is where the Domain Event Pattern demonstrates its effectiveness.

In the createOrder method, when a new order is created, we immediately generate an OrderCreated event populated with the order's details and the current timestamp. Instead of acting directly on this event (such as sending notifications or updating analytics), we delegate it to a MessagePublisher.

This approach clearly illustrates the advantages of decoupling. The service responsible for creating the order does not need to know what actions will follow. It simply raises the event and proceeds, leaving it to other components of the system to determine how to handle it.

public class OrderServiceImpl implements OrderService {

    private final MessagePublisher messagePublisher;

    public OrderServiceImpl(MessagePublisher messagePublisher) {
        this.messagePublisher = messagePublisher;
    }

    @Override
    public void createOrder(Order order) {
        OrderCreated orderCreated = OrderCreated.create(
                order.orderId(),
                OrderMessage.message(order),
                Instant.now()
        );
        messagePublisher.publisher(orderCreated);
    }
}

Conclusion

The Domain Event Pattern provides a clean and efficient way to design systems that are extensible, scalable, and easy to maintain. It's especially powerful in complex domains or microservice architectures where changes in one part of the system need to trigger actions in another.

By capturing business events as immutable facts, you enable a richer, more auditable, and more modular architecture. This pattern helps you build software that's not only robust today but also ready to evolve with future requirements.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=fbk2xL3vgNI&t

Remember, real speed doesn't come from rushing. It comes from doing things right. As Robert C. Martin said, "The only way to go fast, is to go well."

References

Evans, E. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003.
Vernon, V. Implementing Domain-Driven Design. Addison-Wesley, 2013

Domain Model Patterns: Bringing Your Domain to Life

Horse Patterns — Thu, 03 Jul 2025 21:15:00 +0000

In complex software systems, how you structure your domain logic can make the difference between chaos and clarity. Domain Model Patterns provide a powerful way to organize business logic using objects that mirror the real-world rules and concepts of your application. These patterns help developers build expressive, maintainable, and adaptable systems that evolve gracefully with changing business needs.

Let's explore the key building blocks of the Domain Model and how they work together to bring your domain to life.

Value Objects: Small, Immutable and Value Equality

Value Objects are characterized solely by their attributes. They are immutable, meaning their internal state cannot be changed once created. Unlike entities, they have no identity. Two Value Objects with the same data are considered equal, regardless of where or how they are used. This makes them ideal for modeling concepts like measurements, addresses or contact information, where the focus is on the values themselves rather than on individual instances.

Example – Contact Value Object

Here's an implementation of a Contact Value Object. It includes validation for the email format and encapsulates contact details in an immutable, value-based structure:

public class Contact implements ValueObject {

    private String email;

    private String mobileNumber;

    private String address;

    private Contact(String email,
                    String mobileNumber,
                    String address) {
        setEmail(email);
        this.mobileNumber = mobileNumber;
        this.address = address;
    }

    public static Contact of(final String email,
                             final String mobileNumber,
                             final String address) {
        return new Contact(
                email,
                mobileNumber,
                address
        );
    }

    private void setEmail(String email) {
        requireNonNull(
                email,
                "the email cannot be null."
        );

        String regexPattern = "^(?=.{1,64}@)[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*@"
                + "[^-][A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*(\\.[A-Za-z]{2,})$";

        if (!isMatches(email, regexPattern)) {
            throw new IllegalArgumentException("Invalid email address.");
        }
        this.email = email;
    }
    .....
}

This approach ensures that each Contact object is always valid and consistent. Since it's immutable, any change (like updating the email) results in the creation of a new instance, preserving data integrity.

Entities: Unique Identity

Unlike Value Objects, Entities are defined by a unique identity that remains constant throughout their lifecycle. Their internal state may evolve, but their identity persists. Entities are used when it's important to track an object as a distinct individual over time, regardless of how its attributes change.

Example – PersonalData Entity

Here's an implementation of a PersonalData Entity. It uses a citizenId as a unique identifier and includes mutable fields such as name, age, and contact information:

public class PersonalData extends AbstractEntity<String> {

    private String name;
    private int age;
    private Contact contact;

    private PersonalData(String citizenId,
                         String name,
                         int age,
                         Contact contact) {
        super(citizenId);
        setContact(contact);
        this.age = age;
        setName(name);
    }

    public static PersonalData of(final String citizenId,
                                  final String name,
                                  final int age,
                                  final Contact contact) {
        return new PersonalData(
                citizenId,
                name,
                age,
                contact
        );
    }

    protected void updateEmail(final String newEmail) {
        this.contact = Contact.of(
                newEmail,
                contact.mobileNumber(),
                contact.address()
        );
    }
    .....
}

This example illustrates how Entities encapsulate both data and behavior. The PersonalData class ensures that business rules, such as input validation or managing state changes, are enforced through well-defined methods.

Aggregates: Enforcing Consistency Boundaries

An Aggregate is a group of related Entities and Value Objects treated as a single unit for data changes. It establishes a boundary that encapsulates business rules and enforces consistency.

At the heart of every Aggregate is the Aggregate Root, the only entry point for making changes within the boundary. This Root controls access and ensures the integrity of all enclosed components.

Example – Athlete Aggregate Root or Root Entity

The Athlete class serves as the Aggregate Root. It encapsulates related information such as PersonalData and Category, and provides methods to enforce business rules like updating contact info or assigning a category based on age:

public class Athlete extends AbstractAggregateRoot<String> {

    private PersonalData personalData;
    private Category category;

    private Athlete(String athleteId,
                    PersonalData personalData) {
        super(athleteId);
        setPersonalData(personalData);
        setCategory(personalData.age());
    }

    public static Athlete create(final String athleteId,
                                 final PersonalData personalData) {
        return new Athlete(
                athleteId,
                personalData
        );
    }

    public void updateEmail(final String newMobileNumber) {
        this.personalData.updateEmail(newMobileNumber);
    }

    private void setPersonalData(PersonalData personalData) {
        this.personalData = requireNonNull(
                personalData,
                "The personalData cannot be null."
        );
    }

    private void setCategory(int age) {
        this.category = Arrays.stream(Category.values())
                .filter(c -> age >= c.minAge() && age <= c.maxAge())
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException("Category not found for the age: " + age));
    }
    .....
}

This example highlights how the Athlete class acts as a gateway to the aggregate. All updates, such as changing an email address or determining the athlete's category based on age, are managed through this root. This ensures that the internal state of the aggregate remains valid and consistent.

Supporting Patterns: Repositories, Domain Services and Factories

Beyond the core domain model, supporting patterns help organize responsibilities, reduce complexity and maintain a clear separation of concerns.

Repositories

Repositories provide controlled access to Aggregates. They handle storing, retrieving and searching for domain objects without leaking persistence logic into the domain model itself.

Domain Services

A Domain Service handles business operations that don't naturally belong to any single Entity or Value Object. It is stateless and often coordinates activities across multiple Aggregates.

Factories

Factories encapsulate the creation logic of complex objects, ensuring that Entities and Aggregates are always instantiated in a valid, consistent state.

Conclusion

Applying Domain Model Patterns is more than an architectural choice - it's a mindset that brings clarity, robustness, and agility to your software. By distinguishing between Value Objects and Entities, organizing related data into Aggregates, and supporting them with Repositories, Domain Services, and Factories, you can design systems that reflect the true nature of your business domain.

These patterns not only help you write cleaner code but also ensure that your software remains flexible and adaptable as it grows. Embrace these principles, and you'll be well on your way to building software that stands the test of time.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=cb_h_LHMgjw&t

Remember, real speed doesn't come from rushing. It comes from doing things right. As Robert C. Martin said, “The only way to go fast, is to go well.

References

Evans, E. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003.
Vernon, V. Implementing Domain-Driven Design. Addison-Wesley, 2013.

Understanding Domain-Driven Design (DDD)

Horse Patterns — Sun, 15 Jun 2025 16:40:22 +0000

Domain-Driven Design (DDD) is a powerful approach to designing and building complex software systems. Introduced by Eric Evans in his influential book Domain-Driven Design: Tackling Complexity in the Heart of Software (2003), DDD provides both strategic principles and tactical patterns that help teams create scalable, maintainable, and business-aligned software.

What is Domain-Driven Design?

DDD encourages teams to focus on the business domain, the core area of knowledge and activity around which the business revolves. Rather than viewing software as just code or infrastructure, DDD promotes building software that mirrors and models real-world business processes and logic.

By understanding the domain deeply, developers can craft systems that are not only functional but also aligned with the needs and goals of the business.

Why Domain-Driven Design Is a Game Changer

Solves Complex Business Problems
DDD shines in areas with intricate business logic, such as finance, healthcare, and logistics, because it models these complexities directly in the software.

Improves Communication
By using a Ubiquitous Language, DDD fosters a shared vocabulary among developers, stakeholders, and domain experts, reducing miscommunication.

Enhances Maintainability and Scalability
DDD’s modular approach, especially through Bounded Contexts, helps teams build systems that are easier to evolve and extend over time.

Supports Modern Architectures
DDD aligns well with Microservices and Event-Driven Systems, promoting loose coupling, autonomy and flexibility.

Aligns Code with Business Needs
By constantly refining the Domain Model, teams ensure that the software adapts as business requirements change, avoiding costly rewrites.

The Pillars of Domain-Driven Design

To apply Domain-Driven Design effectively, it's important to understand its foundational concepts. These core pillars provide the structure and mindset necessary to model complex domains with clarity and precision. Let's examine each pillar to understand how it supports the design of effective and maintainable software systems.

1. Ubiquitous Language
A Ubiquitous Language is a shared, domain-specific vocabulary used consistently by all team members.

Applied in code, documentation, and discussions.
Developed collaboratively with domain experts.
Ensures clarity and avoids ambiguity.

Example:
In an e-commerce platform, instead of generically saying Order, the team uses specific terms like Purchase Order, Shipment, and Payment Transaction to reflect the business accurately.

Benefits:

Eliminates miscommunication.
Improves understanding.
Enhances consistency across the codebase.

2. Bounded Context
A Bounded Context defines a logical boundary within which a particular domain model is valid. It isolates different interpretations and usages of the same term in different parts of the system.

Example (E-Commerce Platform Subdomains):

Customer (Supporting Subdomain): Manages customer profiles and preferences.

Order (Core Subdomain): Manages order creation, payment and shipping, which are central to the business.

Inventory (Generic Subdomain): Handles stock and logistics using standard industry practices.

Each of these subdomains operates in its own Bounded Context, allowing teams to model them independently and clearly.

Benefits:

Encourages modular design.
Prevents model conflicts.
Enables team autonomy and parallel development.

3. Context Map
A Context Map describes how multiple Bounded Contexts relate and interact with each other in a system.

Common Relationship Types:

Shared Kernel: A small shared model used across contexts (requires collaboration).

Partnership: Tight coordination and mutual dependency.

Customer–Supplier: The upstream context provides services or data (the Supplier), while the downstream context (the Customer) consumes it and adapts accordingly.

Anti-Corruption Layer (ACL): A translation layer that protects domain purity when integrating external or upstream models.

Example (Context Map in Action):

Shared Kernel: Customer and Order contexts share a small, common data model (e.g., customer IDs).

Anti-Corruption Layer (ACL): Order communicates with Inventory through an ACL to protect its domain model from upstream changes.

Benefits:

Supports safe integrations.
Maintains context independence.
Reduces coupling between domains.

Advanced Tactical Patterns in DDD

Beyond its core principles, Domain-Driven Design includes powerful tactical patterns that guide the implementation of domain logic.

Aggregate Roots define transactional boundaries and ensure consistency across related entities.

Entities and Value Objects model real-world concepts - Entities have distinct identities, while Value Objects are immutable and defined by their properties.

Domain Events represent meaningful domain changes, enabling decoupled communication and supporting event-driven designs.

Repositories abstract data access, allowing developers to interact with aggregates using domain language instead of persistence logic.

Domain Services encapsulate business operations that don't naturally belong to any single entity or value object.

Factories manage the creation of complex objects or aggregates, ensuring they're instantiated in a valid and consistent state.

Together, these patterns create a clean, expressive, and maintainable domain model that supports business goals and system scalability.

Conclusion

Domain-Driven Design is more than a methodology, it's a mindset focused on modeling software that mirrors the business it serves.

Ubiquitous Language fosters communication and shared understanding.
Bounded Contexts maintain clarity and modularity in complex systems.
Context Mapping defines how parts of the system collaborate effectively.
Tactical Patterns provide the tools to implement business logic cleanly and effectively.

By adopting DDD, software teams can build systems that are technically sound, aligned with business strategy, and ready to evolve alongside the organization.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=tLaw8kvm_xA&t

Remember, real speed doesn't come from rushing. It comes from doing things right. As Robert C. Martin said, “The only way to go fast, is to go well.”

References

Evans, E. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003.
Vernon, V. Implementing Domain-Driven Design. Addison-Wesley, 2013.

Domain Validation with the Notification Pattern

Horse Patterns — Wed, 28 May 2025 20:09:13 +0000

In software engineering, validation is an essential step, especially when handling user input or ensuring compliance with business rules. Although it’s common to use exceptions to signal errors, this approach can be ineffective for expected issues, such as empty fields or invalid formats.

The Notification Pattern addresses this problem by collecting all errors in a notification object, allowing them to be handled in a structured way and presented to the user clearly and efficiently.

What is the Notification Pattern?

The Notification Pattern is a design strategy that collects validation errors rather than throwing exceptions immediately. It allows your application to gather multiple issues in one go and report them collectively, which is especially useful when validating complex domain objects.

This approach provides users with comprehensive feedback and developers with cleaner, more maintainable code.

Why Use the Notification Pattern?

Prevents Overuse of Exceptions: Exceptions should signal unexpected errors. Validation errors, however, are expected and should be handled differently.

Better User Feedback: Multiple validation errors can be collected and displayed together, preventing a frustrating “whack-a-mole” experience for users.

Decoupling Logic: By using the Notification Pattern, validation logic is separated from the flow control of the program, making it easier to maintain.

How the Notification Pattern Works

The Notification Pattern introduces a structured flow to handling validation in your domain models. Rather than interrupting execution with exceptions, it captures and organizes all issues for smarter downstream handling.

Notification Object
A centralized container that holds a list of validation errors. It acts as an error aggregator across multiple fields or objects within the domain logic.

Validation Phase
Instead of immediately throwing exceptions when a validation rule fails, the rule appends an error message to the notification object. This continues for all validations, allowing the system to collect every issue in one pass.

Error Handling
Once all validations are complete, the application checks the notification object. If errors are present, a domain-specific exception (like DomainViolationException) can be thrown, or the errors can be handled gracefully.

Sample Implementation

Structure of the Notification Pattern

The Notification Pattern is composed of three main parts that work together to validate domain models without immediately throwing exceptions:

Validation Interface
A common contract that defines how individual validation rules behave.
Custom Exception
An exception that wraps all collected violations into a single throwable unit, allowing for comprehensive error reporting.
Notification Object
An accumulator that gathers all validation errors for a given domain object.

Validation Interface

public interface DomainValidation {

    <T> String getErrorMessage(T obj);
    public abstract <T> boolean isValid(T obj);

}

Custom Exception

public class DomainViolationException extends RuntimeException {

    private Set<Violation> violations;

    public DomainViolationException(Class claz) {
        super(String.format("Violation of Domain rules in object %s", claz.getSimpleName()));
        this.violations = new HashSet<>();
    }

    public void addViolation(Violation violation) {
        this.violations.add(violation);
    }

    public Set<Violation> getViolations() {
        return violations;
    }
}

Notification Object

public class DomainExceptionNotification {

    private DomainViolationException exception;

    public <T> DomainExceptionNotification(Class<T> claz) {
        this.exception = new DomainViolationException(claz);
    }

    public <T> T validateAndSet(String objName, T obj, DomainValidation violation) {
        if (!violation.isValid(obj)) {
            this.exception.addViolation(new DomainViolationException.Violation(objName, violation.getErrorMessage(obj)));
        }

        return obj;
    }

    public void validateDomainObject() {
        if (!this.exception.getViolations().isEmpty()) {
            throw this.exception;
        }
    }

    public enum ValidationEnum implements DomainValidation {
        NULL("field cannot be null") {
            @Override
            public <T> boolean isValid(T obj) {
                return nonNull(obj);
            }
        },
        BLANK("field cannot be blank") {
            @Override
            public <T> boolean isValid(T obj) {
                return nonNull(obj) && !isBlank((String) obj);
            }
        };

        ValidationEnum(String errorMessage) {
            this.errorMessage = errorMessage;
        }

        private final String errorMessage;

        @Override
        public <T> String getErrorMessage(T obj) {
            return errorMessage;
        }

        @Override
        public abstract <T> boolean isValid(T obj);
    }
}

Applying to domain objects

Athlete Domain Object
Validates required fields (personalData and category) before creation.

public class Athlete {

    private PersonalData personalData;

    private Category category;

    private Athlete(String athleteId,
                    PersonalData personalData) {
        super(athleteId);

        DomainExceptionNotification notification = new DomainExceptionNotification(Athlete.class);
        this.personalData = notification.validateAndSet("personalData", personalData, DomainExceptionNotification.ValidationEnum.NULL);

        if (nonNull(personalData)) {
            this.category = notification.validateAndSet("category", Category.findCategoryFromAge(personalData().age()), DomainExceptionNotification.ValidationEnum.NULL);
        }

        notification.validateDomainObject();
    }
}

Contact Domain Object
Validates the email field using a custom rule.

public class Contact {

    private String email;

    private String mobileNumber;

    private String address;

    private Contact(String email,
                    String mobileNumber,
                    String address) {
        DomainExceptionNotification notification = new DomainExceptionNotification(Contact.class);

        this.email = notification.validateAndSet("email", email, new EmailValidation());
        this.mobileNumber = mobileNumber;
        this.address = address;

        notification.validateDomainObject();
    }

    public static Contact of(final String email,
                             final String mobileNumber,
                             final String address) {
        return new Contact(
                email,
                mobileNumber,
                address
        );
    }
}

Conclusion

The Notification Pattern is a powerful technique for handling validation in domain-driven applications. It provides:

Cleaner code by avoiding excessive exception handling.
Improved feedback by reporting all errors at once.
Better maintainability through separation of validation and flow control.

By structuring your domain logic around notifications instead of exceptions, your applications become more robust, more user-friendly, and easier to evolve.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=pxpN4WJtrjU

Remember, real speed doesn’t come from rushing. It comes from doing things right. As Robert C. Martin said, “The only way to go fast, is to go well.”

References

Fowler, M. (n.d.). Notification. MartinFowler.com. https://martinfowler.com/eaaDev/Notification.html
BurnedPanic. notification-pattern. GitHub, https://github.com/BurnedPanic/notification-pattern

Simplifying Business Rules with the Specification Pattern

Horse Patterns — Sun, 04 May 2025 17:43:18 +0000

The Specification Pattern is a design pattern that allows you to encapsulate validation criteria in separate objects, making the code more modular and flexible. Instead of writing complex conditional logic directly in the main code, this responsibility is delegated to specification objects. This makes the code easier to understand, maintain, and extend.

What Is the Specification Pattern?

The Specification Pattern is a way to encapsulate business rules into reusable, composable objects.

Instead of cluttering your domain objects or services with multiple conditions, you define clear and testable specifications that determine whether an object meets certain criteria.

In simple terms:
🔹 It separates business logic from domain models.
🔹 It allows flexible and reusable rule composition (AND, OR, NOT conditions).
🔹 It makes code more readable, testable, and maintainable.

When to Use the Specification Pattern

Your business logic is complex and frequently changes.
You need to reuse rules across multiple parts of the application.
You want to keep domain models lightweight and focused.
You are following Domain-Driven Design (DDD) principle

Applying the Specification Pattern

Let’s consider an example: a weightlifting competition system where athletes qualify for specific events based on their performance in lifts like the Snatch and Clean & Jerk.

A bad approach would be stuffing complex if-else conditions directly into domain models. This makes the code harder to read and reduces flexibility when business rules change.

The Specification Pattern offers a cleaner solution: it extracts these conditions into self-contained objects that can be combined dynamically.

Example: Weightlifting Competition

Specification objects contain individual validation rules. In the given code, there are classes such as:

Specification Objects

public class CleanAndJerkOlympicsSpecification extends CompositeSpecification<Double> {

    private static final double MINIMUM_WEIGHT = 200.0;

    @Override
    public BiPredicate<Double, Double> toPredicate() {
        return (snatch, cleanAndJerk) -> cleanAndJerk > MINIMUM_WEIGHT;
    }
}

A similar specification would be created for the Snatch.

Composing Specifications

Specifications can be combined using logical operators like AND and OR. For example:

private void setEligibleForOlympics(double snatchWeight, double cleanAndJerkWeight) {
    this.eligibleForOlympics = new CleanAndJerkOlympicsSpecification()
            .and(new SnatchOlympicsSpecification())
            .toPredicate()
            .test(snatchWeight, cleanAndJerkWeight);
}

Each specification is transformed into a Predicate, which is a condition that can be tested. The toPredicate() method converts each specification into a boolean condition that can be tested using the athlete’s snatch and clean & jerk weights.

Additional Example: Email Validation

Specifications can also validate other types of data, such as email addresses:

public class EmailSpecification implements Specification<String> {

    @Override
    public boolean isSatisfiedBy(String email) {
        return Pattern.compile("^(.+)@(\\S+)$")
                .matcher(email)
                .matches();
    }
}

The code below shows how to use EmailSpecification to validate an athlete’s email.

private void setAthleteEmail(String athleteEmail) {
    boolean isValidEmail = new EmailSpecification().isSatisfiedBy(athleteEmail);

    if (!isValidEmail) {
        throw new IllegalArgumentException("Invalid email.");
    }

    this.athleteEmail = athleteEmail;
}

Conclusion

The Specification Pattern allows you to encapsulate business rules into separate, composable components, making the code modular, reusable, and easier to maintain. It is particularly useful when there are multiple complex conditions that need to be evaluated against objects, such as checking an athlete’s eligibility for competitions or validating input like email addresses.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=ByERVyGQN_A

Remember, real speed doesn’t come from rushing. It comes from doing things right. As Robert C. Martin said, “The only way to go fast, is to go well.”

References

Specification Pattern — Martin Fowler’s Catalog of Patterns of Enterprise Application Architecture: https://martinfowler.com/apsupp/spec.pdf

Embracing Rich Domain Objects: A Practical Guide

Horse Patterns — Sat, 03 May 2025 19:47:50 +0000

In the domain of software design, the way data is modeled significantly impacts the clarity, robustness, and scalability of an application. As systems evolve and become increasingly complex, the need for clear domain boundaries and well-encapsulated behavior becomes essential.

This is where Rich Domain Objects (RDO) offer a compelling solution. RDOs advocate for encapsulating both state and behavior within domain entities, thereby promoting a more cohesive and maintainable architecture.

In this article, we will explore the concept of Rich Domain Objects, their benefits, and how they can be effectively implemented in Java using a practical, real-world example. By the end, you will gain a deeper understanding of this approach and walk away with testable, production-ready code.

Understanding Rich Domain Objects

Rich Domain Objects are rooted in the principles of Domain-Driven Design (DDD). They encourage developers to model software entities based not solely on data structure, but also on domain specific responsibilities and behavior.

Unlike anemic domain models, which serve merely as data containers, Rich Domain Objects (RDOs) encapsulate:

State (data)
Business logic (behavior)
Validation rules (ensure data integrity and enforce domain constraints)

This encapsulation ensures that domain rules are enforced consistently and that object behavior remains predictable and coherent.

Advantages of Rich Domain Objects

Adopting Rich Domain Objects offers several architectural and development benefits.

Encapsulation of Business Logic: By keeping business rules within the domain model, logic stays close to the data it governs, reducing scattering across services or controllers.

Improved Domain Consistency: Validation and rule enforcement are centralized, preventing invalid states from emerging during runtime.

Self-Validation: Objects verify their own validity upon state changes, resulting in more reliable systems.

Expressive APIs: Methods such as changeCategory() communicate domain intent more clearly than traditional setters like setCategory() and setAge().

Business-Aligned Code: The object model naturally mirrors domain language, improving communication between technical and non-technical stakeholders.

Practical Example: Modeling an Athlete Domain

To demonstrate the utility of RDOs, let us consider an Athlete class responsible for managing personal data and categorizing athletes based on their age.

public class Athlete {

    private final String name;
    private int age;
    private Category category;

    private Athlete(String name, int age) {
        this.name = name;
        setAge(age);
        setCategory(age);
    }

    public static Athlete create(String name, int age) {
        return new Athlete(name, age);
    }

    public String name() { return name; }
    public int age() { return age; }
    public Category category() { return category; }

    public void changeCategory(int age) {
        setAge(age);
        setCategory(age);
    }

    private void setAge(int age) {
        if (age <= 0) {
            throw new IllegalArgumentException("Age must be a positive number.");
        }
        this.age = age;
    }

    private void setCategory(int age) {
        this.category = Arrays.stream(Category.values())
                .filter(c -> age >= c.minAge() && age <= c.maxAge())
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException("Category not found for the age: " + age));
    }
}

This implementation ensures that age and category are always valid and correctly synchronized, reducing the likelihood of inconsistent object states.

The following Category enum provides a clear and self-contained definition of age-based classifications:

public enum Category {
    JUNIOR(10, 17),
    ELITE(18, 35),
    MASTER(36, 99);

    private final int minAge;
    private final int maxAge;

    Category(int minAge, int maxAge) {
        this.minAge = minAge;
        this.maxAge = maxAge;
    }

    public int minAge() {
        return minAge;
    }

    public int maxAge() {
        return maxAge;
    }
}

Whenever an athlete’s age is set or updated, the appropriate category is automatically applied in accordance with the business rules.

Testing the Reliability of Rich Domain Objects

One of the key benefits of Rich Domain Objects is that they are inherently easier to test. Because the business logic is embedded within the domain itself, unit tests become more focused and reliable.

Below is a JUnit test suite that verifies the expected behavior of the Athlete class:

@Test
void givenValidInputs_whenCreateAthleteIsCalled_thenAthleteIsReturned() {
    Athlete athlete = Athlete.create("Horse Power", 37);
    Assertions.assertEquals(Category.MASTER, athlete.category());
}

@Test
void givenInvalidAge_whenCreateAthleteIsCalled_thenIllegalArgumentExceptionThrown() {
    String msg = assertThrows(IllegalArgumentException.class,
        () -> Athlete.create("Horse", 5)).getMessage();
    Assertions.assertEquals("Category not found for the age: 5", msg);
}

@Test
void givenNegativeAge_whenCreateAthleteIsCalled_thenExceptionThrown() {
    String msg = assertThrows(IllegalArgumentException.class,
        () -> Athlete.create("Horse", -5)).getMessage();
    Assertions.assertEquals("Age must be a positive number.", msg);

These tests demonstrate how domain rules are strictly enforced, ensuring the creation of only valid, well-formed objects.

Conclusion

Rich Domain Objects represent a fundamental shift toward more robust, behavior-oriented domain modeling. They enable developers to create systems that are not only easier to maintain but also more aligned with real-world business processes.

By embedding business logic within domain entities, developers can build applications that are resilient, expressive, and aligned with stakeholder language. This approach also facilitates better testing, clearer APIs, and a reduction in bugs related to invalid object states.

Before creating your next domain model, consider the following question:

Should this object merely store data, or should it also know how to manage and validate that data?

In many cases, the latter leads to a more accurate and effective design.

Additional Resources

For a step-by-step video walkthrough of this example and further explanation of the pattern in action, watch the full tutorial:

🟥▶️https://www.youtube.com/watch?v=uJ8BLJqaE8Q

Remember, real speed doesn’t come from rushing. It comes from doing things right. As Robert C. Martin said, “The only way to go fast, is to go well.”