At heydru!, we took a different approach. We sponsor drupal-ai — an open-source system built to make AI a reliable, deterministic part of enterprise Drupal engineering. Not a shortcut. Infrastructure.

What drupal-ai actually is​

drupal-ai is not a plugin, a chatbot, or a code generator you run once and forget. It's an engineering system built specifically for professional Drupal teams: production-ready, opinionated, and designed for scale.

The system has four core components:

Skills — 30+ reusable modules encoding domain knowledge about Drupal: how to structure a migration, how to write a proper service, how to handle entity API patterns correctly. Skills give the AI a foundation in Drupal-specific knowledge rather than relying on generic training data.

Agents — 9 specialized task-specific agents for concrete development scenarios: PR reviews, module generation, debugging, migrations, architecture scoping. Each agent knows its context and its constraints.

Rules — 8 enforced rule files that define how code should be written — coding standards, architectural patterns, naming conventions. These are constraints, not suggestions. The AI can't ignore them.

Workflow hooks — Automated integrations with the Drupal development stack: DDEV, Drush, PHPCS, Drupal's own tooling. AI fits into the existing workflow rather than replacing it.

The result: AI that produces code you can actually merge. Not code that looks plausible, but code that follows your team's standards, fits your architecture, and behaves correctly at runtime.

Why we sponsor it​

We sponsor drupal-ai because it solves a problem we lived with for years: AI tooling that's powerful in theory but inconsistent in practice.

The inconsistency problem in Drupal is especially acute. Drupal has deep, layered APIs — the entity system, the plugin system, the cache system, configuration management. Generic AI models have reasonable Drupal knowledge but fail on specifics: deprecated APIs in D11, subtle differences between entity query methods, the correct way to structure a custom migration. The output looks right until it doesn't.

drupal-ai encodes the correct patterns. It codifies 14+ years of Drupal expertise into a system that can be run, tested, and improved. When we use it internally, we're not hoping the AI knows Drupal — we're giving it a structured map of how we build Drupal.

That changes the risk profile entirely. It's the difference between using AI as a convenience and using AI as infrastructure.

What changes for enterprise teams​

For teams operating at scale — large codebases, strict standards, multiple developers — drupal-ai closes the gap between AI's potential and its real-world reliability.

Onboarding accelerates. A new developer with drupal-ai has access to the team's accumulated knowledge from day one. Skills encode what would otherwise take months of code review and mentorship to absorb.

Code review focuses on architecture. When AI output already conforms to your standards and patterns, reviewers stop spending cycles on style and boilerplate. Reviews become substantive.

Migrations become more systematic. The migration agent has specific knowledge of Drupal's Migrate API — source plugins, process plugins, migration dependencies. It doesn't just generate code that looks like a migration; it generates code that follows the patterns that actually work.

Knowledge stops being siloed. On most Drupal teams, expertise lives in individual developers' heads. When they leave, it leaves. drupal-ai makes expertise a shared, version-controlled asset.

This is how heydru! delivers​

When clients work with us, they're not just getting engineers who know Drupal. They're getting a team that has systematized Drupal expertise into infrastructure that makes every engagement more consistent and every delivery more predictable.

drupal-ai is the tooling that makes that possible at a level of rigor that generic AI assistance can't match. We built it, we use it on every project, and we continue to develop it.

If you're running a serious Drupal platform and want to work with the team operating at this level, let's find out if we're a fit.

drupal-ai is open source and actively maintained. Explore the full system at eduardotelaya.com/drupal-ai.

Here's how we think about scalable Drupal backend design.

Start with the access patterns, not the content types​

The most common architecture mistake is starting with content modeling and figuring out delivery later. The right order is the reverse: understand how the content will be consumed, then model around that.

Questions that should be answered before creating the first content type:

• Who are the consumers? Editorial team only, external APIs, a decoupled frontend, third-party integrations?
• What are the read vs. write ratios? A site that publishes 10 times a day and serves 10 million page views needs a very different cache strategy than one publishing 1,000 times a day to 10,000 users.
• What are the latency requirements? Sub-100ms for public pages? Real-time for editorial previews?
• Is content relationship complexity high? Deeply nested entity references kill performance in ways that are hard to fix after the fact.

The answers to these questions shape almost every subsequent architectural decision.

Decoupled vs. traditional: making the right call​

Decoupled Drupal (Drupal as a headless CMS with a separate frontend) is not inherently better than traditional Drupal. It's a tradeoff, and the wrong call in either direction creates problems.

Traditional Drupal is the right choice when:

• The team has strong Drupal frontend expertise (Twig, theme layer)
• SEO and time-to-first-byte are critical and you want the simplest possible stack
• The editorial team needs in-context preview and layout tools (Layout Builder, etc.)
• The integration surface is primarily between Drupal and a few internal systems

