Modulith Principles

Executive Summary

Modulith Principles define the engineering rules that keep the Spring Boot backend modular, domain-aligned, testable, secure, and ready for future service extraction.

Principles

Principle	Engineering Rule
Domain first	Modules are shaped by approved Domains, not screens, tables, integrations, or convenience.
One Domain, one module where practical	Each approved Domain maps to one Modulith module unless an architecture decision approves an exception.
No god module	No module may own unrelated orchestration, source facts, APIs, repositories, events, and integrations.
No shared dumping ground	Shared code must remain minimal, stable, technical, and non-domain-owning.
Application services are boundaries	Commands, queries, AIOS tool calls, workflows, and integration requests enter through application services.
Repositories are private	A module's repositories are not used by other modules.
Events coordinate	Cross-module workflows should use internal events where synchronous coupling is not required.
PostgreSQL is primary	Operational source facts live in PostgreSQL under module ownership.
Multi-tenant always	Tenant and organization context are validated at API, application service, repository, event, and audit boundaries.
Secure by design	Keycloak, Identity authorization, entitlement checks, audit, and least privilege are baseline controls.

Boundary Diagram

flowchart TB
    API[API / Controller]
    App[Application Service]
    Domain[Domain Model]
    Repo[Private Repository]
    Event[Published Event]
    Other[Other Module]

    API --> App
    App --> Domain
    App --> Repo
    Domain --> Event
    Event --> Other

Review Rule

Any implementation that requires a module to directly mutate another module's owned data, call another module's repository, or use another module's internal aggregate requires redesign or an approved architecture decision.