Component Architecture

Executive Summary

Component Architecture defines the C4 Level 3 logical component view for the Algosure Spring Boot Modulith backend. It maps Domains to Modulith modules and defines module-level responsibilities, boundaries, application services, domain services, repositories, internal events, outbox alignment, AIOS integration boundaries, and API boundary ownership.

Why This Exists

The Container Architecture identifies the Spring Boot Modulith backend as the core application container. Component Architecture decomposes that backend into domain-aligned modules so engineering can preserve DDD ownership, the Architecture Mirror Principle, tenant isolation, security, event-driven coordination, and AIOS governance.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

The component architecture prevents god modules, database ownership violations, shared dumping grounds, and hidden coupling before implementation begins.

C4 Level 3 Scope

At C4 Level 3, this document describes logical backend components and module relationships. It does not define package names, Java classes, database schemas, code, or final runtime infrastructure.

flowchart TB
    API[API Boundary Components]
    App[Application Services]
    Domain[Domain Services and Aggregates]
    Repo[Repositories]
    Events[Internal Domain Events]
    Outbox[Outbox Event Delivery Boundary]
    AIOS[AIOS Integration Boundary]
    Shared[Minimal Shared Kernel]

    API --> App
    App --> Domain
    Domain --> Repo
    Domain --> Events
    Events --> Outbox
    App --> AIOS
    Shared --> App
    Shared --> Domain

Modulith Module Set

Domain	Modulith Module	Primary Ownership
Identity	Identity module	Authentication interpretation, memberships, roles, permissions, sessions, API keys, MFA, authorization policy facts.
Organization	Organization module	Tenant root, organization profile, customer context, business structure, user organization relationships.
Compliance	Compliance module	Readiness, requirements, documents, verification, expiry, evidence, compliance risk.
Opportunity	Opportunity module	Tender discovery, aggregation, matching, saved opportunities, recommendations, opportunity lifecycle.
Bid	Bid module	Bid workspace, planning, collaboration, proposal preparation, approvals, submission readiness.
Contract	Contract module	Awarded contract conversion, delivery, milestones, invoices, payments, performance, closeout.
Supplier	Supplier module	Supplier profiles, relationships, quotes, ratings, trust state, supplier performance.
Marketplace	Marketplace module	Marketplace listings, provider visibility, supplier discovery, quote requests, marketplace workflows.
Funding	Funding module	Funding needs, readiness, applications, partner offers, cash-flow risk, repayment context.
Learning	Learning module	Courses, lessons, quizzes, certificates, learning paths, maturity learning.
Intelligence	Intelligence module	AIOS-facing orchestration context, reasoning records, memory workflows, AI event interpretation, explanations.
Notification	Notification module	Notification intent, preferences, reminders, escalations, delivery history, channel status interpretation.
Analytics	Analytics module	Operational metrics, dashboards, KPI snapshots, reports, performance summaries, executive insights.
Billing	Billing module	Plans, subscriptions, invoices, payment state, entitlements, limits, renewals, cancellations.
Administration	Administration module	Platform configuration, feature flags, support operations, audit review, policy configuration, governance controls.

Component Types Per Module

Each domain module should contain the same logical component categories where relevant.

Component Type	Responsibility
API boundary components	Own inbound commands, queries, contracts, request validation, tenant context requirements, and response ownership for the module.
Application services	Coordinate use cases, transactions, policies, repositories, domain services, events, external integration requests, and AIOS requests.
Domain services	Encapsulate domain behavior that does not naturally belong to a single aggregate or entity.
Aggregates and entities	Own invariants, lifecycle transitions, business rules, and domain event creation.
Repositories	Provide persistence access only for aggregates and records owned by the module.
Event publishers and handlers	Publish module-owned domain events and consume subscribed events from other modules through governed contracts.
Integration adapters	Represent outbound or inbound integration interaction owned by the module through approved integration boundaries.
AIOS adapters	Request or receive AIOS work without letting AIOS own source facts or mutate module state directly.

Shared Kernel Rules

The shared kernel must be minimal and stable.

Allowed in Shared Kernel	Not Allowed in Shared Kernel
Tenant identifier value types	Domain aggregates.
User and actor reference value types	Business workflows.
Time, money, reference, and identifier primitives where genuinely universal	Cross-domain services.
Common event metadata structures	Integration logic.
Audit metadata primitives	Repository abstractions that hide ownership.
Error and result primitives that are not domain-specific	Generic business rules.

Core Boundary Rules

Rule	Meaning
One Domain per module where practical	Each approved Domain maps to a distinct Modulith module unless an architecture decision records an exception.
No god module	No module may own orchestration, data, rules, APIs, integrations, and events for unrelated Domains.
No shared dumping ground	Shared components must remain small, technical, stable, and non-domain-owning.
No direct database ownership violations	A module may persist and query its own records only; cross-module reads require APIs, events, projections, or approved query contracts.
APIs are owned by modules	Each module owns its inbound API boundary and must not expose internal aggregates as public contracts.
Events are business contracts	Internal domain events communicate business meaning between modules and must be versioned and governed.
AIOS is a boundary, not a shortcut	AIOS can request context and return outputs, but module-owned facts change only through module-owned application services.
Outbox is future-safe delivery	Domain events should be recorded with transactional state and delivered through an outbox pattern when reliable asynchronous delivery is needed.

Non-Implementation Boundary

This document does not define:

• Java package names.
• Spring annotations.
• Class names.
• Database tables.
• Event payload schemas.
• Controller routes.
• Transaction manager configuration.
• Message broker product.
• Outbox table schema.