Architecture Overview

Accepted

This is the canonical description of how Almathal is structured. Every other document in this handbook elaborates a piece of what is shown here.

The Three Layers (Plus One)

Almathal is composed of three primary layers, with a fourth conceptual layer between Components and the Composer.

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.

1. Component Library — the curated collection of individual adapters: libraries, frameworks, drivers, containers, APIs. Each one wraps an underlying open-source project (Spring Boot, React, pgvector, etc.) with a uniform contract that the rest of the system can rely on.

2. Module Library — pre-composed domain modules. Where a Component is a single library, a Module is an opinionated assembly of multiple Components delivering a complete business-domain function (Auth, Payments, Billing, RAG Core). Modules can be either platform-composed or curated from existing open-source modular projects.

3. Composer — the deterministic orchestrator. Given an Archetype Spec, it resolves Slots to Adapters and Modules, invokes the right Scaffolders with the right configuration, validates compatibility, and prepares the output for the Stitcher. No LLM tokens spent at this layer.

4. Stitcher — the bounded LLM layer. It fills Seams (explicitly declared integration points), generates the UI, customizes the last-mile differences that no archetype can fully anticipate, and produces the final artifacts. The AI Reviewer runs post-generation oversight as a supplementary signal alongside deterministic verification.

Why this shape

The retrieval-first thesis says: most software is recombination, not invention. The Component and Module Libraries make the recombination explicit and trustable. The Composer keeps composition deterministic and reproducible. The Stitcher applies LLM only where genuine novelty lives — at the seams between known-good pieces.

Why Not Just One LLM Doing Everything?

This is the question every reader asks. The short answer: cost, trust, and reliability.

Concern	Pure-LLM approach	Almathal approach
Token cost per app	High; regenerates known patterns every time	Low; LLM invoked only at seams
Provenance	None; LLM-authored code has no audit trail	Per-component; full lineage
License safety	Unverifiable; LLM may reproduce GPL/AGPL code	Verified at admission; enforced by curation
Reproducibility	Stochastic; same prompt produces different output	Versioned and locked; same Spec produces same output
Enterprise auditability	Weak; auditors cannot verify code origin	Strong; every line traces to a vetted component or a recorded seam
Improvement over time	Bounded by base model	Compounds; library grows with each release

The pure-LLM path is the right architecture for a Sunday-evening prototype. Almathal is built for the enterprise procurement reality.

Layer-by-Layer Detail

Component Library

The Component Library holds individual Adapters. Each Adapter is a Manifest-wrapped open-source library, framework, driver, container, or API. Adapters are organized into slices — language- or domain-specific groupings:

Java

Spring Boot, Spring Data JPA, Hibernate, Spring Security, Kafka, Micrometer, JHipster integrations

TypeScript / JavaScript

React, Next.js, Tailwind, shadcn/ui, TanStack Query, Zod, Vitest

Python

FastAPI, pandas, polars, pydantic, scikit-learn, Airflow, SQLAlchemy

AI / LLM

Anthropic SDK, OpenAI SDK, pgvector, Qdrant, LangChain, sentence-transformers, RAGAS

Cross-cutting Infrastructure

PostgreSQL, Valkey (Redis fork), OpenSearch (Elasticsearch fork), Kafka, MinIO, Keycloak, Prometheus, Grafana

Every Adapter has a Manifest declaring its identity, capabilities, interface contracts, compatibility, provenance, integration hints, and operational status.

Module Library

A Module is a pre-composed assembly of Adapters delivering a complete business-domain function. The Auth module, for instance, might combine Spring Security + Keycloak adapter + a database schema for users/roles + an audit-logging adapter + JWT handling.

Modules exist for two reasons:

• Reuse across archetypes. A Payment module can be used in a POS archetype, an e-commerce archetype, and a marketplace archetype. The composition is done once, validated once, and consumed many times.
• Abstraction of complexity. An Archetype that needs “auth” should not need to know which auth library is used or how it integrates. It declares a Module slot and the resolver picks the right Module.

Modules can be either:

