A modular monolith decision record for a small SaaS team.
Choose a modular monolith when clear business boundaries matter more than independent deployment. Record its shared failure and release costs, enforce module APIs and data ownership, and reconsider extraction only when a measured constraint survives simpler remedies.
Inside this article 6 sections +
A modular monolith is a useful starting point when a SaaS team needs clear ownership but can still release and operate the product as one application. The decision becomes credible when it names the boundaries that will be enforced, the costs accepted, and the evidence that would justify separating a module later.
Consider an illustrative scheduling product with workspaces, appointments, billing, and notifications. Four engineers maintain it, and most changes cross the user interface and application. Giving every area a separate service would introduce network contracts and deployment coordination before the team has established stable business boundaries.
Record the constraint behind the choice
Write the decision around the present operating problem: the team needs to change appointment rules without accidentally changing billing, while keeping releases understandable. One deployable application and one PostgreSQL cluster are deliberate choices. They reduce the number of systems to operate, but they also mean a bad deployment or resource leak can affect the whole product.
The record should state what was considered. A conventional layered application is easy to begin but allows business concerns to spread across shared services. Independent services provide deployment boundaries but require distributed failure handling. The modular monolith trades independent deployment for simpler operation, with internal contracts providing most of the separation the team currently needs.
Make module boundaries visible in code and data
Organize modules around business capabilities. Appointments should own the rules for reserving and cancelling a slot. Billing should decide whether an invoice may be issued. A directory named “services” does not create that ownership if every package can update every table.
Expose a small public interface for each module. An appointment module may ask billing for an account's purchasing eligibility; it should not read an invoice repository and interpret statuses itself. Keep internal classes inaccessible where the language permits, and use dependency tests where compiler boundaries are insufficient. Spring Modulith can verify module cycles and access to internal packages in a Spring application. Equivalent checks in another stack must target the same dependency rules.
Give tables an owner even when they share a database. Cross-module reporting can use an explicitly maintained read model. Cross-module writes need a business operation through the owning module. Otherwise the eventual migration cost accumulates quietly in SQL queries, scripts, and support tools.
Choose transactions before choosing messages
If reserving a slot and recording its charge must succeed together, a local database transaction may be the clearest implementation. Document that atomicity as part of the decision. Splitting the modules later would require a new consistency design, so it is misleading to claim that a future extraction is merely moving code.
Notifications have a different requirement. A booking can remain valid while an email is delayed. Persist the intent to notify alongside the booking, then let a worker deliver it with an idempotent handler. This avoids placing email delivery inside the request transaction. The distinction between durable work and a reusable event stream is explored in Kafka versus job queues.
Do not make every interaction asynchronous to imitate a distributed system. A synchronous in-process call can provide a straightforward result and a useful stack trace. Introduce a durable boundary where recovery, latency isolation, or independent consumption justifies the additional state.
Define extraction triggers that can be disproved
“We will need microservices when we grow” is not a trigger. A useful trigger identifies a persistent limitation: document rendering repeatedly exhausts memory despite process limits, or billing changes require an independent release process that the shared deployment cannot provide. Assign a measurement and an owner to each hypothesis.
First test cheaper remedies. A separate worker process can isolate heavy rendering without extracting all document ownership. Query changes can remove a database bottleneck. A release flag can decouple exposure from deployment. If these changes solve the constraint, the decision record should explain why the module remains inside the application.
When extraction is justified, inventory its inbound calls, owned data, transaction dependencies, and operational responsibilities. The first separation may be a process boundary with shared code, followed later by independent storage. Treat those as distinct decisions with their own rollback conditions.
Ask the architecture engagement to produce an enforceable boundary
For a small SaaS team, an architecture engagement can focus on one business capability instead of redesigning every module. Choose a capability whose changes currently spread across the application, such as cancellation and invoice adjustment. Ask for an ownership map, a proposed module interface, transaction rules, and one representative change that exercises them. The team should be able to see where the design lives in code.
Acceptance can include a boundary check that rejects an unwanted dependency, a test showing what happens when notification fails, and a decision record explaining the shared deployment costs. Require a receiving engineer to add a small behavior using the interface. If they must bypass the boundary to complete ordinary work, the design needs adjustment before it becomes the template for the rest of the product.
This approach suits a business that needs clearer ownership while retaining one release and operating model. If independent deployment is already a demonstrated requirement, include extraction as a competing option rather than assuming the monolith will remain suitable. We can review the current constraint, design a practical boundary, and implement a first example that your team can extend without commissioning a wholesale rewrite.
Review the record through one real change
Ask an engineer to add a cancellation fee using the proposed module rules. Which module authorizes the fee? Who owns the invoice adjustment? Can a retry create two charges? Which tests show that cancellation still works if notification delivery is unavailable? The exercise exposes unclear responsibilities more effectively than counting packages.
Keep the record short enough to update when a constraint changes. Link it to boundary tests and current ownership rather than copying implementation details into prose. An architecture review before a rewrite can establish which constraints are real; architecture design work can turn those findings into module contracts and an extraction plan with explicit tradeoffs.