Modular Monolith

A logistics platform runs as a single Spring Boot jar. It deploys fine, but OrderService imports FleetRepository directly, the pricing package reaches into billing tables, and every release notes read "deployed all services." Twelve engineers coordinate through one CI pipeline, and a change to driver shifts touches four packages owned by three teams. Nobody wants microservices — the operational cost is real — but the monolith has become a distributed system's coupling without any of its deployment independence.

A modular monolith keeps one deployment unit while enforcing module-level boundaries. The federation is logical, not physical: one process, one build, one database if you like — but code arranged so that each module is a small application with a public face and a private body.

The mechanics rest on language features you already have. In Java or Kotlin, a module is a package tree where only a handful of types are public:

com.acme.orders/
  api/            public:  OrderModule, PlaceOrderCmd, OrderView
  internal/       package-private: OrderEntity, PricingRules, ShiftPlanner
  spi/            public interfaces this module needs FROM others

The rule is blunt: nothing outside com.acme.orders.internal may name a type from that package. Callers get OrderModule.placeOrder(cmd) and a DTO back. They never see the entity, never construct it, and — critically — never call orderRepository.save() because the repository class itself is package-private. That last point is what separates a real modular monolith from a naming convention: if you cannot reach the persistence layer of another module without going through its API, the module owns its data in practice, not just on a diagram.

Cross-module needs are declared, not scavenged. When orders needs to know whether a driver is on shift, it declares a dependency on fleet.spi.DriverAvailability, an interface owned by the consumer, and the fleet module provides an implementation at the composition root — the hexagonal port pattern applied between modules. The direction matters: consumer-owned interfaces mean fleet can be swapped or faked in tests, and orders never imports a fleet entity.

// owned by orders (consumer), implemented by fleet
public interface DriverAvailability {
    boolean isOnShift(DriverId driver, Instant at);
}

public final class PlaceOrderHandler {
    private final DriverAvailability availability;   // no FleetRepository in sight
}

Wiring happens in exactly one file — the composition root — which is the only place in the application allowed to see every module's public face:

@ModuleConfig
public class Wiring {
    @Bean DriverAvailability driverAvailability(FleetModule fleet) {
        return fleet::isOnShift;          // in-process today, proxy tomorrow
    }
}

Because every cross-module collaboration is routed through that single file, you can see the entire system's coupling on one screen, and tests replace any neighbor with a lambda. A cross-module call remains a method invocation: no serialization, no retry policy, no tail latency — the call graph is the same shape microservices will later have, executed at memory speed.

The payoff is autonomy inside one deployable. Team A merges a pricing change without reading fleet's code; the build fails if someone sneaks a cross-module import; onboarding means learning four module APIs instead of the entire codebase. And because there is still one process, you keep the properties microservices tax heavily — a cross-module call is a method invocation, transactions can span modules when you explicitly allow it, and there is no network in any test. Teams get service-like ownership without paying network and operational overhead yet — that is the pitch, and it is honest as long as the enforcement is real.

Six months after declaring "every module owns its packages," a developer adds import com.acme.fleet.internal.ShiftPlanner to an order handler because the API was missing a method and the deadline was not. The pattern repeats until internal is imported from everywhere and the boundary exists only in the README. The lesson: a boundary without a failing build is a suggestion. Three enforcement layers close the gap.

First, dependency rules as tests. ArchUnit reads your bytecode and asserts architecture in one file:

@Test void modules_do_not_reach_into_each_other() {
    ArchRule rules = classes().that().resideInAPackage("..orders.internal..")
        .should().onlyBeAccessed().byAnyPackage("..orders..");
    rules.check(producedClasses());

    noClasses().that().resideInAPackage("..billing..")
        .should().dependOnClassesThat().resideInAPackage("..orders..")   // declared cycle check
        .andShould().accessClass().where(true);                           // fail CI on violation
}

The same idea exists in other toolchains: import-linter for Python (contracts: orders.internal -> bb) , dependency-cruiser for TypeScript with noCrossModuleInternal rules, and modular Java's module system (module-info.java with requires and exports) where the compiler itself rejects illegal reads. Whichever you use, the rule must run on every pull request; a nightly report is ignored within a month.