• Platform-composed — we assemble them from raw Adapters, validate them, and admit them to the library.
• Curated from open-source — when a high-quality open-source modular project exists (e.g., Lago for billing, Ory Kratos for auth), we wrap it as a Module rather than recompose it ourselves.

Both kinds of provenance are recorded in the Module’s Manifest.

Composer

The Composer is the deterministic orchestrator. Its job:

1. Spec Resolution — Take user input through the hybrid form-plus-conversation interface and produce a fully-resolved Archetype Spec.

2. Compatibility Validation — Walk the Adapter and Module compatibility matrices to ensure the resolved combination actually works together. Block on conflicts; surface explanations through the AI Reviewer for human consumption.

3. Build Approval — Present the resolved Spec to the user as a human-readable summary. User can adjust versions, swap Adapters or Modules, accept defaults, or change variation point answers. Sign-off is recorded as part of the audit trail.

4. Seam Validation — Statically validate that every Seam declared in the Archetype is satisfiable in principle: required Adapters present, input data well-formed, output paths non-conflicting, capabilities covered. Block on broken contracts before any LLM tokens are spent.

5. Scaffolding — Invoke the configured Scaffolders (JHipster, Spring Initializr, create-t3-app, Yeoman) with the right configuration. Capture and post-process output.

6. Handoff to Stitcher — Produce a structured handoff: scaffolded code skeleton, resolved Adapter and Module list with versions, the Spec, and the list of Seams that need LLM stitching.

The Composer never calls an LLM. Every decision it makes is deterministic, reproducible, and inspectable.

Stitcher

The Stitcher is the bounded LLM layer. Its work is constrained by the Seam contracts produced by the Composer:

• Seam filling — For each Seam, generate the code that integrates Adapters and Modules according to the contract. Output paths, required Adapters to use, behaviors to implement, and verification criteria are all declared by the Seam.
• UI generation — Generate the user-facing layer (typically React components) on top of the scaffolded backend.
• Customization — Handle the last-mile differences that variations couldn’t fully anticipate, within the constraints declared by the Archetype.

Two safeguards prevent the Stitcher from drifting:

• Build Verification — Compile, lint, and run smoke tests on the generated app. Deterministic, blocking. If verification fails, the Stitcher is asked to retry with the failure as context, up to a bounded number of attempts.
• AI Reviewer (Output Review) — A separate model from the Stitcher reviews the final output for anti-patterns, security concerns, and consistency issues. Advisory only; surfaces warnings to the user but does not block.

The Curation Pipeline

The Component Library and Module Library do not stay static. The curation pipeline continuously expands and updates them:

1. Discovery — Agents scan open-source ecosystems, new releases, security disclosures, and usage patterns to propose Adapter additions, updates, and deprecations.

2. Evaluation — Automated checks: maintenance signals, security posture (CVE scan), license verification, API stability, regression impact against the existing library.

3. Ratification — Tiered: low-risk admissions (minor version bumps, well-established new Adapters in mature categories) can be agent-ratified; high-risk admissions (security-critical, new categories, breaking changes) require Human Reviewer approval.

4. Release — Admitted changes accumulate into the next versioned release of the platform. Generated apps record the exact platform version used. Customers upgrade on their schedule.

This is detailed further in Governance: Curation Pipeline.

What Almathal Is Not

Equally important. Almathal deliberately does not:

• Compete with Cursor, Lovable, v0, or other LLM-first code generators on raw prompt-to-app generation. The target user is enterprise, not a developer on a Sunday evening.
• Generate code from scratch when a working implementation exists in the curated library.
• Trust LLM-authored code at the Adapter level. LLMs assist in composing, stitching, summarizing, and reviewing. They do not author Adapters that ship without human or agent ratification.
• Mutate under the user. Releases are versioned; customers upgrade deliberately.
• Optimize for general-population developers as the primary buyer. That market may be served eventually, but it is not the MVP.

Related Documents

• Runtime Pipeline — stage-by-stage flow of a generation
• Naming Conventions — the canonical names for every concept
• ID Scheme — slugs, UUIDs, and how identifiers work across the system
• Glossary — formal definition of every term
• Decision: Three-Layer Design — the ADR that established this architecture