Spring Boot Modulith Engineering Foundation¶

Executive Summary¶

The Spring Boot Modulith Engineering Foundation translates the Algosure Blueprint and Architecture layer into an implementation model for the backend. It defines how approved Domains map to Spring Boot Modulith modules, how modules are structured, how boundaries are protected, and how engineering work remains aligned with DDD, AIOS, multi-tenancy, Keycloak, PostgreSQL, and event-driven principles.

Why This Exists¶

The Algosure Blueprint has defined Foundation, Domain Model, Practices, Digital Professionals, AIOS, Business Processes, and Architecture. Engineering now needs a stable foundation that tells future implementers how to turn that architecture into a modular Spring Boot backend without creating a god module, shared dumping ground, or source-of-truth drift.

Owner¶

The owner is the Chief Product Officer and Enterprise Architect.

Business Value¶

This foundation gives engineering teams a practical baseline for module structure, package conventions, dependency control, testing, events, persistence ownership, AIOS integration, and future microservice extraction.

Scope¶

flowchart TB
    Blueprint[Algosure Blueprint]
    Architecture[Architecture Layer]
    Modulith[Spring Boot Modulith Engineering Foundation]
    Modules[Domain-Aligned Modules]
    Tests[Boundary and Module Tests]
    Future[Future Microservice Extraction]

    Blueprint --> Architecture
    Architecture --> Modulith
    Modulith --> Modules
    Modulith --> Tests
    Modulith --> Future

Foundation Rules¶

Rule	Requirement
Spring Boot Modulith is primary	The backend starts as a modular monolith aligned to Spring Boot Modulith principles.
Architecture mirrors Domains	One approved Domain maps to one Modulith module where practical.
Domains own source facts	Operational facts, rules, lifecycle state, repositories, and events belong to the owning module.
Practices own capabilities	Practices shape workflows and operational capability but do not replace Domain ownership.
AIOS uses governed boundaries	AIOS and Digital Professionals interact through application services and approved tool boundaries.
PostgreSQL is primary	PostgreSQL is the primary operational database.
Keycloak is official IdP	Keycloak authenticates users and services; Identity owns business identity and authorization decisions.
Multi-tenant by design	Tenant and organization context are mandatory across APIs, modules, data, events, AIOS, and audit.

Documents¶

Document	Purpose
Engineering Vision	Defines the engineering direction for the Modulith implementation.
Modulith Principles	Defines non-negotiable engineering principles.
Package Structure	Defines Java package conventions.
Module Standard	Defines the required structure and metadata for every module.
Domain to Module Mapping	Maps approved Domains to module names and ownership.
Module Dependency Rules	Defines allowed and forbidden dependencies.
Shared Kernel Standard	Defines the minimal shared kernel.
Application Service Standard	Defines application service responsibilities.
Domain Service Standard	Defines domain service responsibilities.
Repository Standard	Defines persistence ownership and repository rules.
Command Query Standard	Defines command and query responsibility separation.
Event Standard	Defines internal event standards and outbox guidance.
Testing Standard	Defines Spring Modulith tests and boundary verification.
Migration to Microservices Strategy	Defines when and how modules may be extracted later.
Glossary	Defines engineering terms.