The Architecture That Changed the Game: Modeler API

For years, we heard the same question at conferences, in issue queues, on Slack: "Can we use BPMN for Migrations? Can we use it for AI workflows? Can we use it for Commerce checkout orchestration?"

The answer was always no. ECA started with the right intent - blackbox core, separate UIs, two modelers from day one. But intent isn't architecture. The decoupling was incomplete. Model owners and modelers still knew too much about each other.

Adding a new model owner meant rewriting integration code. Adding a new modeler meant updating every model owner.

This is the story of how we completed that architectural separation - and why it matters far beyond ECA.

This is post 2 of 9 in the ECA: The Next Chapter series. Post 1 told the story of the ten-month journey from Dries' feedback to the Athens keynote. This post dives into the Modeler API architecture that made the new capabilities possible.

The Question That Wouldn't Go Away

If you've been following ECA's evolution, you've seen the visual modeler in action. Drag events, conditions, and actions onto a canvas. Draw connections. Save. Your automation runs.

But what if you wanted to model something else? Migration workflows. AI agent task chains. Commerce checkout steps. Content publishing pipelines. These all share the same need: represent complex, interconnected logic visually.

The pattern is everywhere. Yet each time someone asked "Can we use your modeler for X?", we had to say no.

Why?

The incomplete decoupling. Yes, ECA shipped with two modelers from the beginning - the intent was there. But the separation wasn't clean. Model owners and modelers were still coupled at integration points: routing, permissions, UI rendering, save operations, import/export. To add a new model owner (like Migrate), we'd need to fork the modeler or write thousands of lines of glue code.

That's not sustainable. That's not what Drupal's plugin architecture teaches us. We had the right intent from day one. What we needed was the right abstraction.

The Insight: Separation of Concerns

The breakthrough came from stepping back and asking: what are we actually modeling?

Not "ECA models". Not "BPMN diagrams". We're modeling structured, visual representations of logic that some system will execute.

That insight led to the separation:

• Model Owner: The system that executes the logic (ECA, Migrate, AI agents, Commerce)
• Modeler: The UI that lets users build and edit the visual representation (BPMN.iO, Workflow Modeler, future tools)

These two concerns are independent. A model owner doesn't care which modeler created its model. A modeler doesn't care what system will execute the model.

They just need a contract between them - an API.

The Architecture

The Modeler API sits between model owners and modelers, providing:

For Model Owners (via plugin interface):

• Model storage schema definition
• Permission logic
• Route definitions
• UI integration hooks
• Import/export handling
• Template management
• Testing and replay infrastructure

For Modelers (via plugin interface):

• Standard model structure
• Rendering hooks
• Event triggers
• State management
• Validation rules

What the API handles automatically:

• Dynamic route generation (/admin/config/workflow/eca/[model-id]/edit, /admin/structure/migrations/[model-id]/edit)
• Permission checking (delegates to model owner logic)
• UI chrome (tabs, breadcrumbs, local tasks)
• Save orchestration (normalizes data, calls model owner save)
• Import/export coordination
• Template discovery and application
• Testing harness
• Drush command generation

Neither side needs to know the other exists. The API translates.

The Impact: One "Yes" Becomes Many

Here's what changed the moment we completed the Modeler API in February 2025:

Before: "Can we use the modeler for X?" → No, incomplete decoupling.

After: "Can we use the modeler for X?" → Yes. Implement the Model Owner plugin interface. Enable your module. Done.

Suddenly, one modeler could serve multiple model owners. One model owner could work with multiple modelers. The math is simple:

• 4 model owners (ECA, Migrate, AI agents, Commerce) × 3 modelers (BPMN.iO, Workflow Modeler, future tools) = 12 combinations
• Zero glue code required
• Each combination works automatically through the API

This is the compounding effect of good architecture.

Benefits Beyond the Obvious

The immediate benefits are clear:

• Visual configuration for any complex Drupal system
• No reinventing the modeler wheel
• Model portability between modelers
• Shared infrastructure (testing, templates, replay)

