Modular Monolith Architecture and Module Architect

Wrote docs/architecture/modular-monolith-architect/00-overview/modular-monolith-architect-overview.md and docs/architecture/modular-monolith-architect/verification/fitness-self-check.md. Complete enterprise Modular Monolith architecture specification establishing strict package encapsulation, in-process event choreography, schema partitioning, and automated Spring Modulith verification.

---

skill: modular-monolith-architect

Modular Monolith Architecture: Retail Banking & Wealth Platform [MODMONO-BANK-001]

Summary

This specification establishes the enterprise Modular Monolith architecture, module boundary contracts, in-process communication choreography, and database schema isolation for retail-wealth-modular-platform v3.0 under run ID banking-modmono-arch-001. It unifies six core financial subdomains (Retail Deposits, Commercial Lending, Investment Portfolios, Customer Master, KYC Compliance, and General Ledger) across 42 engineers into a single, high-performance deployable JVM artifact sustaining 15,000 peak transactions/second. It decisively eliminates the architectural erosion and circular coupling demonstrated in incident INC-4934 (where unconstrained package imports between Deposit and Lending created cyclic database deadlocks and blocked production releases for 5 weeks). The architecture establishes

strict Spring Modulith package boundaries, restricts inter-module access strictly to exported .api packages, encapsulates internal domain logic in package-private classes, routes cross-module side effects via

in-process asynchronous domain events, and partitions the shared PostgreSQL Aurora database into six isolated relational schemas with zero cross-schema foreign keys.

Detailed Description

Unstructured monolithic codebases inevitably decay into a "Big Ball of Mud" where every service references every entity, making independent testing and future extraction impossible. Conversely, breaking an application into dozens of distributed microservices introduces massive operational drag for teams under 50 engineers. A disciplined Modular Monolith architecture provides the logical isolation and clear team ownership of microservices with the zero-network performance and transactional simplicity of a monolith. Modules communicate across explicit, compiler-enforced interfaces, preventing circular dependencies and preserving clean boundaries.

Incoming Banking Transactions (15,000 req/sec)
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│ Single JVM Deployment Artifact (Spring Modulith 1.2)   │
│                                                        │
│ [ Module: `deposits` ] ──(In-Process Event)──┐         │
│   ├── Public API: `AccountDebitUseCase`      │         │
│   └── Internal: `CheckingAccountEntity`      ▼         │
│                                       [ Event Router ] │
│ [ Module: `lending` ] ◄──────────────────────┘         │
│   ├── Public API: `LoanPaymentFacade`                  │
│   └── Internal: `LoanFacilityRecord`                   │
└────────────────────────────────────────────────────────┘
                         │
                         ▼ (Single Local ACID Transaction)
[ AWS Aurora PostgreSQL Cluster ]
  ├── Schema: `deposits.*` (Zero Cross-Schema Foreign Keys)
  └── Schema: `lending.*`  (Zero Cross-Schema Foreign Keys)

Criteria and weights

Mechanism Specifications

