Java Microservices - Decomposition by Subdomain

---

---

Introduction

Modern software systems must evolve quickly, scale independently, and remain robust in the face of change. Microservices architecture provides a foundation for these requirements by breaking down applications into independent services.

However, how we decompose a system is critical. A poor decomposition can lead to tight coupling, poor scalability, and development friction. Among the various decomposition strategies, "Decomposition by Subdomain" − driven by Domain-Driven Design (DDD) − stands out as one of the most effective and sustainable methods.

This article explores the Decomposition by Subdomain pattern in microservices, its rationale, implementation approach, and real-world applications using Spring Boot.

What is Decomposition by Subdomain?

Definition

Decomposition by subdomain is a microservices design pattern that breaks a system into services based on domain substructures called subdomains, identified through Domain-Driven Design (DDD).

Instead of organizing services by technical functions (like DAO, controllers), we organize them by business function areas such as−

• Customer Management

• Billing

• Inventory

• Shipping

Each subdomain becomes a bounded context, which maps directly to a microservice.

Benefits of Decomposition by Subdomain

Identifying Subdomains: A Case Study

Let's consider an online learning platform like Coursera.

Business Capabilities

• User Registration

• Course Catalog

• Enrollment & Payment

• Content Delivery

• Certification

Decomposed Subdomains

Implementing the Pattern Using Spring Boot

We'll illustrate with two subdomains: Course Management and Enrollment.

Course-Service (Core Subdomain)

Responsibilities

• Manage course creation, categories, metadata.

CourseController.java

@RestController
@RequestMapping("/courses")
public class CourseController {
   @GetMapping("/{id}")
   public String getCourse(@PathVariable String id) {
      return "Course info for ID: " + id;
   }

   @PostMapping("/")
   public String createCourse(@RequestBody Course course) {
      return "Course created: " + course.getTitle();
   }
}

application.yml

spring:
  application:
    name: course-service
server:
  port: 8081

Enrollment-Service (Core Subdomain)

Responsibilities

• Manage student enrollment and payment status.

EnrollmentController.java

@RestController
@RequestMapping("/enrollments")
public class EnrollmentController {
   @PostMapping("/")
   public String enroll(@RequestBody Enrollment enrollment) {
      return "Student enrolled in course ID: " + enrollment.getCourseId();
   }
}

application.yml

spring:
  application:
    name: enrollment-service
server:
  port: 8082

Each service has −

• Its own data model

• Database

• And communicates via REST or asynchronous events.

Communicating Across Subdomains

Subdomain-based services often need to interact.

REST Call (Synchronous)

enrollment-service calls course-service to validate a course −

@Autowired
private RestTemplate restTemplate;

public String getCourse(String id) {
   return restTemplate.getForObject("http://course-service/courses/" + id, String.class);
}

Event-Driven (Asynchronous)

Using Kafka or RabbitMQ for loose coupling −

• course-service emits CourseCreatedEvent.

• enrollment-service listens and updates its cache.

Aligning Subdomains with Bounded Contexts

Subdomain decomposition often aligns with bounded contexts in DDD.

Bounded Context − A logical boundary where a particular domain model is defined and applicable.

This allows −

• Unique data models

• Different vocabularies

• Clear API boundaries

Example

• course-service uses CourseEntity

• enrollment-service uses CourseView (DTO)

This prevents leaky abstractions and supports data autonomy.

Subdomain Database Design

Each service/subdomain must own its data.

Microservice DB Ownership

No shared schemas or cross-database joins.

For queries across services: use data replication, event-driven updates, or API composition.

Best Practices and Considerations

Real-World Example: Netflix

Netflix decomposes by subdomain−

Each team owns one or more subdomains and releases features independently.

Challenges and How to Address Them

Conclusion

Decomposition by Subdomain is a powerful pattern that promotes −

• Business-aligned services

• Autonomous development teams

• Scalable and maintainable architecture

It fosters long-term agility by structuring software based on what the business actually does, not just on technology or project constraints.

With proper modeling, tooling, and communication strategies, subdomain decomposition leads to systems that are easier to build, grow, and maintain.