Architecture

Components

• Ingestion (Akeneo): Webhooks and API sync import entities to local DB.
• Local Model: Eloquent models for Product, Category, Family, ProductAttribute, ProductAttributeValue.
• Change Tracking: `EntityObserver` and `TracksEavChanges` produce Mutation records.
• Mutation Pipeline: `Mutation` and `MutationJob` coordinate fan-out and delivery.
• Queueing: Queues selected by `QueueResolver` using `config/queue-map.php`.
• Workers & Monitoring: Redis-backed queues + Horizon dashboard and supervisors.
• Integrations: `Integration` model + `DriverDiscovery` to get tagged Drivers (e.g., Magento2).
• Mapping: `DatabaseEntityMappingService` implements `EntityMappingServiceInterface` for ID bridging.

External refs:

• Laravel architecture: https://laravel.com/docs/12.x
• Akeneo PHP client: https://github.com/akeneo/php-api-client
• Horizon: https://laravel.com/docs/12.x/horizon

Data Flow

1) Upstream event or scheduled sync creates/updates local entities.

2) Observer computes changed fields and creates a `Mutation` with payload and diffs.

3) For each enabled `Integration` that handles the entity type, a `MutationJob` is created with a priority.

4) Jobs go to priority queues: `integrations-immediate`, `integrations-normal`, `integrations-low`.

5) `ProcessMutationJob` loads the appropriate Driver and calls `handle(MutationData)`.

6) Driver builds target payloads (e.g., Magento 2 rules-based product builder), performs API calls, and updates `MutationJob` status; Horizon captures metrics and failures.

Priority Mapping

Configured in `config/queue-map.php` and per-integration in `priority_map` (see `config/integrations.php`). Lower numbers → higher priority.

Drivers

• Drivers implement `IEC\IntegrationContracts\Contracts\DriverContract` (via `AbstractDriver`).
• Provide name, type (key), version, description, supported entity types, configuration schema, and `handle`/`handleBatch`.
• Registered by Module service providers and tagged as `integration`.
• Drivers can access integration-specific context (e.g., mapping data, websites) via `IntegrationContextInterface`.

External refs:

• Integration contracts: see `docs/iec/10-integration-contracts.md`

Modules

• Example: `Modules/Magento2` registers `Magento2Driver`, repository, actions, and routes.
• Modules are PSR-4 autoloaded and discovered via `nwidart/laravel-modules`.