Naming Conventions

Accepted

This document is the canonical authority for naming. Every other document in the handbook conforms to it. Changes to canonical names require an ADR.

Principles

1. Names describe function, not implementation. “Composer” says what it does, not how it does it.
2. No redundant prefixes. We do not call everything “AlmathalSomething” — the context is implicit.
3. Qualifiers added only when ambiguity exists. “AI Reviewer” and “Human Reviewer” because both kinds exist; just “Stitcher” because there is no human counterpart.
4. Capitalization is for canonical terms. When referring to a defined platform concept in documentation, the term is capitalized (the Composer, an Adapter). When using the same word in its ordinary English sense, it is lowercase.
5. Plurals are ordinary. Adapters, Modules, Archetypes. No invented plural forms.

Layers and Major Components

Term	Refers To
Component Library	The curated collection of Adapters
Module Library	The curated collection of Modules
Composer	The deterministic orchestrator
Stitcher	The LLM layer that fills Seams and generates UI
AI Reviewer	The LLM that performs Output Review
Human Reviewer	A platform team member performing curation ratification
Curation Pipeline	The agent-and-human process for evolving the Libraries

Pipeline Stages

In order of execution:

1. Spec Resolution
2. Compatibility Validation
3. Build Approval
4. Seam Validation
5. Scaffolding
6. Stitching
7. Build Verification
8. Output Review

Each stage has a corresponding doer. Where the doer’s name might be ambiguous, the doer is qualified: Resolver (does Spec Resolution), Compatibility Validator, Build Validator (encompasses lint/compile/test), and so on.

Core Concepts

The vocabulary of composition itself:

Term	Refers To
Adapter	A single Component Library entry
Module	A single Module Library entry
Archetype	A reusable application template
Slot	A position in an Archetype that holds an Adapter or Module
Capability	A declared feature an Adapter or Module provides
Contract	The abstract interface Adapters/Modules with the same role share
Seam	An integration point filled by the Stitcher
Manifest	The JSON descriptor for an Adapter or Module
Spec	The resolved Archetype configuration for one build

Subcomponents Within the Composer

Term	Refers To
Resolver	Performs Spec Resolution
Compatibility Validator	Performs Compatibility Validation
Seam Validator	Performs Seam Validation
Scaffolder Runner	Invokes external Scaffolders
Build Validator	Performs Build Verification (compile, lint, test, contract checks)
Briefing Generator	Produces the human-readable Build Brief for Build Approval

External Tools

Term	Refers To
Scaffolder	An external code-generation tool the Composer orchestrates

Examples (always referred to by their existing project names, not Almathal-coined names): JHipster, Spring Initializr, create-t3-app, Yeoman.

What We Do Not Call Things

To prevent drift, the following names are explicitly not used:

• “Generator” — too generic; we have specific things (Composer, Stitcher, Scaffolders) that do generation.
• “Engine” — overused in tech; not specific.
• “AI” as a standalone noun (“the AI did X”) — always specify which LLM-driven role: Stitcher, AI Reviewer.
• “Plugin” — Adapters are not plugins. They are curated library wrappers.
• “Service” for layers of the platform — services run at runtime in generated apps. Almathal’s internal pieces are Composer, Stitcher, etc.
• “Pipeline” for the whole platform — Pipeline refers specifically to the Pipeline Stages a generation moves through, not to the platform itself.
• “Template” — Templates exist in scaffolders, but Almathal’s reusable application definitions are Archetypes, not “templates.”
• “Recipe” — sometimes tempting metaphorically; not used canonically.

Casing in Code and Files

• JSON keys and YAML keys: snake_case (e.g., adapter_slots, interface_contract)
• Type identifiers in code: PascalCase (e.g., AdapterManifest, ArchetypeSpec)
• File names: kebab-case (e.g., adapter-manifest-v1.mdx, 0007-central-manifest-registry.mdx)
• Slugs in IDs: kebab-case within namespace segments (e.g., adapter:java/spring-data-jpa)
• Capability and Contract IDs: namespace/name/v<N> (e.g., capability:persistence/transactions/v1)

Versioning Style

• Adapters: semver matching the underlying library version (e.g., spring-data-jpa@3.2.4)
• Modules: semver managed by the platform (e.g., module:auth/jwt-with-rbac@1.2.0)
• Archetypes: semver managed by the platform (e.g., archetype:rag-chatbot@0.1.0)
• Capabilities and Contracts: integer version only (v1, v2) — interfaces evolve in major versions only
• Manifest schema and Archetype Spec schema: integer version (v1, v2)
• Platform itself: semver

Cross-Reference

For formal definitions of every term, see the Glossary. For the immutable-vs-mutable identifier model, see the ID Scheme.