Skip to content
Almathal Handbook

Adapter

Accepted

An Adapter is the smallest unit of composition in Almathal. It wraps one underlying open-source library, framework, driver, container, or API with a uniform Manifest that declares its Capabilities, Contracts, compatibility, and provenance.

What an Adapter Wraps

An Adapter is not the library itself — it is a thin layer of metadata and integration hints that the platform maintains alongside the upstream library. The upstream code stays at its public location (Maven Central, npm, PyPI, Docker Hub). Almathal records:

  • What the library is (identity, version)
  • What it provides (Capabilities, Contracts implemented)
  • What it needs (dependencies, configuration, runtime services)
  • What it’s compatible with (other Adapters, scaffolders, runtime versions)
  • Where it came from (provenance, license, security history)
  • How to use it (imports, dependency snippets, typical usage patterns)
  • What can go wrong (known pitfalls)

The Adapter is the data structure the Composer and Stitcher consume when reasoning about whether and how to use the underlying library in a generation.

Why a Uniform Wrapper

Open-source libraries are not designed to compose. Two well-regarded auth libraries have incompatible assumptions about session handling, error formats, logging, and lifecycle. Two persistence libraries (Spring Data JPA and jOOQ) expose entirely different APIs even though they fill the same role.

The Adapter contract abstracts this: by declaring the Contract it implements (e.g., contract:persistence/repository/v1), an Adapter signals “I am substitutable with any other Adapter declaring the same Contract.” The downstream Stitcher generates code against the contract; the resolved Adapter provides the concrete pattern.

This is the same idea as interfaces in object-oriented programming, applied to the entire library ecosystem.

Adapter vs Module

This distinction is foundational. See also Concepts → Module.

AdapterModule
Wraps one library, container, or APIA composed assembly of multiple Adapters
AtomicComposite
adapter:java/spring-bootmodule:auth/jwt-with-rbac
Lives in Component LibraryLives in Module Library
Direct correspondence to an open-source projectA pre-built solution to a domain problem

Spring Data JPA is an Adapter. “Auth with JWT, RBAC, and audit logging” is a Module that uses Spring Security Adapter, a database schema, an audit-logging Adapter, and JWT handling.

Slices

Adapters are organized into slices by language or domain:

  • Java slice — backend frameworks, persistence, auth, messaging, observability, testing
  • TypeScript/JS slice — frontend frameworks, UI components, state management, build tooling
  • Python slice — web frameworks, data manipulation, ML, ETL, observability
  • AI / LLM slice — LLM provider SDKs, vector databases, orchestration frameworks, document processing, evaluation
  • Cross-cutting Infrastructure — databases, message brokers, storage, observability stacks, reverse proxies (typically containerized)

Slices are an organizational convenience, not a hard boundary. The slug namespace (adapter:<slice>/<name>) reflects them.

Adapter Lifecycle

Adapters move through these states (recorded in the Manifest’s lifecycle.status field):

  • Experimental — recently admitted, limited use, may be removed
  • Active — production-ready, fully supported
  • Deprecated — still functional but discouraged for new builds; will be removed in a future release
  • Superseded — replaced by a named successor Adapter
  • Archived — no longer available for new builds; retained only for historical resolution

State transitions are recorded in the Manifest’s lifecycle.audit_trail.

How Adapters Are Created and Maintained

Adapters do not appear automatically. They go through the Curation Pipeline:

  1. An agent or human identifies a candidate library (high frequency in real codebases, strong maintenance signals, compatible licensing)
  2. A Manifest is drafted (LLM-drafted, human-directed in early stages; LLM-drafted with human review later)
  3. Automated checks run: license verification, CVE scan, dependency analysis
  4. The Manifest is reviewed (by Human Reviewer for high-risk categories; by automated checks for low-risk)
  5. On admission, a UUID is assigned and the Adapter becomes available to Archetypes
  6. The Manifest is updated when the underlying library releases new versions

Manifest Authoring documents the process in detail.