ADR-0005: Module Library as Layer 1.5
Date: 2026-06-10
Context
Initial design used three layers: Component Library, Composer, Stitcher. During the design conversation, the need for pre-composed business-domain assemblies emerged. A “payment module” is not a single library (it’s Stripe SDK + database schema + API surface + UI + audit logging composed together) but is also not a complete Archetype (the same payment module is reused across POS, e-commerce, marketplace archetypes).
Forcing Archetypes to compose business modules from raw Adapters every time leads to duplicated wiring logic and inconsistent results.
Decision
Introduce a Module Library as a distinct layer between the Component Library and the Composer. A Module is a pre-composed assembly of Adapters delivering a complete business-domain function. Modules and Adapters have separate Manifest schemas but are treated identically by the Composer’s slot resolver at runtime.
Rationale
- Captures real-world reuse patterns: business-domain modules genuinely repeat across application types.
- Provides an abstraction level between technical building blocks and complete applications.
- Reduces Archetype complexity: an Archetype declares “needs an Auth module” rather than re-assembling auth.
- Allows curation of high-quality open-source modular projects (Lago, Ory Kratos) as Modules with platform-grade integration.
Consequences
- A second Manifest schema (Module Manifest) is required.
- The Composer needs both
adapter_slotsandmodule_slotsin Archetypes. - The curation pipeline must admit both Adapters and Modules.
- Module versioning requires care: Modules depend on Adapters that have their own versioning.
References
- Concepts → Module
- ADR-0024: Module Library Admits Both Provenance Types
- ADR-0002: Three-Layer Design