Skip to slides
▲ ▼ arrow keys
MA
Magento Association
Developer Documentation Project

Developer Docs
Infrastructure

A three-project pipeline — parser, generation engine, and HTML builder — producing structured developer docs for Magento's 344 core modules.

344 core modules
9 doc types each
3,096 total documents
TypeScript LangChain Qdrant Handlebars Tailwind CSS Alpine.js
Presenter
Carl Simpson
Date
March 2026
Evolution

How We Built It

From merchant RAG foundation to full developer documentation pipeline.

Stage 1 David Lambauer
merchant-mastra
TypeScript RAG pipeline for merchant documentation — store owner guides, getting-started content, structured Markdown output.
Stage 2 Carl Simpson
html-docs-transformer
Raw Markdown → production HTML. 7 semantic transformations: callout boxes, step cards, breadcrumb chips, auto-TOC. Bauhaus design system.
Stage 3 Carl Simpson
developer-mastra
Developer-focused RAG engine. 5-source retrieval, Handlebars templates, 3-agent review loop (9.5/10 quality gate). HTML transformer integrated into pipeline.
Stage 4 Current
the-core + Learning Paths
Source-level parser mapping every plugin, observer, and dependency across 344 modules. RAG grounded in real source data. Divio learning paths + certifications planned.
developer-mastra

The Engine: How It Works

Generation Pipeline
1. the-core parses all XML → module graphs
2. Module Scanner discovers 344 modules + API surface
3. Gap Analysis diffs existing docs vs taxonomy
4. RAG retrieves from 5 sources (see right →)
5. LLM + Handlebars template → Markdown
6. 3-Agent Review Loop → 9.5/10 quality gate
7. html-docs-transformer → production HTML
5-Source RAG Retrieval
▶ Qdrant vector store (semantic similarity)
▶ Local docs from the-core (keyword match)
▶ Magento source code (di.xml, Api/, Model/)
▶ Module dependency graphs (JSON)
▶ External Magento docs (Context7 MCP)
Ranked, deduplicated, diversity-bonused
3-Agent Review Loop
REVIEWER Scores: accuracy, completeness, clarity, value, structure
QUALIFIER Filters vague or incorrect feedback
UPDATER Applies revisions, rollback on regression
9.5
Quality Gate
Source-code-grounded. No hallucination — the LLM sees actual XML configs.
Output Architecture

9 Doc Types + HTML Transformer

Per-Module Documentation Set
01 README & Overview
02 Architecture — schema, contracts, deps
03 Execution Flows — operation sequences
04 Plugins & Observers
05 Integrations — cross-module APIs
06 Anti-Patterns — mistakes + fixes
07 Known Issues & Workarounds
08 Version Compatibility
09 Performance Optimisation
html-docs-transformer
Markdown → Production HTML
Raw Markdown → styled, accessible HTML
▶ Callout boxes (Note, Tip, Warning, Caution)
▶ Numbered step cards with visual badges
▶ UI path breadcrumbs (System > Tools > Cache)
▶ Auto-generated table of contents
▶ Syntax-highlighted code blocks
▶ Idempotent — safe to run multiple times
Design System
Bauhaus principles, Magento palette, WCAG AA, zero build. TailwindCSS CDN + Alpine.js.
Before
After
Learning Paths + Output

What's Live Today

Module Reference Docs (the-core)
10 Core Modules
Catalog, Sales, Customer, Checkout, Quote, Payment, Shipping, Store, EAV, ConfigurableProduct
90
Module Docs
4,860+
Components
160+
Total Docs
Developer Guides
6 Tutorials • 11 How-Tos • 21 Advanced
GraphQL, B2B, Indexers, Service Contracts, and more
Divio Documentation Framework
Four content types for different developer needs:
TUTORIAL Step-by-step, hands-on exercises
HOW-TO Solve a specific problem quickly
EXPLAIN Why things work the way they do
REFERENCE API specs, CLI commands, config options
5 Learning Paths
Beginner → Module fundamentals
Intermediate → Plugins, observers, DI
Advanced → Service contracts, GraphQL
Expert → B2B, multi-store, ERP
Enterprise → Architecture, scaling
carlsimpson.co.uk/magento-association/
Roadmap

Scaling to 90 Priority Modules

13 phases · 90 priority modules · 9 doc types each · We need your expertise.

Delivery Phases (13 total)
Phase 1
Pipeline + 9 Core Modules
Parsers, templates, design system — 10 modules live
Phase 2
Content Analysis + Taxonomy
Gap mapping + priority ranking
Phase 3–4
Tooling + Specialist Agents
PHP introspection + domain-specific agents
Phase 5–8
Commerce Modules
Inventory, Tax, CMS, Search, Wishlist, Review, Bundle, Downloadable...
Phase 9–13
Full Coverage + QA
Admin, API, integration modules. 90 modules total.
Progress 10 / 90 modules (11%)
How You Can Help
Review docs for modules you know
Share anti-patterns, gotchas, integration knowledge
Prioritise which modules matter most to you
Adopt into the official Magento Association docs
Get In Touch
NAME Carl Simpson
The Magento community built the platform.
Let's document it — together.