Skip to content
Almathal Handbook

Archetype

Accepted

An Archetype is a reusable template for a complete application type — RAG chatbot, internal CRUD admin tool, point-of-sale system, document processing pipeline. Each Archetype defines everything needed to generate one specific kind of application.

Archetypes are the unit of capability Almathal offers. When we say “Almathal can build X,” what we mean is: an Archetype for X exists in the library.

What an Archetype Defines

An Archetype is defined by an Archetype Spec schema document. The Archetype declares:

  • Which Scaffolders to invoke (JHipster, Spring Initializr, create-t3-app, Yeoman, others)
  • Which Adapter and Module Slots must be filled, with defaults and constraints
  • Which Variation Points the user can configure
  • Which Seams the Stitcher must fill, with full contracts
  • Which sanity checks to run at each pipeline stage
  • Which verification criteria define successful output

The Three Layers of Composition

Almathal’s composition story spans three layers:

Archetype       — what to build (POS system)
   │
   ├── Modules        — opinionated assemblies (Auth, Payments, Inventory)
   │      │
   │      └── Adapters — raw libraries (Spring Security, Stripe SDK, ...)
   │
   └── Scaffolders   — code skeleton generators (JHipster, create-t3-app)

An Archetype names what should be built. Modules deliver business-domain pieces. Adapters provide the raw libraries. Scaffolders produce the project skeleton. The Composer wires them all together.

Archetype Examples

RAG Chatbot (MVP Archetype #1)

  • Scaffolders: create-t3-app (frontend), FastAPI scaffolder (Python backend)
  • Modules: RAG Core, Document Ingestion, Vector Storage, Chat UI
  • Adapter Slots: LLM provider (Anthropic SDK default), vector DB (pgvector default), embedding model (default-tier)
  • Variation Points: corpus type, chunk strategy, model selection
  • Seams: prompt engineering for the chatbot persona, citation rendering UI, custom retrieval filtering

Internal CRUD Admin Tool (MVP Archetype #2)

  • Scaffolders: JHipster (Java + React together)
  • Modules: Auth (JWT + RBAC), Audit Logging, User Management
  • Adapter Slots: database (PostgreSQL default), backend framework (Spring Boot), frontend (React + shadcn/ui)
  • Variation Points: entity definitions, role hierarchy, list view fields
  • Seams: entity-to-UI mapping, custom validation rules, optional workflow approvals

Variation Points

A Variation Point is a user-configurable choice. Variation Points are typed (enum, user-defined list, string, etc.) and constrained (defaults, validation rules, UI hints). The hybrid form-plus-conversation input model renders Variation Points as form fields with conversational refinement for the parts that don’t fit a form.

Example Variation Points in a CRUD admin Archetype:

  • database — enum, options [postgresql, mysql], default postgresql
  • entities — user-defined list of entity definitions, minimum 1
  • auth_provider — enum, options [jwt, keycloak, auth0], default jwt

The Spec captures the user’s answers. The Composer uses them to drive Scaffolder configuration and Slot resolution.

Seams

Seams are the mechanism by which Archetypes constrain the Stitcher. Each Seam declares:

  • Input — the data feeding into this Seam (typically a Variation Point’s value)
  • Output files — exact path templates the Seam must produce
  • Required Adapters — Adapters whose Capabilities must be used
  • Behaviors — what the generated code must implement
  • Verification — how the platform will confirm the Seam was filled correctly

Without Seams, the Stitcher would have to discover where to write code. With Seams, it has explicit job descriptions per output file, and the Composer can pre-validate the contracts before any LLM is invoked.

See Concepts → Seam for the deeper treatment.

Archetype Lifecycle

Archetypes have the same lifecycle states as Adapters and Modules:

  • Experimental — newly drafted, limited use, may change significantly
  • Active — production-ready
  • Deprecated — discouraged for new builds
  • Superseded — replaced by a named successor
  • Archived — no longer available for new builds

An Archetype’s version follows semver. Patch and minor changes preserve backward compatibility for previously-generated apps; major changes do not.

Archetype Versioning Implications

Every generated app records the exact Archetype version that produced it. When the customer wants to regenerate or extend, the platform uses the recorded Archetype version (and matching Adapter/Module versions) unless explicitly upgraded.

This is the same lockfile principle that Cargo, npm, and Poetry apply to dependencies, extended to the application template itself.

The Fallback Path

When a user’s request doesn’t match any Archetype, Almathal falls back to pure-LLM generation, with the user warned that the output won’t carry the trust guarantees archetype-matched generations do. The request is logged for analysis: if the same kind of unmatched request keeps appearing, that’s a signal to create a new Archetype.

This is documented in detail in the Curation Pipeline.

Reusable Templates

A user can save an approved Spec as a reusable template — useful for enterprises generating multiple similar apps with the same configuration. The template captures the user’s Variation Point answers and Slot selections; the underlying Archetype is referenced by version.