1. Component Boundary:

   • Owner: Chief Architect (David O'Reilly).
   • Trigger: Inbound HTTP/REST application request or scheduled batch trigger arriving at a module's public entry point.
   • State/Algorithm: The modular monolith organizes the codebase into six root-level capability packages (deposits, lending, portfolios, customer, kyc, ledger). Each module encapsulates its internal domain models, JPA repositories, and orchestration services within package-private scopes. External access is strictly constrained to the module's public .api package (interfaces and immutable record DTOs).
   • Failure Behavior: Direct compile-time references to another module's internal classes trigger immediate build failure via ArchUnit rules.
   • Test Oracle: ArchUnit test ApplicationModules.of(Application.class).verify() ensuring no unexported classes are referenced across module boundaries.

2. Port And Adapter:

   • Owner: Module Engineering Squad Leads.
   • Trigger: Cross-module functional dependency or external integration requirement.
   • State/Algorithm: Inbound ports are exposed as pure Java interfaces in the module's .api package (e.g., AccountDebitUseCase). Outbound dependencies are injected via Spring IoC using interface abstraction. Internal adapters (e.g., repository implementations, third-party gateway clients) reside in private internal packages and cannot be instantiated directly by other modules.
   • Failure Behavior: Unresolved dependency injection or missing adapter implementation fails during JVM bootstrap context initialization.
   • Test Oracle: Spring Boot module slice test verifying each module initializes its internal dependencies in isolation with mock ports.

3. Runtime Flow:

   • Owner: Head of Wealth (Elena Rostova).
   • Trigger: Execution of a cross-module business transaction (e.g., loan repayment debiting a deposit account).
   • State/Algorithm:
     1. Client submits loan repayment request to lending module REST controller.
     2. lending module calls deposits.api.AccountDebitUseCase.debit(...) via synchronous in-process method invocation (latency < 0.1 ms).
     3. deposits module executes debit within local database transaction, validating account balance.
     4. Upon successful debit, deposits publishes AccountDebitedEvent to Spring ApplicationEventPublisher.
     5. ledger module consumes event asynchronously via in-process queue to record journal entries.
     6. Control returns to caller with confirmation in < 5 ms total execution time.
   • Failure Behavior: Insufficient balance in deposits throws domain exception InsufficientFundsException, immediately aborting the operation without state mutation.
   • Test Oracle: End-to-end integration test confirming repayment flow commits valid journal entries and completes under 10 ms p99 latency.

4. Failure Policy:

   • Owner: Reliability Engineering Lead.
   • Trigger: Runtime exception, database deadlocks, or slow query execution within a module.
   • State/Algorithm:
     • Failure Isolation: Module execution boundaries isolate exceptions; unchecked runtime exceptions in asynchronous event consumers do not roll back the upstream publisher's committed transaction.
     • Deadlock Prevention: Strict alphabetical resource ordering on multi-entity operations; cross-schema queries are strictly forbidden.
     • Event Delivery Guarantees: Failed asynchronous domain events are recorded in the Spring Modulith Event Publication Registry table for retry up to 5 times before alerting.
   • Failure Behavior: Exhausted event retries mark the event publication as FAILED in the registry table and emit a high-priority operational alert.
   • Test Oracle: Chaos test simulating unhandled consumer exception verifying upstream transaction commits successfully and failed event persists in registry.

Architectural Concerns

1. Strict Encapsulation:

   • Trace to source: INC-4934 post-mortem where internal class access caused circular locking.
   • Architectural consequence: Modules retain complete autonomy over internal data structures and refactoring.
   • Enforcement: Java package-private visibility combined with Spring Modulith compilation assertions.
   • Recovery route: Architecture review board waiver required to expose new public API methods; emergency hotfix must add interface to .api package.

2. Clean Boundaries:

   • Trace to source: Enterprise Architecture mandate for team autonomy and microservice extraction readiness.
   • Architectural consequence: Explicit dependency graph allows any of the 6 modules to be extracted into a standalone service with minimal refactoring.
   • Enforcement: Directed Acyclic Graph validation in CI; circular imports fail the build.
   • Recovery route: Introduction of asynchronous domain events to decouple bidirectional synchronous module dependencies.

3. Low Operational Overhead:

   • Trace to source: Team capacity constraint of 42 engineers without a dedicated 24/7 SRE platform team.
   • Architectural consequence: Single deployment pipeline, single JVM monitoring agent, zero distributed tracing tax, zero network serialization latency.
   • Enforcement: Rejection of Kubernetes microservice sprawl; single container artifact deployed to AWS ECS/EKS.
   • Recovery route: Horizontal pod autoscaling based on CPU/memory metrics without distributed consensus overhead.

Alternatives rejected

Contracts and Invariants

Strict Public API Facade Invariant [INV-MOD-01]
  Classes outside a module's designated `.api` package must be marked package-private.
  Directly importing classes from another module's `.internal.*` packages fails CI compilation immediately.

Zero Cross-Schema Foreign Key Policy [INV-MOD-02]
  Relational database tables in one module schema must not establish foreign key constraints
  to tables in another module schema. Cross-module references must use immutable UUID values.

Acyclic Module Dependency Rule [INV-MOD-03]
  The module dependency graph must be strictly acyclic (Directed Acyclic Graph).
  Circular dependencies between modules (e.g. A -> B -> A) are blocked by automated build gates.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against modular monolith standards:

• Boundary Rigor: PASS. Public .api facades and package-private internals prevent code leakage.
• Acyclic Graph: PASS. Spring Modulith build verification guarantees zero circular dependencies.
• Data Isolation: PASS. Dedicated PostgreSQL schemas with zero cross-schema foreign keys.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-MOD-01: Elena Rostova to determine whether in-process domain event publishing should use the Spring Modulith Event Publication Registry backed by the local database to guarantee at-least-once in-process delivery (Owner: Elena Rostova).

Next steps

1. Core Engineering configures ApplicationModules.of(Application.class).verify() in root unit tests.
2. Refactor existing subdomains into explicit .api and .internal package structures.
3. Execute Flyway migration splitting the shared database into six isolated relational schemas.

---

skill: modular-monolith-architect

Retail Banking Modular Monolith — Fitness Self-Check [MODMONO-BANK-FIT-001]

Summary

This fitness self-check evaluates the modular monolith architecture against three critical red-capable domain failure probes: shared mutable ownership, leaky abstraction, and implicit coupling. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Shared JVM heap memory contention during large month-end batch interest accrual runs. Accepted by David O'Reilly with heap sizing set to 16 GB with ZGC.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Architecture Guild incorporates Spring Modulith verification tests into master pull request checks.
2. Platform team verifies that Flyway migration scripts enforce separate database schemas per module.
3. Conduct quarterly architectural review auditing module coupling metrics and extraction readiness.