But the deeper benefits reveal themselves over time:

For End Users:
You'll see more tools that "speak the same language". Learn one visual modeler, use it across multiple Drupal systems. Your investment in understanding visual workflows pays dividends everywhere.

For Drupal:
We now have architecture for visual configuration of complex systems. This isn't specific to ECA. It's infrastructure. WordPress doesn't have this. Joomla doesn't have this. Most CMSs have fragmented admin UIs for complex configuration. Drupal has a pattern.

For Module Maintainers:
Stop building custom admin UIs for complex module configuration. Use the Modeler API. Let users configure your module visually. You focus on domain logic; the API handles routing, permissions, UI, save operations, import/export, testing.

For the AI Era:
The same architecture that handles ECA models can handle AI agent workflows. RAG pipeline configuration. Autonomous task orchestration. When your complex logic needs visual representation and user control, the Modeler API provides the infrastructure.

What the API Provides

Let me get specific. When you implement a Model Owner plugin, the API automatically gives you:

1. Dynamic Routing
Define your base path (/admin/config/workflow/eca/ or /admin/structure/migrations/). The API generates routes for edit, delete, export, and all model operations. Permissions checked. UI chrome rendered. You define the path; the API does the rest.

2. Permissions System
The API handles permissions automatically, based on your model owner's supported features and the config entity type defining your models. Route access, UI rendering, save operations, import/export - all permission-checked by the API.

3. UI Integration
Tabs, breadcrumbs, local tasks render automatically. Your model owner appears in Drupal's admin UI like it's built-in.

4. Save Orchestration
User saves a model. API normalizes the data, validates it, calls your save method with clean data. You handle domain logic; API handles plumbing.

5. Import/Export
Models export as JSON, Archive, or Recipe. Import from any source. API handles serialization, deserialization, validation. You get clean data structures.

6. Template System
Build template libraries. Users discover, apply, customize. API handles storage, discovery, rendering, application. You provide templates; API delivers them.

7. Testing and Replay
Record model execution. Replay step-by-step. See token values at each step. The API provides the infrastructure; your model owner implements the execution hooks.

8. Drush Commands
drush modeler_api:update, drush modeler_api:enable, drush modeler_api:disable, drush modeler_api:model:export - all work for any model owner. API provides them; you benefit automatically.

Months of work to build from scratch. The Modeler API gives it to you.

For Developers: How to Use It

Your module needs visual configuration of complex logic? Here's the pattern:

1. Implement the Model Owner Plugin Interface

<?php

namespace Drupal\your_module\Plugin\ModelerApiModelOwner;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\modeler_api\Attribute\ModelOwner;
use Drupal\modeler_api\Plugin\ModelerApiModelOwner\ModelOwnerBase;

/**
 * Model owner plugin for your module.
 */
#[ModelOwner(
  id: "your_model_owner",
  label: new TranslatableMarkup("Your Model Owner"),
  description: new TranslatableMarkup("Visual configuration for your complex system")
)]
class YourModelOwner extends ModelOwnerBase {

