Polylith compared to other software architectures

[tengstrand]

Polylith + Simple Guiding Rules

This is a discussion I want to have to see if my view of Polylith as an architecture aligns with the community’s.

Statement:

Polylith, combined with a few simple guiding rules, can naturally achieve the benefits of certain traditional architectures — without explicitly adopting them.

---

1. Architectures that naturally emerge from Polylith + simple rules

By following Polylith principles — composable components, bases, and projects — and adding minimal conventions, you automatically get:

Emergent Architecture	Guiding Rule	Benefit
Layered Architecture	Use single responsible components + only talk to "lower" layers [1]	Clear separation of concerns and easier maintainability
Hexagonal Architecture	Use single responsible components [2]	Separation of domain and adapters, testable and replaceable dependencies
Microservices	Make all projects independently deployable	Independently deployable services

Polylith itself is the architecture; other styles emerge from minimal, intentional conventions. Polylith also provides benefits not often found in other architectures, such as tooling support, smoother development, and a more flexible deployment situation.

¹ Let each layer (presentation, application, domain, infrastructure) become a collection of single-responsibility components (making each layer implicit). Each layer of components is only allowed to talk to "lower" layers. Similar architectures, such as Onion and Clean Architecture, will also rely on components, but with different conceptual layers.

² People sometimes suggest “use Hexagonal inside Polylith”, but that is misleading. Polylith already provides the core mechanisms Hexagonal aims to achieve: interfaces act as ports, components serve as "mini application cores" and outgoing adapters, and bases handle incoming adapters (see diagram below). With the small guiding rule of having pure domain components (along with other components) you automatically get the separation of concerns, testability, and replaceable dependencies Hexagonal promises. In other words, Hexagonal is not being embedded into Polylith — following Polylith correctly makes its benefits emerge naturally.

The diagram is taken from this blog post, where I explain Polylith through the lens of Hexagonal Architecture. It shows a base (1) delegating to a domain component (3) which communicates with three other domain components and two infrastructural components via their interfaces (4). As you can see, there are no ports, adapters, or application core here, only a base and a set of components.

---

2. Architectures that do NOT automatically emerge

Some architectures depend heavily on runtime behavior or distributed guarantees, which Polylith alone does not enforce:

Architecture	Why Polylith + simple rules isn’t sufficient
Event-Driven / Reactive	Requires runtime event buses, message ordering, and reactive flow guarantees
CQRS	Requires separate read/write models, eventual consistency, and data orchestration
Distributed Systems	Requires runtime coordination, fault tolerance, and consistency mechanisms

Polylith provides a strong foundation with many benefits over other architectures, but it doesn't automatically implement runtime guarantees or distributed behaviors, so additional design is required for such architectures.

Summary

Ultimately, you can use Polylith as a base architecture, and then add additional design to achieve the desired behavior of your systems.

/Joakim Tengstrand

[imrekoszo]

One thing I spotted:

such as Union and Clean

typo: union -> onion

Also, both Onion and Clean are variations of the Hexagonal architecture, not the Layered one directly.

[imrekoszo]

I still stand by my earlier comments on the topic in other places :)

benefits not often found in other architectures, such as tooling support, smoother development, and a more flexible deployment situation

This is the selling point of Polylith: the tooling that enables [smoother dev/incremental testing/flexible deployment strategies/etc] if you agree to organize your workspace according to the Polylith conventions.

following Polylith correctly makes its benefits emerge naturally

It might be beneficial to separate Poly's documentation along the lines of:

1. Conventions that are strictly necessary to make the tooling work correctly (poly check, poly test, etc.)
   • in my view this is "following Polylith correctly", because these are what are enforced, and to a great benefit because it still leaves flexibility
2. Architectural recommendations not enforced by Polylith, but recommended by its authors
   • this is the "simple rules", "few simple guiding rules", "adding minimal conventions", "small guiding rule of having pure domain components" etc.

Architectures that do NOT automatically emerge

Following what I put in point 1 above does not make any architecture automatically emerge. This is actually a great thing because Polylith does not enforce any architecture, resulting in:

