Modular Monolith Architecture Style Evaluation

Wrote docs/architecture/styles/modular-monolith-style-evaluation.md. Complete Modular Monolith style evaluation establishing logical module boundaries, in-process zero-network communication, schema separation, and ArchUnit compile-time enforcement.

---

skill: modular-monolith-style

Architecture Style Evaluation: Modular Monolith Style [STYLE-MODMONO-001]

Summary

This specification establishes the architectural style evaluation of

Modular Monolith Architecture for retail-loan-platform v3.0 under run ID loan-modmono-style-001. It evaluates candidate architectural styles for orchestrating loan origination, credit scoring, underwriting, and monthly loan servicing across 35 engineers (4 squads) serving 6.5 million retail borrowers. The evaluation resolves the operational overhead and distributed data inconsistency identified in audit AUD-4912 (where an experimental microservices pilot quadrupled cloud infrastructure expenditure and generated 4.2% data inconsistencies during network partition rollbacks, in an engineering team lacking dedicated 24/7 SRE staff). The evaluation compares three primary architecture styles: Traditional Big-Ball-of-Mud Monolith, 18 Distributed Microservices, and Modular Monolith with Compile-Time Boundary Enforcement (Spring Modulith + ArchUnit). It selects Modular Monolith as the optimal style, specifying strictly encapsulated in-process modules, zero-network in-memory event channels, isolated database schemas on a single PostgreSQL Aurora instance, and clean extraction seams for future selective microservice decoupling.

Detailed Description

Organizations with fewer than 50 engineers frequently suffer catastrophic productivity loss when adopting microservices prematurely. The operational burden of managing 18 distinct CI/CD pipelines, Kubernetes Helm charts, service meshes, and distributed tracing distracts small engineering teams from delivering business features. A Modular Monolith provides the structural hygiene, clear domain boundaries, and independent squad code ownership of microservices, while executing within a single deployment runtime. In-process function calls replace brittle network RPCs, atomic database transactions replace fragile distributed sagas, and compile-time boundaries prevent code spaghetti.

Incoming Loan Application (REST API: 6,200 apps/hour)
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│ Single Deployment Runtime (JVM 21 Spring Modulith)     │
│                                                        │
│ [ Module: `origination` ] ──(In-Process Event)──┐      │
│   ├── Package-Private Implementation            │      │
│   └── Public API: `LoanApplicationService`      ▼      │
│                                           [ Event Bus] │
│ [ Module: `underwriting` ] ◄────────────────────┘      │
│   ├── Package-Private Invariants                       │
│   └── Dedicated Logical DB Schema: `underwriting.*`    │
└────────────────────────────────────────────────────────┘
                         │
                         ▼ (Single Local ACID Transaction)
[ Unified AWS Aurora PostgreSQL Cluster ]
  ├── Schema: `origination.*` (Private to origination module)
  └── Schema: `underwriting.*` (Private to underwriting module)

Criteria and weights

Comparison

Result

Option C is selected. Modular Monolith enforces rigid module boundaries using Spring Modulith and ArchUnit; execution remains in-process on a single JVM; database schemas are strictly partitioned to guarantee future extraction optionality.

---

Required Mechanisms

1. Module Boundary & Package Encapsulation Model [MC-MB-01]

• The codebase is structured into four authoritative top-level modules:
  1. com.bank.loan.origination
  2. com.bank.loan.underwriting
  3. com.bank.loan.scoring
  4. com.bank.loan.servicing
• Strict Encapsulation Rule:
  • Only classes located directly in com.bank.loan.<module>.api are marked public.
  • All internal services, domain entities, and repositories reside in package-private packages (com.bank.loan.<module>.internal.*).
  • Cross-module access is enforced via ArchUnit and Spring Modulith @NamedInterface.

2. In-Process Communication & Zero-Network Hops [MC-IC-01]

• Modules interact strictly via:
  1. Direct Synchronous API Invocations: Invoking public interface methods exposed in the companion .api package.

In-Process Application Events: Publishing Spring Application Events (LoanApplicationSubmittedEvent) consumed asynchronously via in-memory thread pools.

Latency Impact: Cross-module interaction executes in

< 0.05 milliseconds (compared to 15–40 ms for network HTTP/gRPC).

3. Database Schema Partitioning & Foreign Key Governance [MC-SP-01]

• The single AWS Aurora PostgreSQL database is partitioned into isolated relational schemas:
  • CREATE SCHEMA origination;
  • CREATE SCHEMA underwriting;
  • CREATE SCHEMA servicing;

Zero Cross-Schema Foreign Keys: Foreign keys crossing schema boundaries are

strictly barred. Modules reference entities in other schemas exclusively via immutable UUID primary keys, guaranteeing zero database coupling.

4. Automated CI Architectural Enforcement [MC-AE-01]

• Continuous Integration runs Spring Modulith verification on every commit:

  @Test
  void verifyModularStructure() {
      ApplicationModules.of(Application.class).verify();
  }
  

• Any commit introducing an illegal cross-module internal reference or circular dependency immediately fails compilation and CI gating.

---

Invariants and Contracts

Strict Package-Private Module Encapsulation [INV-MODMONO-01]
  Classes outside a module's public `.api` package must be marked package-private.
  Directly importing internal classes from another module fails automated ArchUnit CI checks.

Zero Cross-Schema Database Foreign Keys [INV-MODMONO-02]
  Relational database tables owned by one module must not establish foreign key constraints
  to tables owned by another module. Cross-module identity references must use plain UUID strings.

In-Process Event-Driven Decoupling [INV-MODMONO-03]
  Cross-module business workflows that do not require immediate synchronous return values
  must be decoupled using in-process asynchronous domain events.

Explicit Unknowns

• Memory consumption growth on the single JVM heap when 35 concurrent developers deploy high-frequency integration tests (G-1).
• Time required to perform automated database backups on a single 1.8 TB PostgreSQL database housing all 4 partitioned schemas (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against Modular Monolith architecture standards:

• Operational Fit: PASS. Avoids distributed microservice tax for a 35-engineer team without dedicated SREs.
• Boundary Rigor: PASS. Spring Modulith and ArchUnit enforce compile-time package-private encapsulation.
• Data Autonomy: PASS. Isolated relational schemas and zero cross-schema foreign keys preserve extraction seams.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-MODMONO-01: David O'Reilly to determine whether database migration scripts (Flyway / Liquibase) should be maintained in separate per-module directories or a single root migration folder (Owner: David O'Reilly).

Next steps

1. Core Engineering configures Spring Modulith and ArchUnit test verifications in the master build file.
2. Refactor existing subdomains into explicit .api and .internal package structures.
3. Migrate the shared PostgreSQL database into four isolated schemas (origination, underwriting, scoring, servicing).