Intermediate Entity Connector (IEC) — Overview

IEC is a generic, extensible integration platform built on Laravel. It ingests entities (products, families, categories, attributes) from upstream systems like Akeneo PIM into a normalized local model, tracks changes, and fans out mutations to downstream systems (e.g., Magento 2) via Drivers.

Goals

• Decouple ingestion from delivery so each integration can evolve independently.
• Provide a reliable pipeline with prioritization, retries, and observability.
• Keep a local source of truth optimized for mutation generation.
• Make new integrations easy to add using a Driver contract.

Who Should Read This

• Product Owners and stakeholders who want a high-level understanding of how we move data.
• Engineers and solution architects designing new integrations and troubleshooting issues.

High-Level Flow

1. Ingestion (Akeneo):

- Webhooks or API sync fetch entities and store them in local tables.

2. Change Tracking:

- Model observers detect entity changes, create a Mutation record with payload and diffs.

3. Fan-out & Prioritization:

- For each enabled Integration, a Mutation Job is created with a computed priority.

4. Queue & Workers:

- Jobs are dispatched to Redis-backed queues. Horizon supervises workers.

5. Driver Execution:

- A Driver (e.g., Magento 2) translates MutationData into API calls to the target system.

Key Features

• Pluggable Drivers discovered via tags; each Driver defines its configuration schema.
• Priority-based queues for immediate/normal/low workloads, resolved from Integration `priority_map` per mutation.
• Retriable jobs with backoff and visibility in Horizon dashboard.
• Entity mapping service to relate local UUIDs to external IDs.

External References

• Laravel: https://laravel.com/
• Akeneo PIM: https://www.akeneo.com/
• Magento 2 REST: https://developer.adobe.com/commerce/webapi/rest/
• Docker: https://docs.docker.com/
• Taskfile: https://taskfile.dev/

First Integration: Akeneo → Magento 2

• Import Akeneo data into local DB (products, categories, attributes, families).
• Generate product mutations; the Magento 2 Driver posts to REST `rest/V1` endpoints.

Project References

• EPIC overview (Lucid): https://lucid.app/lucidchart/58030f6c-312d-41bc-a1af-dd553c2fa65c/edit?page=0_0&invitationId=inv_aa41a267-22b0-4dab-b167-bc463f9aa6f1#
• Breakdown of development steps: https://docs.google.com/document/d/1aDoxa0gVvqg6Rg1TmoEtBw5mcxs8wbExDgho4mcnJ3k/edit?tab=t.0#heading=h.zdsxq2hea1vt
• M2 test checklist: https://docs.google.com/spreadsheets/d/1uRfAr6sthKDmkvOJCxWngdsLByiNmbxyblUSsMKoTSg/edit?gid=0#gid=0