Twenty-three files for a pause
Letting a member pause their membership for a month took a pull request that changed 23 files and six tables, and it needed approval from three teams. The company behind it runs eleven coworking spaces on one application: members buy a plan, book desks and meeting rooms, and get one invoice a month. The request itself was one line. A member away for August keeps their account, cannot book, and pays nothing for that month.
The work spread because members.status was a column everybody read. The booking code checked that it said active before reserving a desk. The monthly invoicing job joined the members, plans and bookings tables in one query and billed every member whose status was not cancelled. The front-desk check-in screen read the invoices table directly to flag overdue balances. A new value, paused, meant something different to each of those readers, and each one had to be found and changed by the team that owned that file. The invoicing query was one of the places nobody found, and the first members to pause received an August invoice anyway.
Having one application was not the problem. The problem was that any part could read any other part's tables and call any other part's internals, so the cost of a change grew with the number of places that happened to depend on what you touched. Codebases that reach that state, where everything depends on everything, are informally called a Big Ball of Mud.
Bookings, Members, Invoicing
A Modular Monolith keeps the single application, with one build, one deploy and ordinary function calls inside one process, and divides its inside into modules along business lines: here Bookings, Members and Invoicing. Each module has a public interface, a small set of functions other modules may call, and everything else inside it, its classes, helpers and tables, is private to it.
Members publishes canBook(memberId, date) and billingPlan(memberId, month). Bookings no longer knows there is a status column: it asks whether this member may book on this date and gets yes or no, with a reason. Invoicing asks which plan to bill for August and gets the plan, or an answer that there is nothing to bill, as for a cancelled member. Both callers already handle a no, so add the pause now and the change lives in Members: a new state, and the two answers that depend on it. Bookings and Invoicing call the same functions as before and get different answers.
Modules do not remove coordination. If Invoicing later wants to charge paused members a small fee for keeping their locker, what it needs from Members changes, so the interface changes and both teams talk. What changes is where that conversation happens: at one interface everybody can see, instead of in every query that read a column.
Bookings and Invoicing reach Members only through its interface. Each module keeps its own tables in the one database.
The cut follows what the business does, not the technical layers. Packages called controllers, services and repositories are layers, and the pause would still have crossed all three; a module can have layers inside it, which Layered architecture covers. When the same word means different things to different teams, such as a booking for the front desk and a booking for invoicing, deciding where one module's model ends is the question Bounded Context answers.
In this app the modules are the application itself, all built and shipped together. When the parts are optional extensions that a core discovers through fixed extension points, the pattern is Microkernel / Plugin.
One database, three owners
The modules still share one database, and that is where many modular monoliths slide back into a single tangle. If Invoicing can still run its three-table join, the status column is still everyone's. So each module owns its tables, and only its own code reads or writes them. To bill meeting rooms, Invoicing calls billableHours(memberId, month) on the Bookings interface instead of querying the bookings table, and the revenue report that used to be one join becomes a few calls, or a copy of the data Invoicing keeps from what the other modules hand it. Because it is still one database, a single transaction can span two modules' tables. Sometimes that is the right call, as long as the team knows each such transaction would need redesigning if a module moved out. Separately deployed services that share tables have the same problem at a larger cost, described in Shared Database.
A boundary the build checks
In one codebase nothing physical stops a developer from importing Invoicing's internal tax-rate helper into Bookings late on a Friday. It compiles, it works, and that part of the boundary is gone. Boundaries kept by convention erode one shortcut at a time, so they need checks that fail loudly:
- In the code: an architecture test, such as ArchUnit for Java or dependency-cruiser for JavaScript, that fails the build when Bookings imports anything of Invoicing's beyond its interface. When each module is its own unit, language visibility helps too: a Java module exports only the packages it names, and a C# type marked
internalis not visible outside its assembly. - In the database: a schema per module and, when each module connects with its own database role, grants that stop Bookings from reading the invoices table at all.
If Invoicing ever moves out
Suppose the invoicing run on the first of each month, forty minutes long, starts slowing desk bookings, and the company wants Invoicing as its own service. Because the other modules only called its interface and nobody touched its tables, the interface can become a network API with the same operations, the tables move to a database of their own, and the billing rules move without being rewritten. What changes is the calls, Invoicing's own calls to Members and Bookings included: one that ran in the same process can now time out, or find Invoicing down while everything else is up, and any transaction that spanned Invoicing's tables and another module's has to be replaced. Whether that trade is worth making is what Microservices vs monolith weighs; moving the traffic over step by step is Strangler Fig.
The coworking app in the Challenge
The Modular Monolith Challenge asks for one deployment unit with two or more business modules, each behind an explicit interface, data separated per module inside the shared database, and a module that could be extracted later without rewriting its business logic. Draw the coworking app with Bookings and Invoicing, since eight nodes leave little room for Members, and give each module its own schema in the database. Make the extraction requirement visible too: label Invoicing's interface as the seam that would become its API if it moved out.