  /**
   * {@inheritdoc}
   */
  public function componentLabels(): array {
    return [
      'start' => (string) $this->t('Start'),
      'element' => (string) $this->t('Step'),
      'link' => (string) $this->t('Condition'),
      'gateway' => (string) $this->t('Gateway'),
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function configEntityTypeId(): string {
    return 'your_config_entity_type';
  }

  /**
   * {@inheritdoc}
   */
  public function configEntityBasePath(): ?string {
    return 'admin/config/system/your-models';
  }

  /**
   * {@inheritdoc}
   */
  public function supportedOwnerComponentTypes(): array {
    return [
      Api::COMPONENT_TYPE_START => 'trigger',
      Api::COMPONENT_TYPE_ELEMENT => 'step',
    ];
  }

  // ModelOwnerBase provides implementations for most interface methods.
  // Override only what you need to customize.
}

2. Enable Your Module

That's it. When your module is enabled, Drupal's plugin discovery finds your Model Owner automatically. The Modeler API integrates it immediately.

3. Use Any Modeler

Users can now model your system visually using BPMN.iO, the Workflow Modeler, or any future modeler. The API handles translation.

4. Add Testing (Optional)

Implement the test/replay hooks. Users can now test your models, replay executions, debug issues visually.

The pattern is clean. The benefits are immediate.

The Compound Effect

This is where good architecture shines. Every new model owner makes every modeler more valuable. Every new modeler makes every model owner more valuable.

Today:

• ECA as a model owner
• BPMN.iO and Workflow Modeler as modelers
• Result: 2 working combinations

Tomorrow:

• Add Migrate as a model owner → 4 combinations (2 modelers × 2 owners)
• Add AI Agents as a model owner → 6 combinations (if that direction is pursued)
• Add a voice-driven modeler → 9 combinations (3 modelers × 3 owners)

Each addition multiplies value across the ecosystem. No glue code. No custom integration. The API handles it.

This is infrastructure that compounds over years.

Future: What This Enables

Three years from now, what becomes possible?

Scenario 1: Migration Workflows
Visual configuration of complex migrations. Drag source plugins, transformation steps, destination plugins. Connect them. Model dependencies. Test with sample data. Replay to debug. Export as Recipe. This becomes accessible to site builders, not just migration experts.

Scenario 2: AI Agent Orchestration
AI agents need task plans. "Scrape these URLs, extract entities, analyze sentiment, store results, notify users." That's a model. With the Modeler API, users build agent task flows visually. Test them. Replay executions. See what the agent did at each step.

Scenario 3: Commerce Checkout Customization
Checkout flows are complex: payment, shipping, tax calculation, inventory updates, notification. Model it visually. Drag steps. Define conditions. Connect actions. Test with sample carts. Replay production orders. Debug edge cases. All through the Modeler API.

Scenario 4: Content Publishing Pipelines
Draft → Review → Approval → Publish → Notify → Archive. Model the pipeline visually. Define approvers, notification rules, escalation logic. Test with sample content. Replay production workflows. Understand bottlenecks.

These aren't hypothetical. They're the natural next steps once you have infrastructure for visual configuration of complex systems.

Why This Took Years to Envision

The Modeler API wasn't a sudden breakthrough. It was years of:

• Answering "Can we use this for X?" with "Not yet"
• Watching developers reinvent visual configuration UIs
• Wrestling with incomplete decoupling between ECA and its modelers
• Studying Drupal's plugin architecture
• Recognizing the pattern: model owner vs modeler

The architecture was designed at DrupalCon Atlanta in early 2025, then developed in the following months. Long before next-gen ECA and the new Workflow Modeler were even conceived. Recognizing what to build - the right abstraction - took years.

That's the real work of architecture: seeing the abstraction hiding beneath the specifics.

What This Means for Drupal

Drupal now has a pattern for complex system configuration that scales. Not just "one module with visual config". An ecosystem where any module can provide visual configuration through a shared API.

This puts Drupal ahead. WordPress has page builders. Joomla has visual editors. But API-driven visual configuration for any complex system? That's Drupal territory now.

And when AI integration becomes table stakes, when autonomous agents need task configuration, when orchestration between systems is the norm - Drupal will have the infrastructure ready.

This abstraction layer took years to envision. It was designed at DrupalCon Atlanta in early 2025 and developed in the months that followed. It will pay dividends for years to come.

Get Involved

If you maintain a module that needs visual configuration:

• Study the Modeler API documentation
• Look at the ECA Model Owner implementation as a reference
• Join us in #modeler_api on Drupal Slack
• Ask questions, share use cases, propose extensions

This API is young. Your input shapes its evolution.

If you're building complex Drupal systems that need visual configuration, the infrastructure is ready. Build on it. Extend it. Make it yours.

Coming in Post 3: In-Context Customization - how ECA brings automation power directly to where users already are, without requiring them to understand models or visit admin screens.

View all posts in the ECA: The Next Chapter series

Join us on Drupal Slack