Module

Accepted

A Module is a pre-composed assembly of Adapters that delivers a complete business-domain function — Auth, Payments, Billing, Audit Logging, RAG Core, and so on.

Modules occupy the middle layer between individual Adapters and complete Archetypes. They are large enough to solve a real domain problem on their own, but small enough to be reused across multiple Archetypes.

Why Modules Exist

Without Modules, every Archetype would need to know how to assemble its own auth, payments, observability, etc. from raw Adapters. Two failure modes follow:

1. Duplicated composition logic. The same Adapter combinations get re-wired in every Archetype that needs auth, every Archetype that needs payments. Maintenance multiplies.
2. Inconsistent results. Two Archetypes that both “include auth” end up with subtly different auth setups, depending on who authored the Archetype.

Modules solve both: compose the assembly once, validate it once, reuse it across every Archetype that needs that function.

What a Module Contains

A Module’s Manifest declares:

• Identity (slug, UUID, version, display name)
• Constituent Adapters — which Adapters this Module composes and how they wire together
• Capabilities provided to the Archetype
• Contracts implemented
• Configuration surface — what the Archetype must provide (e.g., database connection, JWT secret)
• Compatibility constraints
• Provenance (platform-composed or curated from upstream)

A typical Auth Module might compose:

• adapter:java/spring-security for the framework
• adapter:java/nimbus-jose-jwt for JWT handling
• adapter:java/spring-data-jpa for user persistence
• adapter:infra/keycloak (optional) for external identity
• A schema migration set for users, roles, and audit tables
• An API surface for login, logout, token refresh
• A small UI Component pack for login/registration screens

This composition is encoded in the Module’s Manifest and validated by the platform team.

Two Provenance Types

Modules come from two sources:

Platform-composed

The platform team designs the assembly from raw Adapters. The Module exists only within Almathal. The Manifest’s provenance records composition_source: "platform-composed" and lists the constituent Adapters.

Curated from open source

A high-quality open-source modular project already exists for the domain (Lago for billing, Ory Kratos for auth, etc.). The Module wraps it: dependencies, configuration surface, integration hints. The Manifest’s provenance records composition_source: "upstream" and the upstream project.

Both kinds appear identically to the Composer and the Stitcher. The provenance distinction matters for trust auditing, not for runtime composition.

Module vs Adapter

Property	Adapter	Module
Scale	One library / service	A composed solution to a domain problem
Scope	Technical building block	Business function
Example	adapter:java/spring-security	module:auth/jwt-with-rbac
Inside	An upstream library	Multiple Adapters + glue + schemas + UI
Reuse	Across many Modules	Across many Archetypes

A useful rule of thumb: if a developer would normally write “wire these libraries together to do X,” that wiring becomes a Module. If a developer would use a single library directly, that’s an Adapter.

Module vs Archetype

Modules are not Archetypes. An Archetype is a complete application template. A Module is a reusable component within an Archetype.

A point-of-sale Archetype might compose: an Auth Module, a Payments Module, an Inventory Module, an Accounting Module, plus some Archetype-specific glue. The Archetype’s value is the combination and the Seams that connect the Modules; the Modules themselves are reused across POS, e-commerce, and marketplace Archetypes.

Module Versioning

Modules use semver, managed by the platform team:

• Patch — internal Adapter updates that don’t change the Module’s API or contract
• Minor — new optional features, new optional configuration
• Major — breaking changes to the Module’s API, schema, or contract

When a Module’s constituent Adapters change, the Module’s compatibility matrix is updated. Generations using older Module versions continue to resolve correctly because of the ID scheme’s versioning rules.

Module Lifecycle

Same states as Adapters: Experimental → Active → Deprecated → Superseded → Archived. Recorded in the Module Manifest’s lifecycle.status.

Related

• Adapter — what Modules are composed of
• Archetype — what Modules compose into
• Manifest — the JSON descriptor
• Schemas → Module Manifest v1 — the formal schema