application architecture   architecting   dark energy and dark matter   assemblage  

Introducing Assemblage - a microservice architecture definition process

The essence of applying the Microservice architecture pattern is defining the service architecture: identifying the services, defining their responsibilities, their APIs and their collaborations (with other services). Choosing the right technical architecture - deployment platform, message broker, etc. - also matters. But that’s a far easier and much less important task. That’s because if you define your services incorrectly you will create a fragile, and difficult to maintain distributed monolith that can threaten your organization’s very existence. And to make matters worse, defining the service architecture isn’t just a matter of reading the manual. It’s a design activity that involves numerous, and often tricky trade-offs.

I’ve written a lot about how the dark energy and dark matter forces can help define a service architeture. And, in a few talks, I’ve briefly described the architecture definition process, which is based on dark energy/matter, that I like to use. But until now, it’s not something I’ve described in detail outside of my microservice architecture workshops. The goal of this article is to properly introduce my architecture definition process, which I’ve named Assemblage.

Overview of Assemblage

The input to the architecture definition process consists of the application’s requirements, e.g. user stories/scenarios, non-functional requirements, wireframes, etc. The output of the process is a service architecture, which consists of the services, and their responsibilities, APIs, and collaborations.

The architecture definition process consists of the following steps:

  1. Discovering system operations
  2. Defining subdomains
  3. Designing services and their collaborations
  4. Evaluating a microservice architecture
  5. Refactoring a microservice architecture

Step 1: Discovering system operations

The first step of the process distills the requirements into a set of system operations. A system operation is an invokable behavior implemented by the application. For example, an e-commerce application would typically implement operations such as createCustomer(), createOrder(), cancelOrder() and findOrderHistory(). A system operation reads and/or writes one or more business entities, a.k.a. DDD aggregates, such as Customer and Order. The system operations model the application’s black box behavior.

A system operation is technology independent. But the actual implementation will be invoked in one of several ways. It might, for example, be invoked by a HTTP request or a message. Alternatively, a system operation might be triggered by the passing of time, eg. a monthly batch job.

Learn more…

Step 2: Defining subdomains

The second step of the process defines the subdomains. A subdomain is an implementable model of a sliver of business functionality, a.k.a. business capability. Each subdomain is owned by a small team. A subdomain consists of the aggregates acted upon by system operations. In Java application, for example, a subdomain would consist of Java classes.

Learn more…

Step 3: Designing services and their collaborations

The third step defines the service architecture by grouping the subdomains to form services and designing distributed system operations using the service collaboration (e.g. Saga, API Composition, and CQRS) patterns.

The dark energy and dark matter forces drive the definition of services and the design of system operations.

The output of the third step is a candidate service architecture that is either a monolithic architecture (i.e. a single service) or a microservice architecture (two or more services). The architecture documentation includes a microservice canvas for each service.

Learn more…

Step 4: Evaluating the microservice architecture

The fourth step evaluates the architecture to identify architectural issues/smells that are potential violations of the dark energy and dark matter forces.

Examples of architectural issues/smells include

  • Teams that lack of autonomy because too many teams work together on the same service
  • Services that repeatedly change in lock step due to design time coupling
  • Operation that have low availability and high latency because they span too many service and require too many network roundtrips

The output of fourth step is a list of potential architectural issues.

Step 5: Refactoring the microservice architecture

The fifth and final step refactors the architecture to eliminate architecture smells identified in the previous step. There are four levels of refactorings:

  • System operations - e.g. change collaboration patterns
  • Services - eg. move subdomains between services
  • Subdomains - e.g. split subdomains
  • System operation specifications - e.g. to reduce runtime coupling

The output of the fifth step is an improved microservice architecture.

When to use this process

Where to go from here

This process defines the services, and their responsibilities, APIs, and collaborations. The next step is to define the technical architecture. A big part of defining the technical architecture is selecting and applying the application infrastructure and infrastructure patterns from the microservices pattern language, e.g. deployment, observability, inter-service communication, etc. That’s a topic that I will describe in detail in future articles.

