Module Boundaries

Executive Summary

Module Boundaries defines the rules that govern communication, ownership, dependencies, database access, API exposure, events, shared kernel use, and AIOS interaction inside the Spring Boot Modulith.

Why This Exists

Without explicit boundaries, a modular monolith can degrade into a tightly coupled codebase with hidden database dependencies, shared service dumping grounds, and unclear domain ownership.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Strong module boundaries make Algosure easier to evolve, test, secure, audit, and potentially extract into services later.

Boundary Model

flowchart LR
    ModuleA[Owning Module]
    API[Owned API Boundary]
    Events[Published Domain Events]
    Projection[Subscribed Projection or Handler]
    ModuleB[Consuming Module]
    Shared[Minimal Shared Kernel]
    Database[(Owned Database Records)]

    ModuleA --> API
    ModuleA --> Events
    ModuleA --> Database
    ModuleB --> API
    Events --> Projection
    Projection --> ModuleB
    Shared --> ModuleA
    Shared --> ModuleB

Allowed Module Interactions

Interaction	Allowed When
API boundary call	The consuming module needs owned behavior or a governed query from another module.
Application service call	The dependency is deliberate, directional, and approved as part of a use case.
Domain event publication	A domain-significant fact occurred and other modules may react independently.
Event subscription	The subscriber owns its reaction and does not mutate the publisher's data.
Projection consumption	The projection is governed, rebuildable, and does not become hidden source ownership.
Shared kernel use	The shared type is universal, stable, minimal, and non-domain-owning.

Disallowed Module Interactions

Interaction	Reason
Direct repository access across modules	Violates persistence ownership and hides business dependency.
Direct aggregate or entity access across modules	Leaks internal domain model and creates coupling.
Direct database table reads across modules	Violates source-of-truth ownership and tenant isolation assumptions.
Shared business service for unrelated Domains	Creates a god service or shared dumping ground.
Generic workflow module owning all processes	Breaks Architecture Mirror Principle and Domain ownership.
AIOS writing module state directly	Bypasses source-domain rules, approvals, and audit ownership.
Analytics replacing operational ownership	Turns reporting projections into source facts.

Dependency Rules

Rule	Requirement
Direction must be clear	Dependencies must point from a use case to the owning module or from event publisher to subscriber.
Cycles require review	Cyclic module dependencies are architecture smells and require redesign or explicit decision.
Organization is referenced, not copied	Modules reference Organization through stable identifiers and approved context, not duplicated profile facts.
Identity is authoritative for access facts	Modules can enforce authorization outcomes, but Identity owns role, membership, and permission facts.
Billing owns entitlement facts	Modules can check entitlements through governed access but must not duplicate plan and limit ownership.
Administration owns platform policy	Modules consume approved policy configuration, but do not duplicate platform governance controls.

Database Ownership Rules

Rule	Meaning
Module owns its persistence model	Each module owns the records needed for its aggregates, lifecycle, and source facts.
Cross-module joins are not ownership	Reporting or read models may use governed projections, but operational ownership remains with the source module.
Foreign identifiers are references	Modules may store stable identifiers from other modules but not duplicate mutable source facts.
Repository boundaries are private	Repositories are module-internal and must not be injected into other modules.
Migrations follow ownership	Schema changes must be owned and reviewed by the module that owns the affected records.

AIOS Boundary Rules

Rule	Meaning
AIOS requests authorized context	Modules expose AIOS context only through approved application services or query boundaries.
AI outputs are proposals until accepted	AI-generated recommendations, summaries, drafts, and decisions become state only through module-owned application services.
Intelligence owns reasoning records	The Intelligence module owns AIOS reasoning metadata, explanations, memory workflow state, and task outcomes.
Source Domains own source facts	Intelligence may reference source facts but must not copy ownership or mutate them directly.
Human approval is preserved	High-impact AI outputs require approval according to workflow and policy.

Shared Kernel Boundary

The shared kernel is intentionally small. It exists to reduce duplication of universal primitives, not to centralize business behavior.

Allowed	Not Allowed
TenantId, OrganizationId, UserId, CorrelationId, EventId	Opportunity scoring rules.
Money, Percentage, DateRange where universal	Compliance readiness logic.
Event metadata and audit metadata primitives	Bid lifecycle state machine.
Technical result and error primitives	Funding qualification rules.
Stable reference types	Notification routing policies.

Non-Implementation Boundary

This document does not define dependency test tooling, package access modifiers, schema names, repository interfaces, or module build configuration.