Skip to content
Almathal Handbook

ADR-0002: Three-Layer Design

Accepted

Date: 2026-06-10

Context

Given the retrieval-first thesis (ADR-0001), the platform must structure its retrieval, orchestration, and LLM work into clear layers with separate concerns. A monolithic “generate from prompt” architecture loses the trust and economic advantages; an over-decomposed architecture creates excessive interfaces.

Decision

Almathal uses a four-named-layer architecture (originally numbered Layer 1, 1.5, 2, 3 in the design conversation, later given proper names):

  1. Component Library — curated individual Adapters (libraries, frameworks, drivers, containers, APIs)
  2. Module Library — pre-composed business-domain assemblies of Adapters
  3. Composer — deterministic orchestrator (resolves Specs, invokes Scaffolders, validates contracts)
  4. Stitcher — bounded LLM layer (fills Seams, generates UI, customizes last-mile)

The Composer is the trust boundary: everything at or below it is deterministic and inspectable; everything above it (Stitcher, AI Reviewer) is bounded LLM work.

Rationale

  • The Component Library is the atomic level — too small to be useful alone, but necessary as the building block for Modules and direct use in some Archetypes.
  • The Module Library captures business-domain reuse: Auth, Payments, Billing, etc. Without it, every Archetype would re-wire these from raw Adapters.
  • The Composer concentrates all deterministic decision-making in one place, making it inspectable and reproducible.
  • The Stitcher is the only layer that invokes LLMs, making token economics easy to reason about and bound.

Consequences

  • Two separate libraries (Component and Module) require separate Manifest schemas and admission processes (ADR-0005).
  • The Composer’s design carries most of the platform’s complexity; substantial engineering investment.
  • Trust guarantees can be enforced at the Composer boundary, making them auditable.

References