What happens when your migration source has 163 paragraph types — some containing entire pages of mixed HTML in a single field — and your destination architecture has 42 typed paragraph bundles? It's a fascinating transformation problem that invites you to rethink how migrations can work.

Instead of the traditional one-to-one mapping approach, we explored a different path: first, deeply understand your source data with AI-assisted analysis. Then, decompose monolithic content into typed fragments. Finally, derive and assemble the destination content from multiple source streams.

We applied this approach to a large website migration from Drupal 10 to Drupal 11, making AI a first-class participant in the process — not for code generation, but for source data analysis at scale. An AI agent with 12 atomic skills (database discovery, orphan detection, field population measurement, cross-reference tracing) turned source analysis into a repeatable, on-demand capability that the entire team could leverage from the very first sprint.

Join us to explore this end-to-end approach — analyse, decompose, implement, assemble — and discover how rethinking the migration process can open up new possibilities for your own projects.

Prerequisite

Basic understanding of Drupal's Migrate API (source, process, destination plugins)

Familiarity with paragraph-based content architectures

General awareness of what AI agents and LLM-based tools can do (no deep AI expertise needed)

Target Audience

Drupal developers, architects, and technical leads involved in content migrations

Outline

Let’s be honest: content migrations are one of the most fascinating challenges in Drupal. You’re reverse-engineering years of content architecture, understanding how a site evolved, and designing a pipeline to reshape everything into a new structure.

Our challenge: a Drupal 10 site with 163 paragraph types — many acting as rich HTML containers mixing headings, images, documents, and embeds — to be transformed into 42 clean, typed bundles in Drupal 11. A 4:1 compression that raised a key question: what if, instead of mapping content one-to-one, we decompose it into atomic fragments and reassemble it into something new?

First, we needed visibility. Analysing 163 paragraph types, tracing references, and measuring field usage across thousands of items is complex. So we built an AI agent with 12 atomic skills to query the source database, analyse bundles on demand, detect orphans, verify usage, and generate structured issues — turning weeks of exploration into repeatable analysis.

Then came the engineering: a system to split HTML into typed fragments via DOM traversal, a deriver pipeline to fan out migrations, and a content assembler to rebuild paragraph fields by probing multiple migration maps with fallback logic.

This is a different approach to complex migrations — combining AI-assisted analysis with creative engineering from day one.

Learning Objectives

Learn how to build a reusable AI agent with atomic skills for systematic migration source analysis — including orphan detection, field population measurement, and cross-reference tracing.

Understand the fragment decomposition pattern: how to split monolithic HTML content into typed, discrete paragraph entities using DOM traversal and deterministic UUIDs.

Master the deriver/assembler architecture for N-to-M paragraph type mapping — including fan-out derivation, multi-map probing, and cross-parent fallback assembly.

Experience level
Intermediate