• easier adoption (I don't have to change the architecture of my services when I migrate them into a Polylith workspace)
• the freedom for any kind of architecture to emerge, even reactive/cqrs/etc, by letting the developers working in the workspace make the real architectural decisions
  • this is possible because the conventions that are enforced per point 1 (ex. "how to create an interface in Polylith") are orthogonal to the architectural decisions (ex. "what to put on this or that side of an interface", "which component (brick) should be dependent on which other component")

Following what I put in point 2 might result in what you put into the OP's point 1. However, on

Polylith itself is the architecture; other styles emerge from minimal, intentional conventions

and

People sometimes suggest “use Hexagonal inside Polylith”, but that is misleading

what emerge in these situations already have their names. If you start from a blank workspace, and Hexagonal emerges, then that's exactly Hexagonal inside a Polylith workspace. And this is good, because it's a known pattern and someone new to your workspace can just be told "yo, we're doing hexagonal here like so" and it will be clearer to them what will be expected from future contributions. It's like design patterns - conveying important information in a few words.

Ultimately, you can use Polylith as a base architecture, and then add additional design to achieve the desired behavior of your systems

My suggestion:

Ultimately, you can use Polylith as a workspace framework/tooling, providing you xyz benefits, while leaving you the ability to draw your architecture your way and achieve the desired behavior of your systems. Additionally, if you follow these architectural recommendations by its authors, you might naturally end up with something close to Hexagonal, deployed into microservices.

[tengstrand]

First, I want to say that we are pretty close in our opinions on the matter, but that there are some differences. I'm mostly looking for a coherent picture of what Polylith is in relation to other architectures, so I am eagerly awaiting what other users here think!

That said, my point was that if you have created a system that looks like the one on the right in the illustration (Polylith) then we have already fulfilled almost all of the design goals that the Hexagonal architecture is trying to solve, without having used its concepts or structure.

We can also turn the perspective around. The Hexagonal architecture does not fulfill several architectural goals that Polylith has, e.g. separating development from deployment, or being able to share components between projects (e.g. services). Just because an architecture does not fulfill all of the architectural goals of another architecture, it does not disqualify it as such. However, I agree that Polylith with its small shareable components is a good foundation for all conceivable architectural goals.

[seancorfield]

I've always had a hard time accepting that Polylith is an architecture in and of itself. It's an approach to code organization that supports various architectures and provides tooling to help developers understand and manage their monorepo codebase.

[tlonist-sang]

This aligns perfectly with my understanding of polylith.

[samuelludwig]

Hmm, maybe the argument of "what is an architecture really?" is a little too ontological/semantic to be useful here? (In which case we can reference a specific definition on wikipedia or something. The wikipedia one at least would support considering Polylith an architecture IMO:

Software architecture is the set of structures needed to reason about a software system and the discipline of creating such structures and systems. Each structure comprises software elements, relations among them, and properties of both elements and relations.

Though maybe that hinges on the further semantics of 'what is structure/elements/relations exactly?' ad infinitum.)

I think of Polylith as a code-base architecture, prescribing "organization rules" yes, but also "composition rules" (via the abstraction of components vs bases)- I do not think of Polylith as a system architecture, prescribing how to compose/orchestrate different services/artifacts.

[tengstrand]

I agree.

I see two categories of software architectures: those that organize code within a service, and those that orchestrate interactions between multiple services in a larger system.

Organizing code within a service – e.g. Polylith (*), Layered, Clean, Hexagonal, Onion.

Orchestrating interactions across services – e.g. Microservices, SOA, CQRS, Event-driven architectures.

The latter define boundaries, communication patterns, and data flow, while the former are primarily intended to make it easier to reason about, change, and test the code within each service.

As I see it, these categories complement each other.

(*) Polylith can also organize and share code across services, but let’s set that aside for now.

[drpnsystems]

[seancorfield]

☝️ This sounds like an LLM just regurgitated the Polylith documentation, rather than being an answer to the question?

[tengstrand]

Yes, I agree, so I deleted it.
@drpnsystems Please keep the information here relevant… though if you’re a bot, that might be a challenge.

[tlonist-sang]

I'm in favor of the statement proposed by @tengstrand. Our codebase is deeply influenced by one of your blogposts explaining polylith with hexagonal architecture(https://medium.com/@joakimtengstrand/understanding-polylith-through-the-lens-of-hexagonal-architecture-8e7c8757dab1). Our actual implementation combines the hexagonal aspects with domain driven design principles, and it works very well for us.