<?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 Stephan Hagemann on Medium]]></title>
        <description><![CDATA[Stories by Stephan Hagemann on Medium]]></description>
        <link>https://medium.com/@stephanhagemann?source=rss-b81acef80670------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*eh_2vVZcDmJxPGd7hUGAgQ.jpeg</url>
            <title>Stories by Stephan Hagemann on Medium</title>
            <link>https://medium.com/@stephanhagemann?source=rss-b81acef80670------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 10:06:29 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@stephanhagemann/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[The current state of Gusto’s modularity tooling]]></title>
            <link>https://engineering.gusto.com/the-current-state-of-gustos-modularity-tooling-c99f345fd0a7?source=rss-b81acef80670------2</link>
            <guid isPermaLink="false">https://medium.com/p/c99f345fd0a7</guid>
            <category><![CDATA[modularization]]></category>
            <category><![CDATA[ruby]]></category>
            <category><![CDATA[architecture]]></category>
            <category><![CDATA[packwerk]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <dc:creator><![CDATA[Stephan Hagemann]]></dc:creator>
            <pubDate>Mon, 24 Jun 2024 16:51:16 GMT</pubDate>
            <atom:updated>2024-06-24T16:53:31.368Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="A person lying down with boxes all over them" src="https://cdn-images-1.medium.com/max/1024/1*agb1MLH3_3ZK3OIjJ1JGrA.png" /></figure><p>In my <a href="https://medium.com/gusto-engineering/gustos-gradual-modularization-destination-48d7aabbdede">last post</a>, I looked at how we are steering Gusto’s packaging and modularization work using a broadly applicable way to think about package structures. In this post, I aim to connect this to our tooling setup today. The previous article may not be the most riveting one — nonetheless, you should go back and read it — the most salient points for today are:</p><ul><li>Applications and libraries can depend on and include libraries but not applications. Applications interact with other applications via their APIs.</li><li>The possible APIs for applications and libraries are very different, with the ones for applications being more restrictive.</li></ul><h3>How we got to today</h3><p>We can roughly split Gusto’s journey of using <a href="https://github.com/Shopify/packwerk">packwerk</a> for modularization into three phases.</p><ul><li><strong>Adoption</strong>: A few weeks after Shopify released packwerk in the fall of 2020, we made our first packages at Gusto. After about six months, we had moved most of our biggest codebase into packages — slightly less than 200.</li><li><strong>Expansion</strong>: While most of the original packages weren’t very clean and had many violations, teams across the engineering org created more packages. Even if imperfect, packages showed value as a means of visually separating domains, showing the desired structure, and gradually moving towards it. We got to over 400 packages.</li><li><strong>Refinement</strong>: Having seen the trend of the ever-growing number of packages recreating the problem of the codebase being hard to approach, we knew we had to find a way to change the evolution. So, the phase we are in today aims to resolve the conflict between the sentiment “there are too many packages for me to understand what is going on” and teams creating new packages all the time. The insight discussed in the <a href="https://medium.com/gusto-engineering/gustos-gradual-modularization-destination-48d7aabbdede">previous post</a> led us to ask: “What are the <em>applications</em> here?”</li></ul><h3>Packages as applications?</h3><p>When we asked which applications we thought were present in this codebase, we came up with about 20. 20! Way better than 400. If we could represent these, we’d go from 400 to 20. That would be a massive improvement in the system structure’s approachability. At this number, you can also map applications to products and features that our customers buy, use, and can distinguish.</p><p>The next question was: How do we go from 400 packages to 20? We could not do that. The teams appreciated that they could structure the internals of their domain using packs and did not want to regress from that. Instead, we created a few pieces of tooling that comprise our solution today: layers, product services, and nested packs.</p><h3>Layers and product services</h3><p>First, we tried associating all our packages with one of the target applications. It turned out that was not possible. Many packs didn’t belong to only one application. There were a couple of groups that stood out:</p><ul><li>The application harness (the Rails app root)</li><li>Dev tooling that is needed for data and environment setup in non-production environments</li><li>Rails base classes</li><li>Utilities that provide functionality to many or all product services</li></ul><p>There is directionality to how these groups interact. If we put applications (I will call them product services from now on since that is what we ended up calling them) smack dab in the middle of these four groups, we can think of these groups as layers. The rationale for these layers is that every time you go from a higher to a lower layer, the lower layer should not need to know anything about what’s above: The Rails app configures the runtime of the application but shouldn’t depend on anything, dev tooling needs to have access to models in the domain (product services), but the reverse is not the case, product services rely on rails base classes and utilities, but those should be devoid of knowledge about the product services’ domains.</p><p>A visual to the rescue! The diagram below shows all the layers. The highest layer, the application harness is shown as the outside box. All other layers are boxes inside. The green arrows indicate the order of the layer hierarchy. The relative size of the layer boxes is a nod to the expectable different relative sizes.</p><figure><img alt="Diagram of the layers in our codebase" src="https://cdn-images-1.medium.com/max/960/1*INiR8g_njFfFAy9CxxWgQg.jpeg" /></figure><p>We refined our package structure by creating folders for each layer and moving packs into them. In addition, we used the <a href="https://github.com/rubyatscale/packwerk-extensions?tab=readme-ov-file#layer-checker">packwerk-extensions layer protection</a> to enforce the order of these layers through packwerk. Moving some packages into the non-product services layers means only packages belonging to product services are in the middle layer. The code in this layer amounts to roughly 80% of the codebase and a similar percentage of all packages. So, for this layer, we nested packs into product services.</p><p>The structure today looks something like this:</p><pre>/packs<br>  /tooling<br>  /product_services<br>  /rails_shims<br>  /utilities<br><br>  # Some layers omitted for clarity. The application harness is not visible<br>  # here because it is only the root package.</pre><h3>Nesting packs</h3><p>To allow teams to continue modularizing the internals of their domain, we nested packs into product services. That created the 20ish applications/product services as folders within the product services folder while making space for all the packages belonging to this product service. An immediate benefit of this change was the improved ability to see individual domains in focus.</p><p>At this point, the new structure exposed a new challenge: What is an API? Once again, I refer to my <a href="https://medium.com/gusto-engineering/gustos-gradual-modularization-destination-48d7aabbdede">previous post</a>: The differences between possible APIs when comparing applications and libraries are substantial. And if product services are our <em>applications</em>, what are all the packs within these product services?</p><p>Here is where I empathize with the problems Shopify engineering had with privacy enforcement, as discussed by Gannon McGibbon in <a href="https://shopify.engineering/a-packwerk-retrospective">A Packwerk Retrospective</a>. His analysis culminates in the observation: “The utopia we had imagined simply did not exist, and the tool we thought would get us there was leading us astray.”</p><p>We know we want product services to be applications, so we know what restrictions we can place on their APIs. But what about the packs within them? In general, packs with product services act like libraries, so we know we can’t place any (generic) restrictions on their APIs. This observation may seem like detail at first glance, but it is the crux of it all: We knew that we should place restrictions on the possible APIs for <em>some packs</em>, but we had no way of effectively <em>deciding for any given pack</em> whether it should have restrictions and if so, which ones.</p><p>As such, the best we could do was share general ideas. One such idea that I am guilty of having mentioned many times and that causes quite a bit of damage is “You should probably avoid ActiveRecord at the boundary.” Its danger is that it is good for certain packs and extremely bad for many others.</p><h3>The danger of “no ActiveRecord at the boundary.”</h3><p>For an application, “no ActiveRecord (AR) at the boundary” is a perfectly sensible thing to demand. In fact, it is so deeply ingrained in how we build things that the suggestion of doing something else might seem absurd: Rails controllers return HTML or JSON — because they return data across the application boundary and over the network to a client. If you wanted to send ActiveRecord objects, you would have to marshal them, but even then, you would be unable to use the server’s application context. However, we are not bound by such constraints within one application. We <em>can</em> do things differently.</p><p>If we forget that we have more options for in-app API design, the results for system structure and performance can be disastrous. Take the resolvers backing a GraphQL schema within one domain as an example. When the different packs in a product service construct a graph tree structure, how would it be built if we observed the idea of “no AR at the boundary?” We would have something like a repository pattern that would internally call into AR models of a pack to convert them into data-only structures and return those. While we may want this in other cases, here, it can be said to add two layers of indirection. The resolver would parallelize or chain these calls depending on the exact request. Any repository we build will either be less potent than what we get from AR functionality, or it will reimplement all its complexity. In the latter case… let’s face it is not going to happen. In the former case, you can expect to see all sorts of loading inefficiencies: n+1s, eager loading, lazy loading, over loading, etc. If, instead, the resolver could communicate directly to the pack’s internals and use all the querying powers of AR, we would need to make no such tradeoffs.</p><p>To implement these insights, at Gusto, we decided to explicitly separate the API of a product service from the APIs of packs <em>within</em> a product service. Today, we are working towards a special product service pack, <em>“_api”</em>, which holds the external API for a product service. For all other packs, we work to enforce folder privacy (see below), which causes any usage from outside to cause what we call a product service boundary violation. We allow packages inside of a product service to use any protections they wish, but we restrict privacy and dependency enforcement’s scope to the other packs within the same product service to reduce violation feedback noise: Within product services, it is privacy and dependency as desired by the owning teams, between product services all teams are held to product service privacy.</p><p>The specific tool changes are</p><ul><li><a href="https://github.com/rubyatscale/packwerk-extensions?tab=readme-ov-file#folder-visibility-checker">Folder visibility packwerk-extension</a>: This allows us to control access to product service internals for most packs while excluding specially denoted API packs that contain the API to be used when accessing a product service from the outside.</li><li><a href="https://github.com/alexevanczuk/packs?tab=readme-ov-file#enforcement-globs-ignore">Ignore patterns for privacy and dependency</a>: These patterns allow teams to continue to use these enforcements, focusing on improving the internal structure of the product services they are responsible for.</li></ul><p>The aspirational structure of a product service looks like this:</p><pre>packs/<br>  product_services/<br>    payroll/<br>      _api #product service external API<br>      calculate_payroll/ #internal<br>      filings/ #internal<br>      # ...</pre><h3>Summary</h3><p>At Gusto, we have iterated on our modularity tooling setup multiple times to make more and better refactoring tools available to our engineering organization. The latest iteration creates a new balance between the complexity of the internal structure and its relevance for our business domains. We believe that it will drive better modularization over time and allow us to add an important piece to drive the next step in our software serving our customers: the creation and elevation of well-designed and meaningful internal APIs that can become the precursor to the next product feature and integration opportunity into the Gusto ecosystem of product.</p><h3>PS: Packwerk vs pks (packs)</h3><p>One last update on tooling. We have effectively stopped using <a href="https://github.com/Shopify/packwerk">packwerk</a> in favor of <a href="https://github.com/alexevanczuk/packs">pks</a>, the rust implementation originally authored by Alex Evanzcuk (formerly on our team!). It is compatible with the core features of packwerk. However, some of the features discussed in this post have yet to be backported to packwerk (e.g., generic ignore globs). Pks is superior to packwerk because it is much faster and can be used to parse all Ruby files for their constants instead of extrapolating them from Zeitwerk-loaded names, which is what packwerk does. This means you can use it to get feedback on even more constants in a Ruby application, not just those Zeitwerk knows about.</p><p>PPS: Join discussions on modularity in Ruby and Rails applications on the <a href="https://gradualmodularization.com/">Ruby/Rails Modularity Slack server</a> — you’ll meet quite a few Gusties there! Check out my other writing on modularity at my personal website, <a href="https://stephanhagemann.com/">https://stephanhagemann.com</a>, where you can also find my book, <a href="https://stephanhagemann.com/books/gradual-modularization/">Gradual Modularization for Ruby and Rails</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c99f345fd0a7" width="1" height="1" alt=""><hr><p><a href="https://engineering.gusto.com/the-current-state-of-gustos-modularity-tooling-c99f345fd0a7">The current state of Gusto’s modularity tooling</a> was originally published in <a href="https://engineering.gusto.com/">Gusto Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Gusto’s Gradual Modularization Destination]]></title>
            <link>https://engineering.gusto.com/gustos-gradual-modularization-destination-48d7aabbdede?source=rss-b81acef80670------2</link>
            <guid isPermaLink="false">https://medium.com/p/48d7aabbdede</guid>
            <category><![CDATA[modularization]]></category>
            <category><![CDATA[modular-monolith]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[rails]]></category>
            <dc:creator><![CDATA[Stephan Hagemann]]></dc:creator>
            <pubDate>Mon, 08 Apr 2024 17:19:12 GMT</pubDate>
            <atom:updated>2024-06-25T18:51:43.661Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*h4GWTfebnXIBphLi.jpeg" /></figure><p>When talking to developers about gradual modularization, one of the questions is, “So… where are we headed?” That is, what is the destination of a modularization journey? These developers all work in a large, monolithic codebase-the large application that backs much of Gusto’s functionality. Based on discussions with our peers at different organizations, we know there are a whole bunch of companies in similar situations. These companies all have one thing in common, we’re using Ruby and Rails as a significant part of their backend systems.</p><p>We believe there is a juncture that all of these companies should strive to move their packages towards. This realization is based on working on component-based application design for over a decade and building the gradual modularization and package-based ecosystem for the last couple of years (if you are looking for an intro to these, check out <a href="https://medium.com/gusto-engineering/laying-the-cultural-and-technical-foundation-for-big-rails-6b5ab78349ed">Laying the Cultural and Technical Foundation for Big Rails</a> and <a href="https://medium.com/gusto-engineering/a-how-to-guide-to-ruby-packs-gustos-gem-ecosystem-for-modularizing-ruby-applications-e236126b8c2c">A How-to Guide to Ruby Packs, Gusto’s Gem Ecosystem for Modularizing Ruby Applications</a>). This juncture is this:</p><p><strong>Gradually modularize packages towards extractable applications and libraries.</strong></p><p>Let’s take the two parts of the destination in turn: 1/ What do we mean by applications and libraries, and why are they the target? and 2/ What is extractability, and why is it a target?</p><h3>What we mean by applications and libraries</h3><p>We want to use the term application here as software that is run to do whatever it was designed to do. This can, for example, be a desktop application, a web server, or a lambda function. Anything that, in an operating environment, can be started and then do its thing. In this broad sense, all software we see the effects of or interact with is applications. What we casually call a “Rails app” is an application in this sense.</p><p>Libraries are pieces of software that have a packaging and distribution mechanism and that are included in applications, extending their runtime capabilities with the functionality offered by the library. In Ruby, gems are often libraries in this sense.</p><p>There are technical constraints in how we can combine applications and libraries:</p><ul><li>Applications can interact with other applications by calling their exposed functionality.</li><li>Applications can use libraries by including them.</li><li>Libraries can compose functionality by including other libraries.</li></ul><p>There is nuance here that we will largely gloss over for the sake of length: there are libraries that have application characteristics, e.g., gems including rake tasks that execute like applications, gems that are applications like <a href="https://github.com/rubyatscale/visualize_packs?ref=engineering.gusto.com">visualize_packs</a>.</p><p>All software is either an application or a library in the sense described above.</p><h3>Applications and libraries</h3><p>If we go back to the context in which developers ask themselves whether they should use something like the tooling offered by <a href="https://github.com/rubyatscale?ref=engineering.gusto.com">RubyAtScale</a>, we go back to the fact that folks work in monoliths. It is a bummer that “monolith” is the term the industry landed on because it emphasizes that there is one (structure) but fails to emphasize that folks tend not to believe that it is of uniform structure — that it represents one thing. Quite the opposite: we tend to use it for software that has multitudes in it-multitudes of responsibilities, domains, teams, and, by extension, could have a multitude of applications and libraries in it.</p><p>For monoliths that use the <a href="https://github.com/rubyatscale?ref=engineering.gusto.com">RubyAtScale</a> ecosystem, we divide up the application code of a Rails app into packages. If we ask every package whether it wants to be an application or a library, here are the possible answers:</p><ol><li>A given package wants to be an application</li><li>A given package wants to be a library</li><li>A given package wants to be… “well, we’re not sure yet.”</li><li>A given package wants to be both</li></ol><p>If the answer is #1 or #2 for the given package, we can turn to the question of what extractable means and how to pursue it. The other two options require more interrogation. If the answer is #3, we need to learn more before proceeding. One way to do this by giving ourselves more time: Work on other packages where the answer is not #3 and let that both increase our experience and clarify more parts of the rest of the application. If the answer is #4, you have just found a package that is a monolith, and you should consider splitting it apart.</p><h3>What, in principle, makes a package extractable?</h3><p>We use the term extractable for packages that would work on their own when extracted from the monolith. A specific practical implementation of this notion of extraction could be the following:</p><ul><li>The tests of the codebase pass even after deleting all other packages from the application.</li></ul><p>If a package has dependencies on other packages, this might change to:</p><ul><li>The tests of the codebase pass even after deleting all packages from the application that are not direct or transitive dependencies (via accepted dependencies or violations) of the package.</li></ul><p>Note that this second, more general statement doesn’t prove anything for a single package but rather the remaining group of packages.</p><h3>What makes a library extractable?</h3><p>For libraries, let’s assume that they enforce a package dependency structure. To test the extractability of a package that wants to be a library, take one that has no more dependencies (or violations) on other packages and do the following:</p><ul><li>Move package code (production code and test code) into a new repository,</li><li>Run the tests and fix the visible error. Repeat.</li><li>Profit!</li></ul><p>With these “lists of three,” expect the core problem to be in the middle. In a discussion about <a href="https://shopify.engineering/a-packwerk-retrospective?ref=engineering.gusto.com">Shopify’s recent article “A Packwerk Retrospective</a>,” one of the authors said that when they did this kind of process, even though they had removed all <a href="https://github.com/Shopify/packwerk?ref=engineering.gusto.com">packwerk</a> violations for a package, only 40% of the tests passed when they initially extracted in. That is expected because while packwerk is a tool that aids in the process of getting toward extractability, it doesn’t support every part of that process.</p><p>Here is a list of some of the things that will likely cause errors when doing the above:</p><ul><li>Shared test configuration that needs to be carried over (or tests need to be adapted)</li><li>Shared test helpers — Shared application configuration that changed default behavior (like initializers)</li><li>Product-code metaprogramming that packwerk cannot detect.</li></ul><h3>What makes an application extractable?</h3><p>For applications to analyze extractability, many more preconditions must be met before we reach extractability.</p><ul><li>They enforce Public APIs</li><li>The Public APIs take and return primitive types (and compositions) only, not function-laden objects.</li><li>There are no privacy violations.</li><li>The DB is separate.</li></ul><p>These are just the ones applying to the application and the other applications it collaborates with. There is one more precondition for the whole system, and it is a doozy:</p><p>If you actually want to run an extracted application separately, you must turn the needed APIs from internal, packwerk-public APIs to externally available ones.</p><p>Once done, the steps to test extractability are the same as for libraries:</p><ul><li>Move package code (production code and test code) into a new repository,</li><li>Run the tests and fix the visible error. Repeat.</li><li>Profit!</li></ul><p>In addition to the list we had for libraries, there will be the following things to fix:</p><ul><li>Replace calls to now unknown constants with the equivalent public API on the original application.</li><li>Get the data of the extracted application into the right state.</li></ul><p>Note, in large applications, you may think of groups of packages as wanting to become an application together. In these cases, the description of this section still works, but some of the ways of doing it change.</p><h3>How to extract</h3><p>In both cases, when we get to the “profit” step, the work involved in that step goes something like this:</p><ul><li>Create the repo,</li><li>Make it a gem or an application,</li><li>Share it with the org (via an internal gem server or by deploying the app),</li><li>Add the dependency/interaction to the original host application,</li><li>Remove the package’s code from the original application and rely on the implementation.</li></ul><p>An extraction creates the value of complete separation at the cost of having to maintain that separation and the resulting artifacts.</p><h3>Where to start? Where to stop?</h3><p>The starting point for all of this work, going back to the beginning of this post, is the lack of extractable parts of the codebase and not a lack of extracted parts. The decision on how far to go with extractability and whether to extract is a tradeoff decision of impact and work involved.</p><p>We can depict this choice with a continuum between the three points.</p><p>We said above that the juncture is this:</p><p><strong>Gradually modularize packages towards extractable applications and libraries.</strong></p><p>In this lies the last nuance to the goal of gradual modularization: You decide how far to push along the continuum for each package. This will give you many options for what to pick and optimize for different aspects while on the journey:</p><ul><li>Pick a small, relatively unentangled package to learn or teach the process.</li><li>Pick a package responsible for a core part of the business if it lacks stability.</li><li>Pick a package that feels auxiliary to the application’s core to protect the core from getting bloated.</li></ul><p>So… when you look over your packages… Do you know what they want to be?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=48d7aabbdede" width="1" height="1" alt=""><hr><p><a href="https://engineering.gusto.com/gustos-gradual-modularization-destination-48d7aabbdede">Gusto’s Gradual Modularization Destination</a> was originally published in <a href="https://engineering.gusto.com/">Gusto Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>