Decoupled is the right choice when:

• The frontend is genuinely complex and requires a modern JavaScript framework
• Multiple consumers need the same content (web, mobile app, third-party systems)
• The frontend team is stronger in React/Vue/Next than in Twig
• Content delivery needs to be independent of Drupal's publishing pipeline

The mistake we see most often is organizations going decoupled because it sounds modern, without a frontend team capable of owning the frontend platform. The result is two systems to maintain and none of the benefits.

Content modeling that scales​

A few principles that consistently improve long-term maintainability:

Model for the editor, not just the output. Fields that make sense as a data structure aren't always fields that make sense to an editorial team. If editors are regularly misusing a field — putting body content in a summary field, for example — that's a modeling failure.

Avoid deeply nested entity references. A node referencing a paragraph referencing a media entity referencing a file sounds fine on paper. At 50,000 nodes with complex views, it becomes a join nightmare. Flatten where you can. Use denormalized data structures when read performance matters more than write simplicity.

Use configuration management from day one. All content types, fields, views, and display modes should live in version-controlled YAML. A content type that was created by clicking in the UI and never exported is a liability — it can't be deployed reproducibly, and it can't be code-reviewed.

Plan for multilingual from the start. Adding multilingual support to a site that wasn't designed for it is expensive. Even if you're launching in one language, if there's any chance of adding more, build the translation infrastructure in from the beginning.

Caching architecture​

Caching is where Drupal backend architecture either pays off or falls apart under load.

The caching layers we work with, from outside in:

1. CDN (CloudFront, Fastly, etc.) — Handles the majority of anonymous traffic. Drupal's cache tags enable precise invalidation: when a node is updated, only the CDN cache entries that contain that node are purged, not the entire cache. The purge module ecosystem handles this well.

2. Reverse proxy (Varnish) — Useful for infrastructure setups where a CDN isn't in place, or as an additional layer. Drupal generates Surrogate-Control headers that Varnish respects.

3. Drupal's internal page cache — Serves fully cached pages for anonymous users without bootstrapping the full Drupal stack. Critical for high-traffic public sites.

4. Drupal's dynamic page cache — Caches pages for authenticated users with user-specific elements excluded via cache contexts. Often overlooked, but significant for sites with logged-in users.

5. Render cache — Individual render elements are cached based on cache tags, contexts, and max-age. Deep understanding of the render cache is the difference between a Drupal site that scales and one that doesn't.

The critical concept throughout is cache tags. Every entity in Drupal has tags. When that entity is updated, all cache entries tagged with it are invalidated automatically. Lean into this system rather than fighting it.

API design​

For sites exposing content via API — whether to a decoupled frontend or external consumers — JSON:API (built into Drupal core) covers most use cases well. It handles filtering, sorting, includes, sparse fieldsets, and pagination out of the box.

Custom REST endpoints are appropriate when:

• The response shape needs to differ significantly from Drupal's entity structure
• You need to aggregate data from multiple entity types into a single response
• Performance requirements make the overhead of JSON:API's generic approach unacceptable

When building custom endpoints, keep them thin. Business logic should live in services, not in controllers or plugins. This makes the API layer testable and replaceable.

Database patterns​

A few things that consistently show up as performance bottlenecks:

Views with no exposed indexes. Drupal's Views module generates SQL queries that can be devastating on large datasets if the underlying fields aren't indexed. Always check the query being generated for complex views. Add database indexes where needed — Views doesn't do this automatically.

Entity queries that load full entities unnecessarily. \Drupal::entityTypeManager()->getStorage('node')->loadMultiple($ids) loads complete entities. If you only need a field value, use an entity query to get IDs and then query the field table directly. The difference at scale is significant.

Missing composite indexes on custom tables. If you're writing custom tables (for logging, for external data sync, for anything), design the indexes around the queries you'll run, not around the data you're storing.

A note on infrastructure​

Good Drupal backend architecture is only as good as the infrastructure running it. A few things that matter more than teams typically realize:

• PHP-FPM tuning — The default pm.max_children value is almost never right for production. Profile under realistic load.
• OPcache — Should be enabled and sized appropriately. A warm OPcache makes a meaningful difference in response times.
• Database read replicas — For read-heavy sites, routing read queries to replicas reduces load on the primary significantly. Drupal's database abstraction layer supports this natively.

The compounding effect​

Architecture decisions compound. A good content model makes migrations easier. A clean caching strategy makes infrastructure simpler. Proper use of configuration management makes deployments safer. These things build on each other, and the gap between a well-architected Drupal platform and a poorly-architected one grows with time.

The investment in getting architecture right at the start is almost always returned in reduced maintenance cost within the first year.

Here's how we approach D7 → D11 migrations at heydru: treating them as parallel systems, not upgrades.

