Skip to content
Almathal Handbook

ADR-0001: Retrieval-First Architecture

Accepted

Date: 2026-06-10

Context

Current AI coding tools (Cursor, Lovable, Bolt, v0, Replit Agent) generate code primarily by invoking large language models on every request. This produces apps quickly but burns substantial tokens on regenerating code patterns that exist in canonical form elsewhere, provides no provenance for the produced code, and offers no trust guarantees for enterprise use. Frontier model providers are operating these services at significant losses on inference; the cost structure is supported by venture funding rather than unit economics.

Most software is recombination of well-understood patterns, not novel invention. The ratio is roughly 90% recombination and 10% genuinely new code, even in skilled professional work.

Decision

Almathal will be retrieval-first: when a working implementation exists in the curated libraries, the platform composes it rather than regenerating it. LLMs are invoked only at integration seams, for UI generation, and for last-mile customization that no archetype can fully anticipate.

Rationale

  • Token economics. Retrieval is essentially free; LLM stitching at declared seams costs tokens proportional to the seams, not to the codebase size. Generated apps cost an order of magnitude less than equivalent pure-LLM generation.
  • Trust and provenance. Retrieved components have known sources, licenses, and security histories. LLM-generated code does not.
  • Reproducibility. Composition is deterministic; regeneration is stochastic.
  • Improvement compounds. A curated library improves with each addition; pure-LLM tools improve only when the underlying model improves.

Consequences

  • The platform requires a curated library — Components and Modules — to compose from. This is significant ongoing engineering work, addressed by the Curation Pipeline.
  • The platform cannot serve requests for which no canonical composition exists, except via the pure-LLM fallback path (ADR-0013).
  • The architecture and economics depend on the curated library remaining current; stale libraries degrade the product.

References