Almathal Handbook

What is Almathal?

Almathal is an enterprise software composition platform. It assembles complete, working applications by retrieving and composing vetted building blocks rather than generating code from scratch.

The core thesis is simple: most software is recombination, not invention. Almathal makes that explicit. A curated library of trusted components and pre-composed domain modules is combined by a deterministic orchestrator, with a bounded LLM layer handling integration seams, UI generation, and the genuinely novel parts of each app.

The result is enterprise-grade applications produced at a fraction of the token cost of pure-LLM tools, with full provenance, audit trails, and license traceability for every component shipped.

The Almathal three-layer architecture. Component Library and Module Library are curated and trusted. Composer orchestrates deterministically. Stitcher applies bounded LLM work at integration seams.

The Name

ال‍مثالthe canonical example

Almathal is Arabic for the example or the canonical pattern. The name embeds the thesis: every component, module, and archetype in the library is a vetted, exemplary pattern. Generated applications are compositions of canonical examples, not improvisations.

How Almathal Differs

Retrieval beats regeneration

When a working implementation exists, Almathal composes it. The LLM is invoked only where genuine novelty or judgment is required — not to rewrite what already works.

Determinism dominates

Every decision that can be made deterministically is. The LLM is bounded to integration seams and UI generation, surrounded by deterministic compatibility checks, contract validation, and verification.

Provenance is first-class

Every component shipped in a generated app has a recorded source, license, SBOM fragment, and admission history. License-clean, audit-ready, enterprise-defensible by construction.

Versioned, not mutating

Releases are semver’d. Customers upgrade on their schedule. Every generated app records the exact platform, archetype, adapter, and scaffolder versions that produced it.

Where to Start

New to Almathal?

Start with the Glossary to lock in the vocabulary, then read the Architecture Overview.

Need to understand a decision?

The Decisions log records every architectural decision and its rationale.

Working on schemas?

The Schemas section holds the formal contracts that connect every layer.

Curating components?

The Governance section explains how adapters and modules are admitted, reviewed, and versioned.

Status

This handbook is the architectural and design record produced during the design phase. Implementation begins after the architecture, schemas, and decision log are complete and reviewed.

Every document declares its state in the header: Draft, Accepted, or Superseded.

Audience

This handbook is for internal use:

• Platform engineers building Almathal itself
• Curators (human and agent) maintaining the Component Library and Module Library
• Architects evolving the schemas and patterns
• Future contributors who need to understand why the system is shaped the way it is

End-user documentation for engineers using Almathal to generate applications will be a separate body of work, not contained here.