Spring Boot Modulith

Executive Summary

Spring Boot Modulith defines the logical component model for the Algosure backend. The backend is a modular monolith where each business Domain maps to a governed application module, and modules coordinate through explicit application services, APIs, repositories, and internal domain events.

Why This Exists

Algosure needs modularity without premature microservices. Spring Boot Modulith supports strong module boundaries, domain ownership, event-driven coordination, testable dependencies, and a future path to service extraction where ownership and scale justify it.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

The Modulith architecture keeps engineering aligned to the Blueprint while reducing operational complexity in the early platform lifecycle.

Modulith Shape

flowchart TB
    subgraph Backend["Spring Boot Modulith Backend"]
        Identity[Identity Module]
        Organization[Organization Module]
        Compliance[Compliance Module]
        Opportunity[Opportunity Module]
        Bid[Bid Module]
        Contract[Contract Module]
        Supplier[Supplier Module]
        Marketplace[Marketplace Module]
        Funding[Funding Module]
        Learning[Learning Module]
        Intelligence[Intelligence Module]
        Notification[Notification Module]
        Analytics[Analytics Module]
        Billing[Billing Module]
        Administration[Administration Module]
        Shared[Minimal Shared Kernel]
        Events[Internal Event Bus]
        Outbox[Outbox Boundary]
    end

    Shared --> Identity
    Shared --> Organization
    Shared --> Compliance
    Shared --> Opportunity
    Shared --> Bid
    Shared --> Contract
    Shared --> Supplier
    Shared --> Marketplace
    Shared --> Funding
    Shared --> Learning
    Shared --> Intelligence
    Shared --> Notification
    Shared --> Analytics
    Shared --> Billing
    Shared --> Administration
    Identity --> Events
    Organization --> Events
    Compliance --> Events
    Opportunity --> Events
    Bid --> Events
    Contract --> Events
    Events --> Outbox

Modulith Principles

Principle	Meaning
Domain modules are first-class	Modules are shaped by business Domains, not screens, database tables, external integrations, or team convenience.
Internal models are encapsulated	A module's aggregates, entities, value objects, repositories, and internal services are not used directly by other modules.
Application services are the use-case boundary	Cross-module behavior enters through application services, API contracts, or event handlers.
Events carry business meaning	Events represent domain-significant facts and state transitions, not technical notifications.
Dependencies are deliberate	Module dependencies must be explicit, directional, reviewable, and testable.
Modulith first, microservices later	Extraction is a future option only after module ownership, contracts, scale, and operations justify it.

Standard Module Interior

flowchart TB
    API[API Boundary]
    Application[Application Services]
    Domain[Domain Model]
    DomainService[Domain Services]
    Repository[Repositories]
    Events[Domain Events]
    Handlers[Event Handlers]
    Outbox[Outbox Records]

    API --> Application
    Application --> Domain
    Application --> DomainService
    Domain --> Events
    Application --> Repository
    Repository --> Domain
    Events --> Handlers
    Events --> Outbox

Module Dependency Policy

Dependency Type	Allowed Use
Shared kernel dependency	Allowed only for universal technical primitives and stable metadata.
Application service dependency	Allowed when a use case requires another module's owned behavior and the dependency is approved.
API contract dependency	Allowed for explicit query or command boundaries that do not expose internals.
Event dependency	Preferred for asynchronous cross-module coordination.
Repository dependency	Not allowed across modules.
Aggregate or entity dependency	Not allowed across modules.
Database table dependency	Not allowed across modules.

Outbox Alignment

The outbox pattern is a future-safe event delivery boundary. A module records business state and domain events together, then reliable delivery publishes those events to internal subscribers or future external infrastructure.

Outbox Responsibility	Architecture Rule
Transactional event capture	Domain events that matter outside the module should be captured alongside the state change that produced them.
Reliable delivery	Delivery must support retry, idempotency, ordering where required, and failure visibility.
Event ownership	The publishing module owns event meaning and compatibility.
Subscriber independence	Subscribers must tolerate duplicate delivery and should not rely on hidden database coupling.
Future extraction	Outbox-aligned events preserve a path toward queues, streams, or service extraction without changing domain ownership.

Non-Implementation Boundary

This document does not define:

• Spring Modulith annotations.
• Package naming conventions.
• Build tooling.
• Runtime modules.
• Broker technology.
• Transaction configuration.
• Outbox implementation detail.
• Code-level dependency tests.