Learn more in my workshop

I’m available to teach a designing a microservice architecture definition workshop to teams at your organization. Please don’t hesitate to contact me.

Please note this workshop is only available for teams, not individuals.

application architecture   architecting   dark energy and dark matter   assemblage  

Copyright © 2024 Chris Richardson • All rights reserved • Supported by Kong.

About is brought to you by Chris Richardson. Experienced software architect, author of POJOs in Action, the creator of the original, and the author of Microservices patterns.

Chris helps organizations improve agility and competitiveness through better software architecture. Learn more about his consulting engagements, and training workshops.

Upcoming public talks/workshops


Premium content and office hours is now available for paid subscribers at


Chris teaches comprehensive workshops for architects and developers that will enable your organization use microservices effectively.

Avoid the pitfalls of adopting microservices and learn essential topics, such as service decomposition and design and how to refactor a monolith to microservices.

Learn more

LEARN about microservices

Chris offers numerous other resources for learning the microservice architecture.

Get the book: Microservices Patterns

Read Chris Richardson's book:

Example microservices applications

Want to see an example? Check out Chris Richardson's example applications. See code

Remote consulting session

Got a specific microservice architecture-related question? For example:

  • Wondering whether your organization should adopt microservices?
  • Want to know how to migrate your monolith to microservices?
  • Facing a tricky microservice architecture design problem?

Consider signing up for a two hour, highly focussed, consulting session.

Virtual bootcamp: Distributed data patterns in a microservice architecture

My virtual bootcamp, distributed data patterns in a microservice architecture, is now open for enrollment!

It covers the key distributed data management patterns including Saga, API Composition, and CQRS.

It consists of video lectures, code labs, and a weekly ask-me-anything video conference repeated in multiple timezones.

The regular price is $395/person but use coupon ILFJODYS to sign up for $95 (valid until March 12, 2024). There are deeper discounts for buying multiple seats.

Learn more

Learn how to create a service template and microservice chassis

Take a look at my Manning LiveProject that teaches you how to develop a service template and microservice chassis.

Signup for the newsletter

BUILD microservices

Ready to start using the microservice architecture?

Consulting services

Engage Chris to create a microservices adoption roadmap and help you define your microservice architecture,

The Eventuate platform

Use the platform to tackle distributed data management challenges in your microservices architecture.

Eventuate is Chris's latest startup. It makes it easy to use the Saga pattern to manage transactions and the CQRS pattern to implement queries.

ASSESS your architecture

Assess your application's microservice architecture and identify what needs to be improved.

Consulting services

Engage Chris to conduct an architectural assessment.

Join the microservices google group


Note: tagging is work-in-process

GitOps   ·  Microservices adoption   ·  ancient lore   ·  anti-patterns   ·  application api   ·  application architecture   ·  architecting   ·  architecture   ·  architecture documentation   ·  assemblage   ·  beer   ·  books   ·  containers   ·  dark energy and dark matter   ·  deployment   ·  deployment pipeline   ·  design-time coupling   ·  developer experience   ·  development   ·  devops   ·  docker   ·  eventuate platform   ·  generative AI   ·  glossary   ·  health   ·  hexagonal architecture   ·  implementing commands   ·  implementing queries   ·  inter-service communication   ·  kubernetes   ·  loose coupling   ·  microservice architecture   ·  microservice chassis   ·  microservices adoption   ·  microservicesio updates   ·  modular monolith   ·  multi-architecture docker images   ·  observability   ·  pattern   ·  refactoring to microservices   ·  resilience   ·  sagas   ·  security   ·  service api   ·  service architecture   ·  service blueprint   ·  service collaboration   ·  service design   ·  service discovery   ·  service granularity   ·  service template   ·  software delivery metrics   ·  success triangle   ·  tacos   ·  team topologies   ·  testing   ·  transaction management   ·  transactional messaging

All content


24 Jul 2017 » Revised data patterns