Why this isn't an upgrade​

The instinct is to treat a major version jump as an upgrade — export the database, run some scripts, fix the errors. That works between minor Drupal versions. It does not work between Drupal 7 and Drupal 11.

The underlying architecture is fundamentally different. Drupal 7 uses a hook-based system with procedural PHP. Drupal 8 introduced an object-oriented kernel built on Symfony components, and that foundation has carried through to D11. The content structure, the routing system, the configuration management, the theming layer — all of it changed.

When we take on a D7 migration, the first thing we tell the client is: you are rebuilding your platform, not upgrading it. That reframe matters because it changes how you plan, how you staff, and how you manage risk.

The parallel-run strategy​

The safest migration approach we've found is running D7 and D11 in parallel until D11 is ready to take over fully.

Phase 1 — Audit and content modeling

Before writing a single line of new code, we do a complete audit of the D7 site: every content type, every field, every view, every module, every integration. We document what's actually being used versus what was installed and forgotten. Legacy Drupal sites routinely have 80+ contributed modules enabled, and in practice 30% of them are doing nothing useful.

This audit becomes the migration spec. We don't migrate everything — we migrate what matters. That distinction alone has saved clients weeks of work.

Phase 2 — Build D11 in isolation

We stand up the D11 platform in a separate environment, completely decoupled from D7. Same database server, different database. We rebuild content types in D11 using configuration management from the start — no clicking in the UI, everything in YAML. This means the D11 build is fully reproducible from day one.

Custom module code gets rewritten as Drupal 8+ plugins and services. There's no shortcut here, but the new code is substantially cleaner and more testable than most D7 module code.

Phase 3 — Content migration with Drupal's Migrate API

The Migrate API, stable since Drupal 8.1, is the right tool for this. It provides a structured pipeline: source plugins read data from D7, process plugins transform it, destination plugins write it to D11.

// Example: simple node migration source
source:
  plugin: d7_node
  node_type: article
process:
  title: title
  body: body/0/value
  field_category:
    plugin: migration_lookup
    migration: d7_taxonomy_term_tags
    source: field_tags
destination:
  plugin: entity:node
  default_bundle: article

We run migrations iteratively, not once. The first run will expose field mapping issues, missing taxonomies, broken file references. We fix those, wipe the D11 content tables, and run again. By the fifth or sixth iteration the migration runs cleanly in under an hour for most sites.

Phase 4 — Continuous sync

This is the part most teams skip, and it's the most important one. Once D11 content is in good shape, we set up a sync job that runs the migration daily. Every new node, every content update, every taxonomy change in D7 gets migrated to D11 automatically.

This keeps D11 current. It means the cutover isn't a one-time data dump — it's just turning off the sync and flipping DNS.

Phase 5 — The cutover

When D11 has been running in parallel for long enough that the team is confident in it, the cutover is straightforward:

1. Put D7 in maintenance mode
2. Run a final full migration to catch any content updated since the last sync
3. Update DNS to point to D11
4. Monitor for 48 hours
5. Keep D7 accessible internally for one month as a fallback

Total downtime: the time it takes to flip DNS — minutes, not hours, not days.

Common failure modes​

Trying to do it all at once. Teams that try to migrate content, rebuild features, upgrade infrastructure, and launch all in one go almost always blow past their timeline. Phase it.

Underestimating custom module rewrites. A 500-line D7 module doesn't become a 500-line D11 module. The concepts are different. Budget more time than you think you need.

Skipping the audit. The client thinks they know what their site does. They are never fully right. The audit always surfaces something — usually a niche feature that two people use and three people have forgotten exists, with no documentation.

Not running migrations repeatedly. Running the migration once early and not touching it again means you'll hit a wall of data issues during the real cutover. Run it weekly at minimum throughout the project.

What a realistic timeline looks like​

For a mid-size Drupal 7 site (15–30 content types, 50,000–200,000 nodes, 5–10 custom modules), we typically budget:

• Audit and scoping: 2–3 weeks
• D11 build: 8–16 weeks (varies heavily by custom functionality)
• Migration pipeline development and iteration: 4–6 weeks, running in parallel with build
• User acceptance testing: 3–4 weeks
• Cutover and stabilization: 1–2 weeks

Total: 4–6 months for a well-scoped project. Teams that rush this to 2–3 months usually end up doing a second migration a year later.

The upside​

D11 is meaningfully better than D7 in ways that aren't obvious until you're in it. Configuration management makes deployments predictable. The service container makes testing realistic. JSON:API and GraphQL come standard. The performance baseline is higher.

The migration is real work. But the platform you end up with is substantially more maintainable, more secure, and more capable than what you're leaving behind.

If you're still on D7 and trying to figure out where to start, the answer is the audit. Everything else follows from there.