Fyrn
Back to blog
architectureconfig-as-code

Declarative vs. Imperative Integration: Why YAML Configs Beat Visual Builders

The case for version-controllable, declarative integration configs over drag-and-drop visual builders. Git workflows, code review, and reproducible deployments.

Fyrn Engineering ·

Open your integration platform. Find a production flow. Now answer these questions:

  • What changed in the last deploy?
  • Who approved it?
  • Can you roll it back in 30 seconds?
  • Could a new engineer understand it without a walkthrough?

If your integrations live in a visual builder, the answer to most of these is no. The flow looks like a canvas of connected boxes. Changes are tracked (maybe) as timestamps in a proprietary version history. There’s no diff, no review, no branch-and-merge workflow.

This is the imperative model: you tell the system how to do something, step by step, using the platform’s visual language. It works for demos. It doesn’t work for teams.

The declarative model is the alternative: you describe what you want, the system figures out how. The description is a text file — YAML, JSON, HCL — that lives in your repo, goes through code review, and deploys through your CI/CD pipeline.

Imperative: The Visual Builder Model

In an imperative integration builder, you:

  1. Drag a “trigger” node onto the canvas
  2. Connect it to a “transformation” node
  3. Configure each field mapping in a modal dialog
  4. Connect the output to a “target” node
  5. Test it manually in the GUI
  6. Click “Deploy”

The resulting integration is stored as a proprietary object in the platform’s database. You might get a JSON export, but it’s typically a serialized representation of the GUI state — not a human-readable description of the integration logic.

Here’s what the “export” of a visual builder flow often looks like:

{
  "flow_id": "f7a3b2c1-...",
  "version": 47,
  "canvas": {
    "nodes": [
      {
        "id": "n1",
        "type": "trigger_shopify_order_created",
        "position": {"x": 120, "y": 80},
        "config": {
          "connection_id": "conn_abc123",
          "filters": [{"field": "financial_status", "op": "eq", "value": "paid"}]
        }
      },
      {
        "id": "n2",
        "type": "transform_mapping",
        "position": {"x": 340, "y": 80},
        "config": {
          "mappings": [
            {"source": "$.order.id", "target": "$.external_id", "transform": null},
            {"source": "$.order.email", "target": "$.customer_email", "transform": "lowercase"}
          ]
        }
      }
    ],
    "edges": [{"from": "n1", "to": "n2", "port": "output"}]
  }
}

Canvas coordinates. Node IDs. Connection references. This isn’t documentation — it’s GUI state. Try reviewing that in a pull request.

Declarative: The Config-as-Code Model

A declarative integration describes the outcome, not the mouse clicks:

flow: shopify-orders-to-erp
description: "Sync paid Shopify orders to ERP as sales orders"

trigger:
  source: shopify
  event: orders/create
  filter:
    financial_status: paid

transform:
  order:
    external_id: "{{ trigger.id }}"
    customer_email: "{{ trigger.email | lowercase }}"
    items: "{{ trigger.line_items | map: sku, quantity, price }}"
    shipping:
      address: "{{ trigger.shipping_address }}"
      method: "{{ trigger.shipping_lines[0].title }}"
    total: "{{ trigger.total_price }}"

target:
  destination: erp
  action: sales_orders.create
  on_conflict: update_by_external_id

retry:
  max_attempts: 3
  backoff: exponential

alerts:
  on_failure: ops-channel

This is readable. Reviewable. Diffable. A new engineer can understand the integration in 30 seconds.

Why Declarative Wins for Teams

Git-native workflows

Declarative configs are text files. They live in your repo. This gives you everything git provides for free:

# See what changed
git diff main..feature/update-order-sync

# Review before deploy
gh pr create --title "Update order sync: add shipping method"

# Roll back a bad deploy
git revert abc123

# See who changed what and when
git blame flows/shopify-orders-to-erp.yaml

Visual builders offer “version history” — a list of timestamps with “Restore” buttons. That’s not the same as a branch-based review workflow with approvals, CI checks, and automated testing.

Code review for integrations

When an engineer modifies a declarative config, the team sees exactly what changed:

  transform:
    order:
      external_id: "{{ trigger.id }}"
      customer_email: "{{ trigger.email | lowercase }}"
      items: "{{ trigger.line_items | map: sku, quantity, price }}"
+     shipping:
+       address: "{{ trigger.shipping_address }}"
+       method: "{{ trigger.shipping_lines[0].title }}"
      total: "{{ trigger.total_price }}"

Two lines added. Clear what they do. Reviewable in a PR. Approver can verify the field paths are correct.

Compare that to reviewing a visual builder change: “Something changed in the Shopify-to-ERP flow. Click through 4 tabs of modal dialogs to find it.”

Reproducible deployments

Declarative configs enable proper CI/CD:

# .github/workflows/deploy-flows.yml
on:
  push:
    branches: [main]
    paths: ['flows/**']

jobs:
  deploy:
    steps:
      - uses: actions/checkout@v4
      - run: fyrn validate flows/
      - run: fyrn test flows/ --fixtures tests/
      - run: fyrn deploy flows/ --env production

Every change is validated, tested against fixtures, and deployed automatically. No manual “click Deploy” in a GUI. No “did someone change production directly?” uncertainty.

Environment promotion

With config-as-code, promoting from staging to production is a merge:

# flows/shopify-orders-to-erp.yaml uses environment variables
target:
  destination: erp
  endpoint: "{{ env.ERP_API_URL }}"
  credentials: "{{ env.ERP_API_KEY }}"

Same config, different environment variables. Staging and production run identical logic — the only difference is where they point. Visual builders typically require duplicating the entire flow across environments and keeping them manually in sync.

The AI Generation Advantage

One objection to declarative configs: “Writing YAML is still manual work. Visual builders are faster for simple integrations.”

This was true in 2024. It’s not true in 2026. AI generation inverts the equation:

  1. You describe the integration in natural language
  2. AI generates the declarative config
  3. You review, approve, and merge

The AI handles the YAML syntax, field mapping research, and boilerplate. You handle the intent and review. The result is still a version-controlled text file — not a black box.

This means declarative configs get the speed advantage of visual builders (fast creation) plus the maintainability advantage of code (git workflows, reviews, CI/CD).

When Visual Builders Make Sense

To be fair, visual builders aren’t always wrong:

  • Non-technical users who need to set up simple automations (marketing → CRM sync)
  • Prototyping where you’re exploring what’s possible before committing to a production config
  • Very simple integrations (single trigger, single action, no transformation)

But the moment you need version control, code review, reproducible deployments, or team collaboration — the visual builder becomes a liability. And most integrations reach that point faster than you’d expect.

Migration Path

If you’re currently on a visual builder and want to move to declarative:

  1. Export what you can. Most platforms offer some form of JSON export. Even if it’s ugly GUI state, it contains the logic.
  2. Translate to declarative configs. Map the triggers, transformations, and targets from the export into clean YAML. AI tools can help here.
  3. Add to git. Create a flows/ directory in your repo.
  4. Set up CI/CD. Validate and deploy configs on merge.
  5. Migrate incrementally. Move flows one at a time, starting with the most critical or frequently-changed ones.

The investment pays off immediately. The first time you catch a bad mapping in code review instead of in production, you’ll wonder why you ever used a GUI.

The Bottom Line

Visual builders optimize for the first 10 minutes of building an integration. Declarative configs optimize for the next 10 months of maintaining it. Since maintenance is 90% of the lifecycle cost, the math is clear.

Write your integrations like you write your infrastructure: as code, in version control, with review and CI/CD. The visual canvas was a crutch. It’s time to let go.