Second, build-level modules. Splitting the monolith into separately compiled units — Gradle subprojects, Maven modules, npm workspaces, .NET assemblies — makes the boundary visible to the compiler instead of a test. orders can only reference fleet if its build file declares the dependency, and it can only see fleet's api source set because internal is not on the export path. This is the step that turns "we behave like services" into "we compile like services."

Third, database ownership inside the one database. The classic erosion is a shared schema where every service can JOIN orders o ON ... and a "quick fix" becomes a permanent coupling. The discipline:

Reporting is the honest complement to prevention. A monthly dependency report — module graph, cycles, fan-in/fan-out — gives each team the one metric that predicts trouble: who depends on whom. Rising fan-in on a module means its API is becoming a utility sink; any cycle means two modules now change together and cannot be extracted or tested independently. Architects track coupling metrics over time precisely because boundaries erode under deadlines in ways no single review catches — the erosion is invisible until you plot it.

Analytics deserves an explicit exception because it is the pressure that breaks schemas first. Reporting teams need cross-module reads, and granting them ad-hoc SELECT on every schema reopens the coupling door. The working pattern is a dedicated read-only role that can only read, fed instead by a nightly (or near-real-time) projection into a reporting.* schema — a copy, so the analytics joins never constrain how orders and fleet evolve their tables. The trade-off is staleness, and it is usually the right one: reports tolerate minutes of lag; production modules should not tolerate foreign rows tied to their schema shape.

In interviews, expect to be asked "how do you enforce module boundaries in a monolith?" Answer with the three layers — bytecode rules, compile-time modules, schema ownership — and add the tell that separates candidates who shipped: enforcement is only as good as the failure mode. A rule that warns passes; a rule that fails the build with the offending import in the message gets fixed in the same PR.

A modular monolith is not a consolation prize for teams too timid for microservices. It is a specific bet: pay for boundaries now, pay for distribution later only where evidence demands it. The bet has three legs.

What you gain immediately. Independent team ownership without coordination overhead: the pricing team merges to its module, reviews happen inside the owning team, and the shared pipeline stays green because modules do not import each other's internals. Testing gets cheaper — module tests run against in-process fakes of neighbors' SPI interfaces, so the default suite has no network and no containers. And you keep monolith economics: one deploy artifact, ACID transactions across the two or three modules that genuinely need them (used sparingly, with the participating modules named explicitly), and no on-call burden for message brokers, service meshes, or distributed tracing on day one.

What you deliberately delay. Per-service deploy pipelines, network failure modes, eventual consistency, schema duplication, versioned contracts — all of it. The team that would spend its first quarter building a platform instead ships product, and the boundary debt they accumulate is measured and visible rather than feared.

The extraction trigger. Split a module out only when one of three conditions is proven:

Without one of those, extraction is costume change: you get the cost of distribution and keep the coordination anyway. With one, extraction is mechanical — and this is where the design pays its dividend. The module already has a narrow API (its api package), consumer-owned SPI interfaces, private tables, and no inbound hacks, because CI has been proving it for two years. The move becomes: replace in-process calls to OrderModule with an RPC or event adapter implementing the same interface, move orders.* tables to their own Postgres, and delete nothing. Teams that skipped the modular stage face a rewrite; teams that kept it face a migration with a checklist.

The failure modes are worth naming so you can spot them in a review. Shared-internal drift — modules importing each other's internal via friend-module exemptions granted "temporarily." God module — one module that everyone requires (usually common or customers), where fan-in grows until it is a distributed monolith in embryo; the fix is to shrink its API to stable value types. Anemic cross-module calls — chatty method calls between two modules that mimic a network hop and argue, quietly, for real extraction.

Interview framing: "modular monolith vs microservices" is asked constantly. The strong answer gives the mechanism (enforced APIs, private data, CI rules), states the gain (autonomy without distribution), and names the trigger rather than the fashion — then links the boundary language to Bounded Contexts in Domain-Driven Design, which supplies the map for where the module cuts should go in the first place.