<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Joakim Tengstrand on Medium]]></title>
        <description><![CDATA[Stories by Joakim Tengstrand on Medium]]></description>
        <link>https://medium.com/@joakimtengstrand?source=rss-852c2bee3b00------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*oJvirGuwarRqXAcP-gPfqw.jpeg</url>
            <title>Stories by Joakim Tengstrand on Medium</title>
            <link>https://medium.com/@joakimtengstrand?source=rss-852c2bee3b00------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 14:15:17 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@joakimtengstrand/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Understanding Polylith through the lens of Hexagonal architecture]]></title>
            <link>https://medium.com/@joakimtengstrand/understanding-polylith-through-the-lens-of-hexagonal-architecture-8e7c8757dab1?source=rss-852c2bee3b00------2</link>
            <guid isPermaLink="false">https://medium.com/p/8e7c8757dab1</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-design]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[clojure]]></category>
            <dc:creator><![CDATA[Joakim Tengstrand]]></dc:creator>
            <pubDate>Wed, 01 Nov 2023 18:31:01 GMT</pubDate>
            <atom:updated>2025-12-09T07:40:37.588Z</atom:updated>
            <content:encoded><![CDATA[<p>This blog post has <a href="https://tengstrand.github.io/blog/2023-11-01-understanding-polylith-through-the-lens-of-hexagonal-architecture.html"><strong>moved here</strong></a>.</p><blockquote>In the Hexagonal architecture, we start with the application core, and let that grow over time. Polylith starts at another end, with the bricks, where each brick does one thing, and if we want to do one more thing, then we create another brick.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*upoMj6gkKpd_G4r7f8kwMQ.png" /></figure><p>If you are a fan of the <a href="https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)">Hexagonal</a> architecture, also known as Ports &amp; Adapters, we think you’ll love the way <a href="https://polylith.gitbook.io/polylith">Polylith</a> turns your system into fine-grained Lego-like bricks!</p><p>The Hexagonal architecture was invented in 2005 by <a href="https://en.wikipedia.org/wiki/Alistair_Cockburn">Alistair Cockburn</a>. His <a href="https://alistair.cockburn.us/hexagonal-architecture/">article</a> states that it “Allows an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases”.</p><p>The solution consists of three types of building blocks; <em>ports</em>, <em>adapters</em>, and the <em>application core:</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/684/1*aeaq0utQ-eiwlxIhltg5Bw.png" /></figure><p>The picture shows a user that interacts with a user interface that talks to a Hexagonal backend application. There is also another system that interacts directly with the same application.</p><p>The main idea in the Hexagonal architecture is to isolate the core from the outside world:</p><ol><li>The primary adapters (1) receive calls from different systems, and serve as a bridge between the application core (3) and the outside world.</li><li>The incoming ports (2) abstract away implementation details in the application core (3) and only expose what each adapter (1) needs to know.</li><li>The application core (3) consists of business domain logic for an application, and only knows about itself and outgoing ports (4).</li><li>The outgoing ports (4) expose functionality that is not part of the business logic (3), and abstract away implementation details in the secondary adapters (5).</li><li>The secondary adapters (5) implement the outgoing ports (4), typically IO operations such as interactions with databases, message queues, the file system, and third-party APIs.</li></ol><p>Let’s extract a slice, so we can more easily reason about these building blocks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/991/0*wlM4GNIFhfKUem1c" /></figure><p>This shows how a user, via a user interface (UI), talks to a REST service that communicates with a database.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/996/0*HRO424NL8r85VedR" /></figure><p>Here, a user uses a command line tool, which accesses a database and a file system from a shell.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/996/0*MbfW4v483_W4VpCE" /></figure><p>The architecture leaves some flexibility when it comes to how the ports can be organized. Here we have switched the number of incoming and outgoing ports.</p><p>The Hexagonal architecture makes the application core depend less on its surroundings, which makes it easier to test and e.g. use an in-memory database when testing the app with a script.</p><p>Alistair Cockburn doesn’t talk much about how to handle larger systems in his <a href="https://alistair.cockburn.us/hexagonal-architecture/">article</a>, but there is a “Distributed, Large-Team Development” section that mentions that a system can be split into several applications.</p><p><a href="https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)">Wikipedia</a> says that “According to some authors, the hexagonal architecture is at the origin of the <a href="https://en.wikipedia.org/wiki/Microservices">microservices</a> architecture”.</p><p>Here is how it may look like:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*21t1pqmugfglksC3w7lwhw.png" /></figure><p>If too many charts make your eyes hurt, hold on, further down there will be references to code examples.</p><p>Now it’s high time to look at how the Polylith architecture works!</p><h4>The Polylith way</h4><p>Polylith is a component based architecture that uses small LEGO®-like bricks that can be combined into various services and tools.</p><p>Working with a Polylith system is like having a Lego box with bricks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*1fHOrCium33a0TZNMxIjbg.png" /></figure><p>In the Lego box we find two categories of bricks. The components in green, and the bases in blue. More on these categories later.</p><p>The bricks can be combined into any set of services and tools, called projects in Polylith:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/504/1*y-ipbz3Ern1Sn2DN2AhdWg.png" /></figure><p>We also have a special project called development which contains all bricks, and is used when working with the code:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/200/1*5NqccxE_n5CTR-W-ebIR7A.png" /></figure><p>All bricks and projects live together in a <a href="https://en.wikipedia.org/wiki/Monorepo">monorepo</a>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/451/1*WoPvAFdy3yJMXwAygJd2cA.png" /></figure><p>Here we illustrate how bricks are used across projects:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/489/1*9IX5_ZB6S961OIXbaJR84w.png" /></figure><p>For example, the db component is used in both backend and email-lambda. This helps us remove code duplication and gives a tremendous level of reuse across the entire codebase.</p><h4>Development</h4><p>The development project gives us a monolithic development experience so we can easily search, test, refactor, and debug the code, even across services.</p><p>You may wonder what a single development project has to do with an architecture. There are three main reasons:</p><p>Firstly, it guarantees that all bricks fit together, so that they can be combined in any way into projects, and then be built into artifacts. Bricks have access to all other component interfaces, which make them easy to create.</p><p>Secondly, how the code is executed in production is an implementation detail in Polylith. The philosophy is that we should be able to change how to run the code in production without affecting the development experience, and vice versa.</p><p>Thirdly, the single development experience is there to speed up the feedback loop and to make us more productive. Having all the code in one place gives us a simpler development setup compared to having several services running locally. It also improves the testing experience, including potential support for incremental testing.</p><h4>Project</h4><p>A project is used to assemble a set of bricks into one place, so that we can build different kinds of artifacts from them, e.g. services and tools.</p><p>A command line tool can look something like this in Polylith:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*mx0_-hqf8sytrB5fd6pgXg.png" /></figure><p>We define a project in Polylith by listing the included bricks by name in a configuration file, similar to how libraries are handled but without giving a version.</p><p>This makes us stop thinking of code as layers or other shapes. Instead we can concentrate on one brick at a time, without caring about dependencies or how things are executed in production.</p><p>If we follow the call chain from the shell to the file system, it could look something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1008/0*T_jSUrLZcHC3betS" /></figure><p>The blue brick receives a call from the shell that delegates to a number of bricks, ending with the <em>file</em> brick that touches the file system.</p><h3>A comparison</h3><p>To better understand the difference between <a href="https://polylith.gitbook.io/polylith/">Polylith</a> and the <a href="https://alistair.cockburn.us/hexagonal-architecture">Hexagonal</a> architecture, let’s compare the two:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/0*in7XZRj5B8hnRpgC" /></figure><h4>Component</h4><p>Components in Polylith are our composable building blocks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*dOT17p1M9okaoyfv-3B58A.png" /></figure><p>A component (c) has an interface (i) that delegates incoming calls to its implementation (x). We often skip showing the interface and instead illustrate the component as a green box (c).</p><p>The interface (i) sometimes has the same role as a primary port (2):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/359/1*QSu7JBVZe9Dngd8NVbd4Zg.png" /></figure><p>In that case, the component implementation (x) corresponds to a subset (3) of an application core (6).</p><p>The interface (i) can also have the role of outgoing port (4):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/358/1*icvP18x9fh4oc5IHMPc-Sw.png" /></figure><p>In that case, the implementation (x) corresponds to the secondary adapter (5).</p><p>Components only know about interfaces (i).</p><h4>Base</h4><p>A base is a bridge between the outside world and the components it delegates to (via interfaces):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/350/1*utmMxfTNk13DZ3kbv_3uDg.png" /></figure><p>A base (b) has a public API (a) that receives incoming calls from the outside world (w), and delegates (d) them to interfaces (i) and in rare cases other bases (b). We often skip showing the different parts of the base (a + d) and instead illustrate it as a blue box (b).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/300/1*--uEx425xK7jhhsvfwQRkg.png" /></figure><p>A base (b) has the same role as the primary adapter (1) which is to expose a public API.</p><p>Bases only know about other bases and interfaces (i).</p><h4>Brick</h4><p>Brick is the common name for a component or base:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/180/1*00_s7auccDcDlx7ukPfYOA.png" /></figure><p>The name comes from the fact that they are small and composable, like LEGO® bricks.</p><p>A way of thinking about bricks is that they are Hexagon application cores in miniature:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/357/1*IXc1WP-PaytuqKGN3IOS7A.png" /></figure><p>This component accesses three different interfaces. The component doesn’t know how the interfaces are implemented, in the same way an application core doesn’t know which secondary adapters are behind the outgoing ports.</p><p>One difference is that behind the interfaces to the right, there can be both “secondary adapters” and pure domain logic.</p><p>To better understand the differences, you can see a Polylith project as made up by many “mini application cores”, which could look something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/511/1*iRrzkvoZzV4oEmtj8Vo97Q.png" /></figure><p>The “mini core” to the left is represented by a base in Polylith. The five domain “mini cores” in the middle will be components, and then we have two more “mini cores” to the right that encapsulate different IO-operations, which also will turn into components.</p><p>The eight “mini cores” are assembled into an application in Polylith:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/217/1*LHh89StWBwPlTrUt0hYYng.png" /></figure><p>Applications are called projects in Polylith, and are illustrated like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/200/1*nhPs9nk5TsU4HCmXcOfn0g.png" /></figure><p>Polylith doesn’t force you to organize your bricks in a certain way, but because it’s so easy to create small, cohesive components, a Polylith system tends to end up with many components, each of which does <a href="https://en.wikipedia.org/wiki/Single-responsibility_principle">one thing</a>.</p><p>That can be a subdomain, an interface to a database, or a third-party API.</p><h3>The Application core</h3><p>Let’s see what an application core could look like in Polylith.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/991/1*DKuUSkeTCuxfN5uTWl3hxw.png" /></figure><p>Here is an example of how a primary adapter (1) delegates to an incoming port (2) that delegates to a subdomain (3) that calls three other parts of the application domain (6) and two outgoing ports (4).</p><p>In Polylith, the base (1) does the same job as the primary adapter. The four subdomains and the two secondary ports with associated secondary adapters, are replaced by six components in this example.</p><p>If we strip away the calls, the two applications can be illustrated like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/886/1*O_Cm87gB-dP-SLcW6pW38Q.png" /></figure><p>In the Hexagonal architecture, we start with the application core, and let that grow over time, and maybe split it up into smaller pieces when it gets too big. Alistair’s <a href="https://alistair.cockburn.us/hexagonal-architecture/">article</a> has examples on how to isolate the application core, but leaves no guidance on how to structure the code inside the core.</p><p>Polylith starts at another end, with the bricks. A brick does one thing, and if we want to do one more thing, then we create another brick. We don’t have one or more “application bricks” that we continuously add code to. Instead we end up with a set of bricks that can be put together into various projects.</p><p>Exactly how the code should be executed in production can be postponed to later, and also be easily changed when needed, by regrouping the bricks.</p><h3>Composability</h3><p>In object oriented languages, functionality is oriented around objects, but often with one exception: arithmetic operations.</p><p>Back in time when most object oriented languages didn’t have good support for functional style programming, you could still use arithmetic expressions like 1 + 2 * 3:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*jFfG-yETVj1SzUqDxp5uEw.png" /></figure><p>Compare this with an all-in object oriented approach. Note that this is just an example to illustrate the differences, not the optimal way of solving the problem:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*oeKvqRwoNwNE0-0PTJPkOQ.png" /></figure><p>As you can see, this requires more code and doesn’t read as well.</p><p>Let’s list the different ways an object A can gain access to an objects B:</p><ul><li>Pass in B as an argument when calling a method of A.</li><li>Pass in B in the constructor of A and save it as a member of A.</li><li>Pass in B to a setter method of A and save it as a member of A.</li><li>Use reflection to set a member B in A.</li></ul><p>Any of these variants will give A access to B:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*25LGy5JPDQ2T7iZsDxY2Ag.png" /></figure><p>These kinds of operations can sometimes be performed by a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but under the hood, some of the operations above will be used.</p><p>The Hexagonal architecture originates from the object oriented world, and the code examples in Alistair’s <a href="https://alistair.cockburn.us/hexagonal-architecture/">article</a> uses dependency injection.</p><p>In the 1 + 2 * 3 example, we didn’t have to specify the relationships between the operators and the operands, which made the functional solution simpler and more readable.</p><p>Polylith originates from the functional world and takes this approach to software design. Bricks are composable, the same way 1 + 2 * 3 is, and we don’t need to specify how each brick depends on other bricks when we assemble them into projects at build time. It’s enough to specify which bricks to include:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/182/1*bfixqJimMCqFIlStpmjsNw.png" /></figure><p>Almost too simple!</p><p>In Polylith we don’t configure how the bricks depend on each other. As long as they compile in the development project, we are fine. All bricks have access to all components, or to be precise, all interfaces, and they are connected by using direct function calls.</p><p>So when a brick needs some functionality that is exposed in any of the interfaces, we don’t have to add an annotation, edit a configuration file or add a member to a class to gain access. All we have to do is to import the brick’s interface namespace in the code that needs it, in the exact same way we do with libraries. It doesn’t need to be more complicated than that!</p><p>Note that in some situations we need polymorphism at runtime, and when that happens, we need to solve that in a traditional way.</p><p>It would be possible to implement a variant of Polylith using dependency injection, but it would also be more complex and more like the object oriented example, and less like 1 + 2 * 3 :</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*xwcQYk2Vi5WOsIo62GR72Q.png" /></figure><p>The bottom line is that putting things side by side is more composable and less complex than putting things inside each other.</p><h4>Reducing complexity</h4><p>As you have probably already figured out, Polylith is very much a tool to fight complexity.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/556/0*OExfzIpPprXuVFCY.png" /></figure><p>I explain how composability, size, and other things affect complexity <a href="https://itnext.io/the-origin-of-complexity-8ecb39130fc">here</a>.</p><h4>Code examples</h4><p>If you want to compare different backend systems, there is a cool project called <a href="https://github.com/gothinkster/realworld">RealWorld</a> where different languages implement the same backend API spec.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*Qp7RvAeZw1ZS9hCe" /></figure><p>There is an implementation using the Hexagonal architecture in Go <a href="https://github.com/labasubagia/realworld-backend">here</a>, and a Polylith example in Clojure <a href="https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app">here</a>.</p><p>You can explore the Polylith example without installing anything.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*QsFq5y9G0QGDpP6O.png" /></figure><p>There are instructions <a href="https://github.com/PEZ/clojure-polylith-realworld-example-app/blob/master/gitpod.md">here</a> for getting a full development environment to a live Polylith Real World example running in your browser, with only a few clicks. It guides you in how to use Clojure so that you can experiment with Polylith!</p><h3>Code sharing</h3><p>The main goals of Polylith are to decrease complexity and make coding a more joyful experience. <a href="https://en.wikipedia.org/wiki/Duplicate_code">Code duplication</a> is generally considered undesirable, which is also why code sharing is built-in to Polylith.</p><p>We could create libraries as a way of sharing code within our system and across services. But that would also increase the complexity and harm the development experience, which we want to avoid.</p><p>Polylith solves the sharing problem at build time. These are the prerequisites for it to work:</p><ol><li>Use a <a href="https://en.wikipedia.org/wiki/Monorepo">monorepo</a>.</li><li>Use shareable Lego-like bricks at the source code level.</li><li>Enable subsets of bricks to be built into artifacts.</li></ol><p>Let’s go through them.</p><h4>Use a monorepo</h4><p>In Polylith, we don’t use libraries to share code between services and tools, because of the <a href="https://polylith.gitbook.io/polylith/introduction/sharing-code">problems that come with it</a>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/490/0*nG3dk7qz6qDgeFxW" /></figure><p>Once we abandon this idea, we need to use a monorepo.</p><h4>Use <strong>shareable</strong> Lego-like bricks at the source code level</h4><p>You can think of Polylith bricks as blocks of code that can be shared across the entire system at build time and are connected with direct function calls in the same way we use libraries.</p><h4>Enable subsets of bricks to be built into artifacts</h4><p>Once the bricks are represented as plain source code, the next step is to be able to assemble subsets of them into projects and build artifacts from them.</p><p>This can be implemented in different ways, depending on which language and tools you use. The best way we have found is to let the code structure mirror the architecture’s building blocks (bricks and projects) and use IDEs and build tools that have support for multiple source directories.</p><p>Other variants include the use of <a href="https://en.wikipedia.org/wiki/Symbolic_link">symbolic links</a> or a single development project with just one source directory. None of these give the same level of decoupling and composability, so we stick with the multiple source directories variant here.</p><h4>Examples</h4><p><a href="https://clojure.org/">Clojure</a>, together with <a href="https://github.com/clojure/tools.deps">tools.deps</a>, has built-in support for multiple source directories.</p><p>Here is an example taken from the <a href="https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app">clojure-polylith-realworld-example-app</a> project, which lists the bricks in a <a href="https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app/blob/master/projects/realworld-backend/deps.edn">deps.edn</a> config file:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ya-5ktAic-IKHGijD7uB0A.png" /></figure><p>In Python we have <a href="https://davidvujic.github.io/python-polylith-docs">Python tools for the Polylith Architecture</a> which uses Poetry together with the Multiproject plugin.</p><p>Here is an example that is taken from its documentation:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/682/1*iSvd1x5l0Lz3bhjNiq07ZQ.png" /></figure><p>Another example is Java together with Maven. Java doesn’t support the use of multiple source directories out of the box, but it can be achieved with the <a href="https://www.mojohaus.org/build-helper-maven-plugin/usage.html">build-helper-maven-plugin</a>. Most Java IDEs support Maven based projects, which means we get the IDE integration for free.</p><p>As we mentioned earlier in the previous section, it would be possible to use dependency injection together with a monorepo to share code across applications, but that would also add more complexity and be less composable, which is why we avoid it.</p><h3>Code structure</h3><p>The standardized code structure in Polylith helps us reason about the code, but it’s also part of the solution to the code sharing puzzle and how to support polymorphism at build time.</p><p>A Polylith codebase lives in a monorepo and is divided into one or more <a href="https://polylith.gitbook.io/polylith/architecture/2.1.-workspace">workspaces</a>. A workspace mirrors the core concepts of the Polylith architecture, like bases, components, and projects.</p><p>In this example, the workspace directory is also the root of the repository. It can have any name, but here we stick with workspace:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/160/1*Z89Cg_nVZTHT5YQSJpPVeg.png" /></figure><p>Each brick and project lives in its own directory, e.g.:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/254/1*JrjfBAYnaXhfN5D4s5WEIg.png" /></figure><p>Each brick stores its own source directories, and each project lists the included bricks in a config file:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/220/1*gT6eQIT2YhVs8cfiHkIiKg.png" /></figure><h4>base</h4><p>The namespaces for a base follow this structure:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/408/1*P67gaGEsvmGSE3t5NepwzQ.png" /></figure><p>First we have the top namespace, which could be any valid namespace, e.g. my.company. Next we have the name of the base, e.g. email-lambda, followed by one or several namespaces which implement the public API and delegate to component interfaces.</p><h4>component</h4><p>A component is structured in a similar way, but has the interface name directly after the top namespace:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/450/1*Jq-_a-oYU_vyyBIWDpMYOA.png" /></figure><p>A component also has an interface namespace, that delegates incoming calls to implementing namespaces, e.g.:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/450/1*ohPR8I28_XmUHEMZW4Ij7g.png" /></figure><p>An option is to split the interface to sub namespaces, e.g.:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/545/1*EDzZP-dKVEkh-rTY7M8Suw.png" /></figure><p>Think of an interface in Polylith as a set of functions (and maybe constants and macros) that exposes a component’s functionality.</p><p>If more than one component implements the authentication interface, they will live in separate directories under components but use the same com.mycompany.authentication namespace.</p><p>All bricks use the same top namespace, or com.mycompany as in this example.</p><h4>project</h4><p>Each project includes a configuration file that specifies the bricks to include in the project. This is often a single base and a set of components. How this looks depends on which library or build tool you use for your language of choice.</p><p>We can take the previously mentioned <em>realworld-backend </em>service as example:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ya-5ktAic-IKHGijD7uB0A.png" /></figure><p>The tooling gathers all the brick namespaces into one single “monolith”:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*TS3jAfTEsEbLcdKFAwsPlw.png" /></figure><p>From here we can run tests and build and deploy an artifact, e.g. a service.</p><h4>development</h4><p>As you already know, the development project is used to give us a monolithic user experience.</p><p>However, an important difference from other projects is that you never build and deploy the development project.</p><p>It’s also a place where you put code that is only used during development, for example code that fixes problems in the production database.</p><p>We can even let each developer have their own namespace, e.g. dev.alanturing or dev.adalovelace, where they can put code that they find useful during development.</p><h3>Tooling support</h3><p>A Polylith tool can give us additional value, for example help us enforce various constraints, like that bricks only access interfaces, or that all components fulfill the interface contracts. A tool can also help us run tests incrementally, or visualize different aspects of the architecture.</p><p>The <a href="https://cljdoc.org/d/polylith/clj-poly/0.2.18-SNAPSHOT/doc/readme">poly tool</a>, written for Clojure and tools.deps is a good example. This is what the output of the info command looks like for the <a href="https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app">clojure-polylith-realworld-example-app</a> example app:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/505/1*5DHK1luQ-P9-j11DLwu5zA.png" /></figure><p>By looking at the names and the colors, we can see that this system has a realworld-backend REST service, exposed by the rest-api base, containing nine components with different responsibilities. This gives us a pretty good idea of what problems this system solves and how it’s executed in production.</p><p>It also shows additional information, like the e6f7f20 commit hash number and the stable-master <a href="https://git-scm.com/book/en/v2/Git-Basics-Tagging">git tag</a>, which was created when all tests passed in the continuous integration pipeline. This is a marker for the latest stable point in time, which is used by the tool to run tests incrementally.</p><p>The s and t flags tell us whether the src and/or test directories for a brick are included in a project.</p><p>Another example is the deps command:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/469/1*c94J2Uj7GKqDZY4JOFvbUw.png" /></figure><p>It shows which interfaces (in yellow) each brick depends on. For example, the rest-api base depends on all interfaces, while the tag component only depends on the database interface.</p><p>Finally, here is the output from the libs command:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SVIl36k59df7MNv8T_pi7Q.png" /></figure><p>This shows which libraries that are in use, which bricks are using them, and which projects they will be included in.</p><p>The tool also supports incremental testing, which I try to describe <a href="https://polylith.gitbook.io/polylith/introduction/testing-incrementally">here</a>. Having tooling support like this gives the productivity an extra boost by speeding up the feedback loop.</p><p>At the time of writing, there is only tooling support for <a href="https://cljdoc.org/d/polylith/clj-poly/0.2.18-SNAPSHOT/doc/readme">Clojure/tools.deps</a> and <a href="https://davidvujic.github.io/python-polylith-docs/">Python/Poetry</a>, but we hope more languages will be added in the future. In the meantime, don’t be afraid of using Polylith, even if your language lacks tooling support, you will still get most of the benefits!</p><p>If you are curious about how real production systems could look, please visit the <a href="https://cljdoc.org/d/polylith/clj-poly/0.2.18-SNAPSHOT/doc/production-systems">production systems</a> page of the poly tool documentation.</p><h3>Summary</h3><p>A good thing with the Hexagonal architecture is that it separates concerns. However, Polylith takes separation of concerns to the next level.</p><p>Polylith is the first component-based architecture with truly small composable bricks that can be shared across the entire system.</p><p>The bricks help you focus on code quality, changeability, observability, testability, and efficiency, both when developing the code and when deciding on how to run the code in production.</p><p>If you haven’t tried Polylith yet, please do, because it’s a real joy to work with!</p><p>Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8e7c8757dab1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The origin of complexity]]></title>
            <link>https://itnext.io/the-origin-of-complexity-8ecb39130fc?source=rss-852c2bee3b00------2</link>
            <guid isPermaLink="false">https://medium.com/p/8ecb39130fc</guid>
            <category><![CDATA[clojure]]></category>
            <category><![CDATA[complexity]]></category>
            <category><![CDATA[software-design]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[functional-programming]]></category>
            <dc:creator><![CDATA[Joakim Tengstrand]]></dc:creator>
            <pubDate>Sat, 14 Sep 2019 16:41:48 GMT</pubDate>
            <atom:updated>2025-12-09T07:44:01.832Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*foxuWif81NU5GTXSljGQlw.png" /></figure><p>This blog post has <a href="https://tengstrand.github.io/blog/2019-09-14-the-origin-of-complexity.html"><strong>moved here</strong></a>.</p><p>Writing software is hard.</p><p>There are so many things to deal with, so many moving parts and things that can go wrong that it is easy to get lost. It’s not only about building the <em>right thing, </em>but<em> </em>also<em> </em>about building the <em>thing right</em>.</p><p>As a reaction to that, the list of tips on how to best develop software has constantly grown over the years. Sometimes the tips have been quite helpful but others have been contradictory.</p><p>We have learned to not repeat ourselves, avoid mutable state, use pure functions, use interfaces, use polymorphism, prefer composition, use declarative style, avoid temporal coupling, work in small teams, make small commits, avoid long lived branches, test our code, and so on.</p><p>But wouldn’t it be great if we could find one single, simple principle, that is easy to understand and that helps us to reason about software?</p><p>Let’s rewrite the list and add <em>why </em>to get a hint:</p><ul><li><em>Don’t repeat yourself</em> — because that adds coordination.</li><li><em>Make it small</em> — because that reduces coordination.</li><li><em>Avoid mutable state — </em>because it adds coordination.</li><li><em>Use pure functions — </em>because they reduce coordination.</li><li><em>Use interfaces</em> — because they reduce coordination.</li><li><em>Use polymorphism</em> — because it reduces coordination.</li><li><em>Prefer composition — </em>because it reduces<em> </em>coordination<em>.</em></li><li><em>Use declarative style — </em>because it reduces<em> </em>coordination<em>.</em></li><li><em>Avoid temporal coupling</em> — because it introduces coordination</li><li><em>Work in small teams — </em>because it reduces coordination.</li><li><em>Make small commits — </em>because it reduces coordination.</li><li><em>Avoid long lived branches — </em>because they increase coordination.</li><li><em>Test your code — </em>to catch coordination that wasn’t done correctly!</li></ul><p>As you can see, it’s all about<em> coordination</em>!</p><p>Now you may think, what’s wrong with coordination?</p><p>The problem with coordination is that it <em>adds complexity </em>to our systems which make them harder to change and work with. Let’s look at an example.</p><p>Here we have inserted a heading in a simple text editor:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/268/1*hKtm_Najim2grxHCfWhjKg.png" /></figure><p>The problem with this is that if we change the heading,</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/262/1*yT5Fkt7oEVjelHHHv0gWdA.png" /></figure><p>we also need to update the row below, by adding more = characters. The consequence is that we have introduced <em>coordination </em>that needs to be <em>addressed by a human being</em>. This may be a small problem here, because the missing equal signs are easy to spot and fix, but that’s not always the case.</p><p>Another way to put it is that we have <em>failed to automate</em> the task, by <em>introducing manual work</em> instead of letting the computer do the job for us.</p><p>The solution is to switch to a more advanced text editor, like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/270/1*AJkhFLxgyFmGQ0KiPauPqw.png" /></figure><p>If we now change the text to:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/262/1*RgfL8-Si4Z2qvDOn6WJu4A.png" /></figure><p>the underline will automatically be updated by the editor, which solves our coordination problem through <em>automation </em>by the computer.</p><p>This correlation<em> </em>could be expressed with something like “when the heading is changed, make sure the corresponding row below has the same number of characters”. This is something that a person could be responsible for, but it could also be delegated to, and <em>automated by</em>, a computer.</p><p>Note that we can’t get rid of all manual work. Automation needs code, written by humans! Of course it’s only a matter of time until even that task has also been taken over by computers, but that’s another story!</p><h3>Changeability</h3><p>When we work with software, we have to deal with the fact that most things around us constantly change.</p><p>That include hardware, protocols, data formats, security standards, operating systems, programming languages, libraries, frameworks, code, tooling, services, methodologies, staff, organisations, and not least ourselves!</p><p>I would argue that <em>changeability</em> is the most important feature of software to fight complexity. If we could find a simple model that is based on simple principles, then we have something useful that will help us create simpler systems.</p><p>This is what we need to do to achieve <em>changeability:</em></p><ul><li>Increase usability</li><li>Reduce coordination</li></ul><h3>Usability</h3><p>Making things <em>usable</em> can be achieved by adapting our systems and tools to people and their limitations and needs. Code is no exception!</p><p>The level of usability of a codebase or part of a codebase has a direct correlation with how easy it is to change.</p><p>Here is what Wikipedia says about <a href="https://en.wikipedia.org/wiki/Usability">usability</a>:</p><blockquote><strong>Usability</strong> is the ease of use and learnability of a human-made object such as a tool or device. In <a href="https://en.wikipedia.org/wiki/Software_engineering">software engineering</a>, <strong>usability </strong>is the degree to which a software can be used by specified consumers to achieve quantified objectives with effectiveness, efficiency, and satisfaction in a quantified context of use.</blockquote><p>The main ways of achieving usability<em> </em>in software are:</p><ol><li>Make things easy to find, reuse and reason about.</li><li>Use tools and techniques that let you work fast and give you a fast feedback loop.</li><li>Organise people so that you facilitate communication, learning and craftsmanship.</li></ol><p>Usability can be increased in many ways. Here are three examples:</p><p><strong>Example 1:</strong> Give things a good name.</p><p><strong>Example 2:</strong> Use a <a href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">REPL</a> to increase the productivity by shortening the feedback loop.</p><p><strong>Example 3: </strong>Agree on a <a href="https://martinfowler.com/bliki/UbiquitousLanguage.html">ubiquitous language</a> when communicating.</p><p>There is a lot to say about usability but it’s a huge research area of its own which we will not delve into here.</p><h3><em>Coordination</em></h3><p>We have already said that coordination increases complexity and given some examples of it but we haven’t looked into what causes it or where it arises.</p><h4>Cause of coordination</h4><p>There are three main areas that introduce the need for coordination:</p><ul><li>Size — when things get bigger</li><li><em>Order</em> — when order<em> </em>matters</li><li>Consistency — when consistency matters</li></ul><h4>Cause of coordination — Size</h4><p>When something gets bigger it doesn’t just have a negative effect on the <em>usability; </em>by making things harder to understand and reason about, it also increases the need for <em>coordination</em>.</p><p>There are essentially two ways to minimise size:</p><ul><li>Split it up — to reduce coordination</li><li>Make it composable — to make it smaller and easier to use</li></ul><p><strong>Split it up</strong></p><p>For example, if we <em>double </em>the number of people in a team by going from three to six people:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/556/1*orUZe-87ze-_yHME7AStPA.png" /></figure><p>The number of ways to communicate increases from three to fifteen, which is a factor of 5! This <em>exponential growth of coordination </em>and <em>complexity </em>is one of the hardest problems to tackle in software<em>. </em>This unfortunate behaviour is the reason why some <a href="https://en.wikipedia.org/wiki/List_of_failed_and_overbudget_custom_software_projects">large projects fail</a>.</p><p>The way to fight complexity is to split things up:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/508/1*lX1-et8jGWbfDAfc01ntyw.png" /></figure><p>Here we have two teams of three people, where one person in each team is responsible for communicating with the other team and its own. This has reduced the number of connections from 15 to 7, which is more than a 50% reduction in coordination!</p><p>The same principles apply to code and data which is why it’s better to have small functions than big ones and why a <a href="https://polylith.gitbook.io/polylith">Polylith</a> system made up of small reusable components is preferable to a big <a href="https://en.wikipedia.org/wiki/Monolithic_application">Monolith</a>.</p><p><strong>Make it composable</strong></p><p>The other main technique to reduce size is by making things <em>composable.</em></p><p>To achieve <em>composability</em> we have to introduce <em>conformity </em>in the way we process things:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/888/1*huC8Gq1RXtqgm3UNMD9AzQ.png" /></figure><p>The <a href="https://en.wikipedia.org/wiki/Functional_programming">functional</a> way is to have <em>data </em>as material and <em>functions </em>as tools. The <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object oriented</a> way is to have <em>data </em>or <em>interfaces </em>as material and <em>objects </em>as tools.</p><p>To make this useful we need to reduce the number of variants of <em>material </em>and make sure the <em>tools </em>can operate on it. As long as that is met, we can allow ourself to have a large set of tools as a way to reduce complexity.</p><p>In Unix, the material<em> </em>consists of <em>lines of strings </em>and the tools are represented by a set of <em>commands</em> which can be combined together like LEGO<strong>©</strong>:</p><pre>tr -cs A-Za-z <strong>‘\n’</strong> | <br>tr A-Z a-z | <br>sort | <br>uniq -c | <br>sort -rn | <br>sed <strong>${1}</strong>q</pre><p>This example was taken from a solution that <a href="https://en.wikipedia.org/wiki/Douglas_McIlroy">Douglas McIlroy</a> wrote when he gave feedback to <a href="https://en.wikipedia.org/wiki/Donald_Knuth">Donald Knuth</a>. You can read more about the background <a href="https://franklinchen.com/blog/2011/12/08/revisiting-knuth-and-mcilroys-word-count-programs/">here</a> and also find a <a href="https://rosettacode.org/wiki/Word_frequency#Clojure">list with solutions</a> to the problem written in different languages.</p><h4>Cause of coordination — Order</h4><p>One source of complexity is when we need to coordinate the <em>order</em> in which things happen.</p><p>Sometimes it’s important that things come in a certain order. Code is no exception.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/550/1*GiUsdvShXDRwNqfWGK69BA.png" /></figure><p>Here <em>statement 2 </em>must wait for <em>statement 1 </em>to finish, which has introduced need for coordination between the two statements. The result is that we can’t swap the order or parallelise the statements.</p><p>Sometimes one thing has to happen before another. In those cases, it’s helpful if that is explicitly expressed, by the code, the planning tool, or whatever tool we use. But if the need for coordination is not clearly expressed, which is often the case with code, then you run an increased risk of introducing errors.</p><p>The solution is to separate <em>what </em>from <em>how. </em>If we can express <em>what </em>needs to be done and delegate <em>how </em>to some other parts, like a function, a queue, a rule engine or a <a href="https://en.wikipedia.org/wiki/Domain-specific_language">DSL</a> engine, then we are in a much better position to care less about the execution order.</p><p>Let’s give some examples where the <em>order</em> is important:</p><p><strong>Example 1:</strong> We plan our work before we start working.</p><p><strong>Example 2</strong>: An <em>init</em> function must be called, before proceeding with other work (temporal coupling).</p><p><strong>Example 3: </strong>A server must be installed with an operating system, a virtual machine, some tools and such, before other software can run on it.</p><p><strong>Example 4:</strong> We learn and practice to achieve craftsmanship before we can perform tasks.</p><p>Some of these tasks, like setting up a server, can be automated which is the way we <em>reduce coordination</em>. Other tasks can’t be fully automated, at least not yet, like planning, learning and practising.</p><h4>Cause of coordination — Consistency</h4><p>The last thing on our list that causes coordination is when things need to be consistent. We live in a changing world, and things can very easily “get out of sync”. Another challenge is to avoid duplication.</p><p>There are essentially two ways to keep things in sync:</p><ul><li>Have only one<em> </em>of things</li><li>Move in small steps</li></ul><p><strong>Have only one</strong></p><p>An efficient way to ensure that things are consistent is to only have <em>one of everything</em>. The instructions and functions that are part of a programming language are good examples.</p><p>Each “building block”, like an <em>if </em>statement, is only defined <em>once, </em>but can be used from more than one place in the code:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/584/1*rSQOBSND01dWVS6r76cy8Q.png" /></figure><p>The language itself is also only defined once, but can be used from several places (on different machines). The way we get rid of coordination is to only need to make changes in <em>one place.</em></p><p>If we have some code or data that is copied and used in more than one place (e.g. two different services) then we have introduced <em>duplication</em> that needs to be <em>coordinated </em>to stay in sync and remain <em>consistent.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/462/1*nnNz3hkF-MZSURu-rJoHbg.png" /></figure><p>If we later need to change one of them, e.g. to fix a bug, then we also need to remember to update the other service. The idea that <em>copy&amp;paste </em>can be used to “decouple” services is often an illusion, because it doesn’t remove the<em> need for coordination</em>.</p><p>Sometimes though, you really want to start from scratch. An example is when the <a href="https://www.mysql.com/">MySql</a> database was forked to become <a href="https://mariadb.org/">MariaDB</a>.</p><p>Another example of removing coordination by centralising a definition into one place, is the use of <em>polymorphism:</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/468/1*2Mh9DFlg-gNHXyOrWeuZow.png" /></figure><p>In object orientation, the choice of method to call when invoking a method on an object is based on the type of its class. Functional languages sometimes support an even <a href="https://clojure.org/reference/multimethods">more flexible</a> way of dispatching calls, but the principle is the same.</p><p>The idea is to centralise the dispatching mechanism into <em>one place </em>so that we don’t end up with duplicated <em>if </em>or <em>case </em>statements scattered around the codebase, that then need coordination.</p><p><strong>Move in small steps</strong></p><p>The most common example of when things get <em>out of sync </em>is when people, tools, code, models, hardware, and so on, don’t move with their surroundings.</p><p>The way to tackle the problem is to <em>move in small steps.</em></p><p>The reason we want to move in small steps, like making small commits in our <a href="https://en.wikipedia.org/wiki/Version_control">VCS</a> system or by having short <a href="https://www.scrum.org/resources/what-is-a-sprint-in-scrum">sprints</a>, is that the amount of coordination we need to do when “merging back” increases exponentially with the size of the “diff”:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/690/1*rsYth8DWtUfqwo-EqPWI7g.png" /></figure><p>The more often we can merge back our code into master, the less coordination needs to be done. The shorter sprints we have, the easier it is to stay in sync with a changing world (the “master” branch).</p><h4>Where coordination arises</h4><p>We mentioned that many things are constantly changing when developing software. Changes introduce the <em>need for coordination</em> which is one of the main reasons why building software is so hard.</p><p>As we can see, coordination is going on at all levels:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*R69tIy3NMCVE_zPmAIhp6w.png" /></figure><ol><li><em>Hardware &amp; network</em> are affected by the <em>reality</em> so that they sometimes break and need to be repaired or replaced.</li><li>Concepts from <em>the world</em> become <em>models </em>in our code<em>.</em></li><li><em>People </em>are affected by <em>the world </em>and the environment they live and work in.</li><li><em>People </em>leave teams/projects and new people appear.</li><li><em>Tools</em> <em>&amp; services </em>are used to manage <em>hardware &amp; network. </em>Sometimes <em>manually </em>by <em>people </em>that use <em>tools</em> and sometimes <em>automated.</em></li><li><em>Tools </em>are used to execute or debug <em>runtime code.</em></li><li><em>Tools &amp; services </em>are made up of <em>runtime code </em>so that they can be executed.</li><li><em>Hardware </em>is needed to execute <em>runtime code.</em></li><li><em>Source code </em>is transformed into <em>runtime code.</em></li><li><em>Tools </em>are used to work with <em>source code.</em></li><li><em>Tools </em>are used by other <em>tools &amp; services.</em></li><li><em>People </em>create <em>tools &amp; services</em>.</li><li><em>People </em>interact with other <em>people.</em></li><li><em>Models</em> affect how the <em>source code</em> is written.</li><li><em>Tools</em> are used to create <em>models</em>.</li><li><em>Tools </em>and<em> services </em>are used by <em>people </em>to perform tasks: 5 ) manage hardware &amp; network, 6) execute or debug code, 10) work with source code, 15) create models, 16) organise people.</li></ol><p>There is a massive amount of coordination going on here. If we make a change in one place, it will often start a ripple effect of changes in other parts.</p><p>The ways in which we manage all these changes are:</p><ol><li>Increase usability</li><li>Automate and minimise coordination</li></ol><p>We have already talked about how to automate coordination and that usability affects changeability. But what we haven’t mentioned yet is that we sometimes have the choice to <em>not change at all </em>or to only make <em>non-breaking changes.</em></p><p>Here are some examples:</p><p><strong>Example 1: </strong>The original <a href="https://en.wikipedia.org/wiki/X86">Intel x86</a> instruction is still supported, decades after it was first released.</p><p><strong>Example 2: </strong>The original bytecode instruction set for the <a href="https://en.wikipedia.org/wiki/Java_virtual_machine">Java Virtual Machine</a> is still supported.</p><p><strong>Example 3: </strong>The original <a href="https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol">HTTP</a> protocol specification is still supported, more than four decades later.</p><p>The solution is to agree on a contract, make it into a standard, and then only make backward compatible changes. Simple as that!</p><p>These standards are globally shared, but we can use the same idea within an organisation or a codebase, by e.g. saying that we always use <a href="https://en.wikipedia.org/wiki/JSON">JSON</a> when communicating between services, or that all code should run on top of the <a href="https://en.wikipedia.org/wiki/.NET_Framework">.Net</a> or the <a href="https://en.wikipedia.org/wiki/Java_virtual_machine">JVM</a> platform to ensure consistency.</p><h3>Out of the Tar Pit</h3><p>Before we continue, we need to mention the masterpiece <a href="http://curtclifton.net/papers/MoseleyMarks06a.pdf">Out of the Tar Pit</a> by Ben Moseley and Peter Marks. The reason is simple. It would be a crime to not include it in a blog post about <em>complexity</em> in software!</p><p>If you haven’t read it already, I recommend that you do. It’s well spent time!</p><p>They talk a lot about the importance of fighting complexity and where it arises.</p><p>They state that:</p><blockquote>Complexity is the single major difficulty in the successful development of large-scale software systems.</blockquote><p>They continue:</p><blockquote>We believe that the major contributor to this complexity in many systems is the handling of state</blockquote><p>With <em>state </em>they mean <em>mutable state, </em>especially<em> uncoordinated mutable state. </em>I agree that this is very much true, especially in languages that encourage use of <em>uncoordinated mutable state.</em></p><p>The reason why <em>mutable state</em> is especially hard to deal with, is that it introduces the <em>need for coordination. </em>Sometimes this need for coordination is lacking, as in the case of <em>global variables, </em>which is why global variables are discouraged in general.</p><p>Luckily, there are ways of controlling mutable state, like the use of <a href="https://en.wikipedia.org/wiki/Transaction_processing">transactions</a>, <a href="https://clojure.org/reference/transients">transient data structures</a>, <a href="https://en.wikipedia.org/wiki/Software_transactional_memory">software transactional memory (stm)</a>, <a href="https://clojure.org/reference/atoms">atoms</a>, and more.</p><p>A common situation where mutable state can sneak in is via use of objects:</p><blockquote>The bottom line is that all forms of OOP rely on state (contained within objects) and in general all behaviour is affected by this state. As a result of this, OOP suffers directly from the problems associated with state described above, and as such we believe that it does not provide an adequate foundation for avoiding complexity.</blockquote><p>This is also why the use of <em>immutable state </em>and<em> pure functions </em>is preferred, because they don’t introduce coordination by themselves.</p><p>The paper also talks about complexity caused by <em>control,</em> which is about the <em>order </em>in which things happen.</p><p>Their observation is that:</p><blockquote>ordering in which things will happen is controlled by the order in which the statements of the programming language are written</blockquote><p>The problem with this is that it adds need for coordination that is not explicitly expressed by the language with the result that the developers need to perform this coordination in their head when they read the code, which increases the risk of introducing errors in the code.</p><p>They describe it very well on page 8 and 9:</p><blockquote>The difficulty is that when control is an implicit part of the language (as it almost always is), then every single piece of program must be understood in that context — even when (as is often the case) the programmer may wish to say nothing about this. When a programmer is forced (through use of a language with implicit control flow) to specify the control, he or she is being forced to specify an aspect of how the system should work rather than simply what is desired. Effectively they are being forced to over-specify the problem.</blockquote><p>The paper discusses many other aspects of software, like identity, different kinds of programming paradigms, the relational model, and more. I think if more people understood this paper, much of the complexity that is produced in this industry could be eliminated!</p><h3>Dependencies</h3><p>So why use the word <em>coordination </em>when we already have <em>dependency?</em></p><p>The main reason is that they <em>mean different things</em>.</p><p>That’s also why we can’t say “dependencies are bad”, because it’s not always the case. It’s especially not true if we depend on something that never changes in a breaking way.</p><p>For example, depending on a Virtual Machine (e.g. the JVM) helps us eliminate the need for coordination between the compiled bytecode and the hardware. Depending on java.lang.String helps us work with strings in a safe way, without worrying about it changing in the future!</p><p>The rule of thumb is:</p><blockquote>Stabilise the things you depend on</blockquote><h3>Coupling</h3><p>So if we can’t use <em>dependencies </em>to describe how well a system is designed, maybe we can use <em>coupling</em>?</p><p>Coupling can be described with the <a href="https://connascence.io/">connascence</a> concept, but here we will use the <a href="https://en.wikipedia.org/wiki/Coupling_(computer_programming)">Wikipedia</a> definition:</p><blockquote>In <a href="https://en.wikipedia.org/wiki/Software_engineering">software engineering</a>, <strong>coupling</strong> is the degree of interdependence between software modules; a measure of how closely connected two routines or modules are; the strength of the relationships between modules.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*U1CNvxBiKvTiAWkh1cNPcw.png" /><figcaption><a href="https://en.wikipedia.org/wiki/File:Coupling_sketches_cropped_1.svg">https://en.wikipedia.org/wiki/File:Coupling_sketches_cropped_1.svg</a></figcaption></figure><p>This illustration measures three aspects of coupling<em>: interdependency, coordination</em> and <em>information flow</em>. If we need three words to describe <em>coupling</em>, where <em>coordination </em>is one of them, then it’s probably not the same concept as <em>coordination!</em></p><p>An indication that the concept is not so concisely defined is the huge list of different types of coupling: <em>content coupling, common coupling, external coupling, control coupling, stamp coupling</em><strong><em>, </em></strong><em>data coupling, subclass coupling </em>and<em> temporal coupling</em>.</p><p>The underlying mechanisms that contribute to complexity are not clearly expressed, which makes the concept of <em>loose</em> or <em>tight coupling </em>hard to use as a tool to guide us when making design decisions.</p><p>The consequence is that people often try to “decouple” things without decreasing the need for coordination, which unfortunately often only adds more complexity. A better approach is instead to focus on <em>reducing coordination</em> and <em>increasing usability</em> as a way to fight complexity.</p><h3>Tradeoffs</h3><p>Sometimes you may have to chose between a <em>usable </em>solution that introduces <em>coordination </em>and a solution that does the opposite.</p><p>Let’s assume you need to choose between introducing duplications in a text file, or using a <a href="https://en.wikipedia.org/wiki/Template_processor">template engine</a>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*f9n8Wo0mVgCB23elw-kwBA.png" /></figure><p>To store the content as <em>plain text</em> keeps it readable and search-able, but with the extra cost of remembering to update the file whenever the duplicated content changes.</p><p>Introducing a <em>template engine </em>will solve the <em>coordination </em>of the otherwise duplicated content, but will also add complexity and maybe reduce readability and search-ability.</p><p>What solution to choose should be based on how often the duplicated data changes, the risk of forgetting to update the file and how big an impact that may have compared to the cost of introducing a template engine.</p><p>Most often though, a reduction in <em>coordination </em>also has a positive effect on the <em>usability:</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z9_lU5DYbXPnfWobCYmqQQ.png" /></figure><p>That includes reducing the <em>size</em>, removing <em>duplication</em>, separating <em>what</em> from <em>how</em>, keeping things <em>consistent</em>, and more.</p><h3>Summary</h3><p>This diagram summarises what we have talked about:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DtG6HitflGKRmKfKhIlFiQ.png" /></figure><p>This diagram will help you develop the <em>thing right </em>but not the <em>right thing. </em>That part you have to figure out yourself!</p><p>The goal is to give you a tool that guides you towards simpler solutions with increased quality in a way that allows you to work fast, have more fun and spend less money!</p><p>So don’t hesitate to use this diagram the next time you need to make a design decision!</p><h3>Choice of programming language</h3><p>Our most important tool in our toolkit is the <em>programming language. </em>People often say that it doesn’t matter what programming language we choose, because we can solve any problem regardless of choice of language, as long as it’s fast enough and <a href="https://en.wikipedia.org/wiki/Turing_completeness">Turing complete</a>.</p><p>This is as wrong as saying that it doesn’t matter how skilled the players in a football team are. It may be a poor comparison, but programming languages also need “skills” to perform well!</p><p>Sometimes the speed of the language or how fast it compiles is the most important skill, but most often it’s just about how well it’s suited to fight complexity.</p><p>When we make our choice of language, we should pick one that ticks as many boxes in the <em>Simplicity </em>column as possible:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oMrjwp6xJMMcZTtKOfLijg.png" /></figure><p>If this diagram looks familiar to you, then it’s because it’s taken from the brilliant talk <a href="https://www.infoq.com/presentations/Simple-Made-Easy">Simple Made Easy</a> by <a href="https://github.com/tallesl/Rich-Hickey-fanclub">Rich Hickey</a>.</p><p>Don’t forget that the choice of programming language is not just a matter of taste, it’s an opportunity to choose the best tool for the job to fight complexity.</p><p>If your favourite language doesn&#39;t tick that many boxes, then it can be an idea to look around and see if you can find <a href="https://clojure.org/">one that does</a>!</p><p>Let the war against complexity begin.</p><p>Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8ecb39130fc" width="1" height="1" alt=""><hr><p><a href="https://itnext.io/the-origin-of-complexity-8ecb39130fc">The origin of complexity</a> was originally published in <a href="https://itnext.io/">ITNEXT</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[You don’t want to go back]]></title>
            <link>https://medium.com/@joakimtengstrand/you-dont-want-to-go-back-4714aab9e321?source=rss-852c2bee3b00------2</link>
            <guid isPermaLink="false">https://medium.com/p/4714aab9e321</guid>
            <category><![CDATA[functional-programming]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[object-oriented]]></category>
            <category><![CDATA[software]]></category>
            <dc:creator><![CDATA[Joakim Tengstrand]]></dc:creator>
            <pubDate>Thu, 15 Aug 2019 17:26:52 GMT</pubDate>
            <atom:updated>2019-08-15T17:26:52.851Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/833/1*en0VuFCjdgj2KoRYcGTXYQ.png" /></figure><p>I just listened to <a href="https://www.functionalgeekery.com/episode-126-andy-hunt-and-dave-thomas/">episode 126</a> of the Functional Geekery podcast. This time the guests were <a href="https://en.wikipedia.org/wiki/Andy_Hunt_(author)">Andy Hunt</a> and <a href="https://en.wikipedia.org/wiki/Dave_Thomas_(programmer)">Dave Thomas</a>. The main reason they were invited was probably because they have released a new version of their classic book <a href="https://pragprog.com/book/tpp20/the-pragmatic-programmer-20th-anniversary-edition">The Pragmatic Programmer</a>.</p><p>I can really recommend this episode, but especially two sections caught my interest.</p><blockquote><strong>Andy Hunt: </strong>“The underlying metric for good design is simply that things that are well designed are easier to change. They are easier to adapt to what the users actually wants. And that’s the only rule of design, really, is: <em>do things that make it easier to change</em>.”.</blockquote><p>I agree with this statement. I think that the problem can partially be solved by finding blocks of reusable code that <em>never change</em> their <em>contract</em>, <em>semantics</em> or <em>performance characteristics</em> (by getting slower). Good examples are the <a href="https://en.wikipedia.org/wiki/X86_instruction_listings">x86 instruction set</a>, the <a href="http://mally.stanford.edu/~sr/computing/basic-unix.html">Unix commands</a> or the <a href="https://clojure.org/api/cheatsheet">standard functions in Clojure</a>.</p><p>Of course, bugs can sometimes be introduced anyway, like the <a href="https://en.wikipedia.org/wiki/Pentium_FDIV_bug">Pentium FDIV bug</a>, but most of the time they are the most stable and reliable building blocks of our systems, the foundation.</p><blockquote><strong>Andy Hunt:</strong> “When you think about OO programming, I was a big fan of OO, but at the same time as I was doing it, I kept bumping into situations where it really got pretty messy, where the fact the state was being managed in these little islolated chunks, sounds good in theory, but when it comes to tracking down the seventeen different people that have some kind of influence on this, it got to be pretty hairy.</blockquote><blockquote>When I started to program in more functional style, then I discovered that making state explicit, and more to the point. Making state transformation explicit, decoupled me in a kind of radical way. No longer was my code and my state all one big ball of mud, but instead the state had an independent existence to the code.</blockquote><blockquote>And in the same way that the Unix pipeline allows you to put together these little sharp utilities in ways that the original creator never imagined, the same thing is true when you start writing in a functional style, and it’s not necessarily just about pipelines, it’s this idea that you have pure functions that simply don’t have their own state, that create copies of data having applied transformations to it. <em>Once you get into that mindset, you reall don’t want to go back, you know?!</em>”.</blockquote><p>I programmed <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">OO</a> (for twenty years) and I tried really hard to get things right. Now I have used a functional language (<a href="https://en.wikipedia.org/wiki/Clojure">Clojure</a>) for three years, and I totally agree:</p><p><em>You don’t want to go back!</em></p><p>Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4714aab9e321" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Polylith architecture]]></title>
            <link>https://medium.com/@joakimtengstrand/the-polylith-architecture-1eec55c5ebce?source=rss-852c2bee3b00------2</link>
            <guid isPermaLink="false">https://medium.com/p/1eec55c5ebce</guid>
            <category><![CDATA[clojure]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[functional-programming]]></category>
            <dc:creator><![CDATA[Joakim Tengstrand]]></dc:creator>
            <pubDate>Tue, 02 Oct 2018 17:44:07 GMT</pubDate>
            <atom:updated>2025-12-09T07:44:56.609Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4bPf7A77YJN2h5sj8TxuhQ.png" /></figure><p><em>This blog post has</em><strong><em> </em></strong><a href="https://tengstrand.github.io/blog/2018-10-02-the-polylith-architecture.html"><strong><em>moved here</em></strong></a><em>,</em><strong><em> </em></strong><em>with updated footnotes.</em></p><p>Today I’m proud to announce a new software architecture, called Polylith!</p><p>I hope that Polylith can have a positive affect on the software industry, by focusing on simplicity and developer happiness and efficiency.</p><p>Let’s start from the beginning. Two years ago I finally had the chance to work full time with the functional language <a href="https://en.wikipedia.org/wiki/Clojure">Clojure</a> and the functional database <a href="https://www.datomic.com/">Datomic</a>. I had read a book, blogged and played around with the language for a while, but now it was time to leave 20 years of Java behind me.</p><p>I joined a small team with one developer, a team leader and a UX designer. Even though only the team leader and I had any previous experience with Clojure and very little experience with Datomic, the whole team was up and running quickly and very soon became a hyper productive Dream Team!</p><p>A fantastic thing about Clojure is its <a href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">REPL</a>. It allows you to work much faster compared to “up front” compiled languages like Java. Instead, it compiles the code incrementally. The result is lightning fast feedback, where you have direct access to all your data and compiled code. Once you have tried it, you will never look back!</p><p>After a month I questioned why we still had a Microservices architecture. It slowed us down because we now had a bunch of <a href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">REPL</a>s instead of just one, and it also added a lot of boilerplate code and unnecessary complexity.</p><p>One morning on the train to work I got that eureka moment that you may get once in a lifetime. I realised that the solution was to turn the development environment into a monolith using <a href="https://en.wikipedia.org/wiki/Symbolic_link">symbolic links</a> to each “component”! This little trick worked out well and now we had our single REPL back again!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*d6-MSAkLpwkrNZiYQ7k6Yg.png" /><figcaption>The three building blocks of Polylith</figcaption></figure><p>Two years have passed and we still love this way of designing systems. The components have become our friends that are easy to understand, reuse and combine into deployable systems. The <a href="https://github.com/tengstrand/lein-polylith">tool</a> helps us test and build our systems incrementally both locally and on the continuous integration server.</p><p>It’s not just efficient and fun, it has changed the way we think about design at the system level.</p><p>If this has made you curious, then head over to our <a href="https://polylith.gitbook.io/">high-level documentation</a> to find out more.</p><p>Happy coding!</p><p>Joakim Tengstrand</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1eec55c5ebce" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Micro Monolith Architecture]]></title>
            <link>https://medium.com/@joakimtengstrand/the-micro-monolith-architecture-d135d9cafbe?source=rss-852c2bee3b00------2</link>
            <guid isPermaLink="false">https://medium.com/p/d135d9cafbe</guid>
            <category><![CDATA[clojure]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[microservices]]></category>
            <dc:creator><![CDATA[Joakim Tengstrand]]></dc:creator>
            <pubDate>Wed, 28 Dec 2016 13:50:48 GMT</pubDate>
            <atom:updated>2025-12-09T07:45:45.689Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Uoc_G_Fv4Ykx6EmzPkcL8g.jpeg" /></figure><p>This blog post has <a href="https://tengstrand.github.io/blog/2016-12-28-the-micro-monolith-architecture.html"><strong>moved here</strong></a>, with updated footnotes.</p><p>Writing quality software, with thousands or millions of lines of code, is probably one of the most challenging and complex tasks you can undertake. Here I will present an alternative, amazingly simple way of modularising software, complete with <a href="https://github.com/tengstrand/micromonolith">code examples</a> in Java and Clojure!</p><p>When a system grows it will eventually reach a point when it becomes hard to manage as a single <a href="https://en.wikipedia.org/wiki/Monolithic_application">monolith</a>. For every line of code that is added, the system becomes harder to understand, change and reuse. <a href="https://en.wikipedia.org/wiki/Microservices">Microservices</a> try to address these problems but also bring extra complexity and an increased cost of integration.</p><p>The core principle in the Micro Monolith architecture is to keep the hardware, software and the data <em>close together</em> in <em>one place</em>. By doing so we can simplify things and get rid of unnecessary coordination. The performance will also be improved if we have direct access to the data from <em>one place. </em>If we design our systems using small, isolated, and composable building blocks (like Microservices) but execute them from <em>one place</em> (like a monolith), we get the best of both worlds.</p><h4>How it works</h4><p>Each service is stored as a project in the version control system, with the ability to build its own <a href="https://en.wikipedia.org/wiki/JAR_%28file_format%29">JAR</a> (if running on the <a href="https://en.wikipedia.org/wiki/Java_virtual_machine">JVM</a> — or similar on other platforms). They become the building blocks in the production environment that we use to compose our systems. In the <em>development </em>project we link all the source code from the services, so that we can work directly with the code as if it was a single project.</p><p>Let’s continue by summarising the pros and cons of the Micro Monolith approach:</p><h4>Pros</h4><ul><li>simplicity<em> (separation of concerns, but with direct code calling, which removes the complexity of networked APIs)</em></li><li>excellent performance <em>(no network calls to access services)</em></li><li>modular and composable services <em>(reuse across multiple systems)</em></li><li>data consistency via cross-service transactions <em>(instead of eventual consistency)</em></li><li>reduced devops and hardware/hosting costs <em>(run the system on a single machine)</em></li><li>easy to test (<em>the whole system can be tested as one piece)</em></li><li>a faster and more effective development experience <em>(navigate, refactor and debug across services + make changes without rebuilding services)</em></li></ul><h4>Cons</h4><ul><li>you “must” use the same programming language in all services (*)</li><li>the development project requires some extra setup <em>(creating the symbolic links)</em></li><li>your operating system has to support symbolic links</li><li>resources that share the same path must have unique names across all services <em>(if they have different content)</em></li><li>you lose the built-in version control support in your <a href="https://en.wikipedia.org/wiki/Integrated_development_environment">IDE</a> <em>(because Micro Monolith is probably not supported by your IDE — yet!)</em></li></ul><p>(*) You are not forced to use only one programming language, but to achieve all the benefits you get from the development setup (like refactoring and debugging across services) then by far the best option is to stick with one language. The second best is to use a mix of languages that can run on the same platform (e.g. the <a href="https://en.wikipedia.org/wiki/Java_virtual_machine">JVM</a>) like Java, Scala, JRuby and Clojure (and C if using the native interface <a href="https://en.wikipedia.org/wiki/Java_Native_Interface">JNI</a>), but then you also need to build a new <a href="https://en.wikipedia.org/wiki/JAR_(file_format)">JAR</a> every time you make a change in a service so that it can be shared to other services. You always have the option to write some of the services as Microservices, but then you lose the benefits that come with the Micro Monolith architecture for these services.</p><p>We have talked about the concepts behind the Micro Monolith approach but not so much about how it works in practice, so let’s do that by showing two code examples in <a href="https://en.wikipedia.org/wiki/Java_(programming_language)">Java</a> and <a href="https://en.wikipedia.org/wiki/Clojure">Clojure</a>. All the code examples can be found <a href="https://github.com/tengstrand/micromonolith">here</a>. Note: in a real system, they would have been stored in separate repositories, isolated from each other, but for convenience they are here stored in a single repository.</p><p>The Java and the Clojure examples implement the same “solution”, a fake REST API that orchestrates a number of services and exposes <em>findAddresses, doUserStuff </em>and <em>doMoreUserStuff</em>.</p><h3>Java — code examples</h3><p>Java is a popular language that we will use to show how the Micro Monolith architecture can look like in an object oriented language.</p><p>The <a href="https://github.com/tengstrand/micromonolith/tree/master/java/development"><em>development</em></a><em> </em>project is the place where you will spend most of your time as a developer. Even though all our services are stored as separate version controlled projects (<a href="https://sv.wikipedia.org/wiki/Git">Git</a> in our case) we use a clever trick to bring all the source code together into a single project (<em>one place) </em>by using <a href="https://en.wikipedia.org/wiki/Symbolic_link">symbolic links</a>. The IDE doesn’t care if the directories are “real” or just links, but will mark them with an arrow in the IDE (at least in the one <a href="https://www.jetbrains.com/idea">we use</a> in this example):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/518/1*0AVMEX8x683Rbhs7Jbl3DQ.png" /></figure><p>After the project has been checked out locally, the links will work out of the box in Linux or Unix, but on other platforms you might need to create the development project manually with a script similar to <a href="https://github.com/tengstrand/micromonolith/blob/master/java/development/setup.sh">this</a>.</p><p>With this project setup we achieve all the benefits we normally get from a modern development environment, even <em>across services.</em> That includes <em>debugging</em>, <em>refactoring </em>and <em>searching.</em> This is very powerful and time saving. We don’t need to rebuild services every time we change the code which makes the workflow very efficient and joyful!</p><h4>Dependencies</h4><p>When designing the system we need to decide if we allow services to have knowledge about concrete implementations of external libraries or not. In this example we allow that. As a result of that decision, it’s a good idea to use the same version of libraries across all services.</p><p>The other option is to integrate internal services with external libraries by adding interfaces between them. So instead of allowing a service to know about a concrete library like <em>log4j-1.2.17.jar, </em>we instead create the interface <em>log4j-api</em> that the <em>orchestrator service</em> injects into the services that need it.</p><h4>The orchestrator service</h4><p>The orchestrator service is the place where we put the services together. A system can have more than one orchestrator service, but in this example we only have the <a href="https://github.com/tengstrand/micromonolith/blob/master/java/rest/src/main/java/micromonolith/rest/RestService.java">RestService</a>. Its dependencies to <em>address, email </em>and <em>user </em>services are specified in <a href="https://github.com/tengstrand/micromonolith/blob/master/java/rest/pom.xml">pom.xml</a>.</p><p>If service <em>A</em> needs to call function <em>f </em>in service <em>B</em>, then function <em>f </em>is injected into <em>A</em> by the orchestrator service. It’s not mandatory to only inject one function at a time, but it will increase the <em>changeability</em> and the <em>testability</em> by making the services less coupled to each other. We will use the term <em>micro injection </em>when referring to the concept of injecting one function at a time.</p><h4>Testing</h4><p>The Micro Monolith architecture encourages testing by making it both simple and easy. Just as with Microservices, it’s easier to test every service in isolation. An advantage compared to Microservices is that it is simpler to test the whole system because it is deployed as a single piece on one machine (our <a href="https://github.com/tengstrand/micromonolith/blob/master/java/rest/src/main/java/micromonolith/rest/RestService.java">REST API</a> in this example).</p><p>This example includes a <em>test data generator</em> that help us set up the database in a known state. You may have a <em>user</em> table with a relationship to the <em>address</em> table. You then may have a <em>UserService</em> and an <em>AddressService</em>. The <a href="https://github.com/tengstrand/micromonolith/tree/master/java/test-data-generator">test-data-generator</a> lets you easily set up a known state of the database, which facilitates the writing of integration tests. This can be done both within a service and across services, for example <a href="https://github.com/tengstrand/micromonolith/blob/master/java/address/src/test/java/micromonolith/address/AddressServiceTest.java">AddressServiceTest</a> and <a href="https://github.com/tengstrand/micromonolith/blob/master/java/user/src/test/java/micromonolith/user/UserServiceTest.java">UserServiceTest</a>.</p><h3>Clojure — code examples</h3><p><a href="https://en.wikipedia.org/wiki/Clojure">Clojure</a> is a powerful functional language that runs on top of the <a href="https://en.wikipedia.org/wiki/Java_virtual_machine">JVM</a>. We will use Clojure to show how the Micro Monolith architecture can look like in a functional language. All Clojure code can be found <a href="https://github.com/tengstrand/micromonolith/tree/master/clojure">here</a>.</p><p>The <em>development</em> project looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/525/1*uELFfYW76XTt8bkfbaBazQ.png" /></figure><p>The Clojure version has basically the same structure as the Java version but the functions are stored in namespaces instead of classes. We also don’t need the extra API layer for the address and the email service that we have in Java. As a bonus the Clojure version is less verbose and can do the same job in about 200 lines of code compared to 400 in Java.</p><p>The micro injection is simpler in Clojure and we use the <a href="https://github.com/tengstrand/micromonolith/blob/master/clojure/injection/src/injection/core.clj">inject</a> macro to inject functions. In the example, the function <a href="https://github.com/tengstrand/micromonolith/blob/master/clojure/email/src/email/service.clj"><em>email/send-pdf-email!</em></a><em> </em>replaces <a href="https://github.com/tengstrand/micromonolith/blob/master/clojure/user/src/user/service.clj"><em>user.service/send-pdf-email!</em></a> at line 8 in namespace <a href="https://github.com/tengstrand/micromonolith/blob/master/clojure/rest/src/rest/service.clj">rest.service</a>.</p><h3>Practical experience</h3><p>I and the team I work with have used the Micro Monolith architecture in a real production system for a while. We started with a Microservices architecture, where every service had its own repository in Git. The transition to Micro Monolith was very smooth and all we had to do was to <strong>throw away about 30% of the code</strong> in all our services and replace all REST service calls with simple function calls. It was not only the REST parts that disappeared, but also a lot of complexity related to state and error handling.</p><p>In the beginning, the development environment had the same setup as the production environment, where every service was represented as a Java archive (JAR-file). Every time we changed a service, we also had to rebuild the JAR, so that it could be used by other services. Another downside was that we had to restart the <a href="https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop">REPL</a> (yes, we use Clojure!). That was time consuming and took away some of the joy of working in a REPL.</p><p>I then came up with the new setup for the development project. After that change we could start the REPL once and then continue working without being interrupted, resulting in happier developers! Another thing we realised was that we had some dead code in our services, marked in grey, that we now could get rid of.</p><p>Another design choice was to use the <a href="http://www.datomic.com/">Datomic</a> database. It fits really well with the Micro Monolith architecture and is both simple and powerful. You can read more about its architecture <a href="http://docs.datomic.com/architecture.html">here</a>.</p><p>We use a test-data-generator from almost every service to simplify setting up integration tests. Some of the naming of variables and functions in that service could be improved. Before the change, we had to manually search and replace occurrences in all our services which was both time-consuming and error-prone. The result was that we avoided to make these small changes. With the new development project we can take advantage of the refactoring support in the IDE to rename variables and functions in a wink!</p><h3>Summary</h3><p>The Micro Monolith presents a simpler model of how to build systems. It competes with the Microservice architecture but it doesn’t completely replace it, since the latter definitely has its place. Feel free to use them both if you have the need.</p><p>If you care about simplicity and composability when building systems, then you should definitely give the Micro Monolith architecture a try. Enjoy the efficiency of the development setup and the simplicity of the test and production environment.</p><p>Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d135d9cafbe" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>