Glossary
Every term used in this handbook is defined here. When a term has a dedicated concept page, it links to it. When two terms can be confused, the disambiguation is called out explicitly.
Adapter
A single curated building block in the Component Library. An Adapter wraps an underlying open-source library, framework, driver, container, or API (such as Spring Boot, React, or pgvector) with a uniform Manifest that declares its capabilities, contracts, compatibility, and provenance.
Adapters are the atomic units of composition. The smallest thing the platform retrieves and stitches.
See: Concepts → Adapter
AI Reviewer
The LLM-driven agent that performs post-generation oversight during the Output Review stage. Reviews generated code for anti-patterns, security concerns, and consistency issues. Operates as an advisory signal layered on top of deterministic Build Verification; does not block on its own.
Distinct from the Stitcher. The AI Reviewer uses a different model than the Stitcher to reduce the risk of an LLM rubber-stamping its own work.
Almathal
The platform itself. From Arabic المثال, meaning the example or the canonical pattern. The name reflects the central thesis: every component in the library is a vetted, exemplary pattern, and generated applications are compositions of canonical examples rather than improvisations.
Archetype
A reusable template for a complete application type — for example, RAG chatbot, internal CRUD admin tool, or point-of-sale system. An Archetype is defined by an Archetype Spec that declares which Scaffolders to invoke, which Adapter and Module Slots are required, which Variation Points the user can configure, and which Seams the Stitcher must fill.
Archetypes are the unit of capability offered to end users: “Almathal can produce a RAG chatbot” means an Archetype for that app type exists.
See: Concepts → Archetype
Archetype Spec
The resolved, fully-populated configuration for one specific build of an Archetype. Combines the Archetype definition with the user’s filled-in Variation Points, chosen Adapters and Modules, and selected versions. Used by the Composer to drive Scaffolding and prepare the Stitcher handoff.
See: Concepts → Spec · Schemas → Archetype Spec v1
Build Approval
The Pipeline Stage where the user reviews the resolved Archetype Spec (rendered as a human-readable summary by the LLM) and either approves, edits, or rejects it before generation begins. The approval is recorded as part of the audit trail. Blocking — generation does not proceed without explicit user sign-off.
Build Verification
The Pipeline Stage where the generated application is mechanically validated: compilation, linting, smoke tests, and seam contract verification. Deterministic, blocking. The Stitcher is asked to retry (within a bounded attempt count) if verification fails.
Distinct from Output Review, which is the LLM-driven supplementary review of the same output.
Capability
A declared operation or feature that an Adapter or Module provides. Capabilities are namespaced, versioned identifiers (for example, capability:persistence/transactions/v1 or capability:auth/sso/v1) drawn from a central registry. Archetypes declare required capabilities on their Slots; Adapters and Modules declare provided capabilities in their Manifests. The Composer matches required and provided capabilities during Spec Resolution.
See: Concepts → Capability · Governance → Capability Namespace
Compatibility Validation
The Pipeline Stage where the resolved combination of Adapters, Modules, Scaffolders, and runtime versions is checked against the distributed compatibility matrix. Deterministic, blocking. The AI Reviewer generates a human-readable explanation but does not perform the check itself.
Component Library
The curated collection of Adapters. The lowest layer of the platform — atomic, language-and-framework-level building blocks. Organized into slices (Java, TS/JS, Python, AI/LLM, Cross-cutting Infrastructure).
Composer
The deterministic orchestrator that sits between the Component Library / Module Library and the Stitcher. Resolves Archetype Specs, validates compatibility, invokes Scaffolders, and prepares the structured handoff for the Stitcher. Never invokes an LLM.
The Composer is the trust boundary: everything above it (Stitcher, AI Reviewer) is bounded LLM work; everything at or below it (Composer, Module Library, Component Library) is deterministic and inspectable.
Contract
The abstract interface that Adapters or Modules implementing the same role share. For example, the contract contract:persistence/repository/v1 defines the operations any persistence Adapter must support (save, findById, findAll, delete). Both Spring Data JPA and jOOQ implement the same contract with different concrete patterns, making them substitutable in Slots requiring that contract.
Contracts enable substitution. Without them, Adapters with the same Capability might still produce incompatible code shapes.
See: Concepts → Contract
Curation Pipeline
The agent-and-human collaborative process by which the Component Library and Module Library are continuously expanded and maintained. Agents discover candidates and run automated checks; humans ratify high-risk admissions while low-risk admissions can be agent-approved with post-hoc human sampling.
See: Governance → Curation Pipeline
Human Reviewer
A platform team member with the authority to ratify changes to the Component Library, Module Library, Capability namespace, or Archetype definitions. The role exists primarily in the Curation Pipeline where human judgment is required for high-risk admissions.
Distinct from the AI Reviewer, which performs post-generation output oversight on individual builds.
Manifest
The JSON descriptor for an Adapter or Module. Declares identity, version, Capabilities, Contracts implemented, compatibility constraints, dependencies, provenance, integration hints, and operational status. Manifests are the contract between Library and Composer: everything the Composer needs to make decisions about a building block lives in its Manifest.
See: Concepts → Manifest · Schemas → Adapter Manifest v1
Module
A pre-composed assembly of Adapters delivering a complete business-domain function (Auth, Payments, Billing, RAG Core, etc.). A Module is one level of abstraction above an Adapter and one level below an Archetype: too coarse to be a single library, too narrow to be a whole app.
Modules can be platform-composed (assembled from raw Adapters by the platform team) or curated from existing open-source modular projects (wrapped from projects like Lago or Ory Kratos). The Manifest records which kind, but the Composer treats both identically.
See: Concepts → Module
Module Library
The curated collection of Modules. Sits between the Component Library and the Composer. Holds the reusable business-domain building blocks that multiple Archetypes compose into complete applications.
Output Review
The Pipeline Stage where the AI Reviewer inspects the generated application after Build Verification passes. Advisory, non-blocking. Surfaces warnings to the user about anti-patterns, security concerns, or consistency issues.
Pipeline Stages
The sequence of stages a generation moves through. In order: Spec Resolution → Compatibility Validation → Build Approval → Seam Validation → Scaffolding → Stitching → Build Verification → Output Review.
See: Architecture → Runtime Pipeline
Provenance
The record of where an Adapter or Module came from, who maintains it, what license it carries, when it was admitted to the library, by what method (human-reviewed or agent-ratified), and its security and audit history. Provenance is a first-class field in every Manifest and is the foundation of Almathal’s enterprise trust differentiation.
Resolver
The Composer subcomponent that performs Spec Resolution: turning user input into a fully populated Archetype Spec with all Slots filled, Variation Points resolved, and versions locked.
Scaffolder
An existing best-in-class code generation tool that the Composer orchestrates rather than reinventing: JHipster (Java enterprise), Spring Initializr (Spring Boot starters), create-t3-app (modern TS frontend), Yeoman (long tail), and others. The Composer invokes Scaffolders with computed configuration; the Scaffolder produces a code skeleton; the platform post-processes the output and hands it to the Stitcher.
Scaffolder Runner
The Composer subcomponent that knows how to translate an Archetype Spec into each Scaffolder’s input language, invoke the Scaffolder in a sandboxed environment, and capture its output.
Scaffolding
The Pipeline Stage where Scaffolders are invoked to produce the application’s code skeleton. Deterministic; no LLM involvement.
Seam
A specifically declared integration point in an Archetype Spec where the Stitcher must generate custom code that integrates Adapters and Modules. A Seam includes a contract: required Adapters to use, output file paths, behaviors to implement, and verification criteria. Seams bound the Stitcher’s work — without them, the Stitcher would have to discover where to make changes.
See: Concepts → Seam
Seam Validation
The Pipeline Stage where every Seam in the resolved Archetype Spec is statically validated before the Stitcher is invoked: inputs resolve, required Adapters are present, output paths don’t conflict, capabilities are covered, verification is feasible. Catches archetype-definition bugs before LLM tokens are spent on doomed generations.
Slot
A position in an Archetype where an Adapter or Module gets plugged in. A Slot declares: its identifier, the Category of thing it accepts, the Contract and/or Capabilities it requires, and a default. During Spec Resolution, the Resolver selects an Adapter or Module to fill each Slot.
See: Concepts → Slot
Spec
Short for Archetype Spec. The resolved configuration for a build.
See: Concepts → Spec
Spec Resolution
The Pipeline Stage where user input is converted into a fully populated Archetype Spec. Variation Points are filled, Slots are resolved to specific Adapters and Modules, versions are locked.
Stitcher
The bounded LLM layer that fills Seams, generates UI, and applies last-mile customization to the output of Scaffolding. Operates against explicit Seam contracts produced by the Composer; does not have free range over the generated app.
Stitching
The Pipeline Stage where the Stitcher does its work — filling Seams and generating UI according to the contracts declared in the Archetype Spec.
UUID
The immutable internal identifier assigned to every Adapter, Module, Archetype, Capability, and Contract at admission to the registry. Used in audit logs, build records, and database joins. Coexists with the human-readable namespaced slug; slugs are mutable, UUIDs never change.
Namespaced Slug
The human-readable identifier for an Adapter, Module, Archetype, or other entity. Follows the pattern <type>:<namespace>/<name> (e.g., adapter:java/spring-data-jpa, module:auth/jwt-with-rbac, archetype:rag-chatbot). Used in Manifests, Archetype Specs, documentation, and day-to-day reference.
Variation Point
A user-configurable choice within an Archetype. Declared in the Archetype with type (enum, user-defined list, string, etc.), constraints, default, and UI hints. The hybrid form-plus-conversation input model renders Variation Points as form fields with conversational refinement for the unstructured parts.
Disambiguation Notes
Adapter vs Module. An Adapter wraps one library or service. A Module is a composed assembly of multiple Adapters delivering a business-domain function. Spring Data JPA is an Adapter; “Auth with JWT and RBAC” is a Module.
Component Library vs Module Library. The Component Library holds Adapters (atomic). The Module Library holds Modules (composed). Modules are made from Components; the Module Library sits above the Component Library in the architecture diagram.
Capability vs Contract. A Capability is a declared feature (“this thing supports pagination”). A Contract is the interface shape (“this is the operation signature for paginated queries”). Two Adapters with the same Capability might have different Contracts; two Adapters with the same Contract are substitutable.
Stitcher vs AI Reviewer. Both are LLMs. The Stitcher produces code (filling Seams, generating UI). The AI Reviewer inspects the produced code. Different models are used for each to avoid an LLM rubber-stamping its own output.
Build Verification vs Output Review. Build Verification is mechanical (compile, lint, test) and blocking. Output Review is LLM advisory and non-blocking. Both run after Stitching.
Scaffolder vs Composer. A Scaffolder is an external tool (JHipster, etc.) that produces code skeletons. The Composer is Almathal’s own orchestrator that decides which Scaffolders to invoke, with what configuration, and what to do with the output.