# sneadxx/nexus-inventory architecture

> Architecture diagram of the GitHub repository sneadxx/nexus-inventory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sneadxx/nexus-inventory
- Repository: https://github.com/sneadxx/nexus-inventory

## Overview

nexus-inventory is a Laravel package for normalizing product and inventory operations across Shopify, WooCommerce, Amazon, and Etsy. The principal workflow exposes channel drivers through Nexus, accepts product stock changes through builders, and dispatches queued inventory pushes; incoming webhooks are verified, parsed, logged, and converted into inventory events. The README also describes catalog syncing, dashboard/log views, and queue-based processing. Some of those runtime links are documented but their implementation was not sampled, so those edges are dashed or omitted.

Main entry points: [`src/InventoryManager.php`](https://github.com/sneadxx/nexus-inventory/blob/main/src/InventoryManager.php) (Inventory Manager), [`src/Drivers`](https://github.com/sneadxx/nexus-inventory/tree/main/src/Drivers) (Channel Drivers), [`src/Jobs/PushInventoryJob.php`](https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/PushInventoryJob.php) (Inventory Push Job), [`src/Services/WebhookProcessor.php`](https://github.com/sneadxx/nexus-inventory/blob/main/src/Services/WebhookProcessor.php) (Webhook Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sync["Sync API"]
  node_facade["Nexus Facade<br/>[Nexus.php]"]
  node_manager["Inventory Manager"]
  node_builders["Sync Builders"]
  node_catalog_builder["Catalog Builder"]
  node_batch_builder["Batch Builder<br/>[BatchBuilder.php]"]
  node_push_job["Inventory Push Job"]
  node_catalog_jobs["Catalog Jobs<br/>[CatalogSyncJob.php]"]
  node_batch_job["Channel Batch Job"]
end

subgraph group_channels["Sales Channels"]
  node_driver_contract["Driver Contract"]
  node_channel_drivers["Channel Drivers"]
  node_product_dto["Product DTO<br/>[NexusProduct.php]"]
  node_inventory_dto["Inventory Update"]
  node_channel_mapping[("Channel Mapping<br/>[ChannelMapping.php]")]
end

subgraph group_hooks["Webhook Intake"]
  node_webhook_controller["Webhook Controller"]
  node_signature_middleware["Signature Middleware"]
  node_webhook_processor["Webhook Processor"]
  node_webhook_verifiers["Channel Verifiers"]
  node_webhook_log["Webhook Log"]
end

subgraph group_ops["Operations"]
  node_event_stream["Inventory Events"]
  node_rate_limit["Token Bucket<br/>[TokenBucket.php]"]
  node_dashboard["Dashboard"]
  node_dead_letter[("Dead Letter Queue")]
  node_service_provider["Package Wiring"]
end

node_app_user(("Package User"))
node_store_admin(("Store Admin"))

node_app_user -.->|"uses"| node_facade
node_facade -->|"resolves"| node_manager
node_manager -->|"creates"| node_channel_drivers
node_manager -->|"creates"| node_catalog_builder
node_manager -->|"creates"| node_builders
node_manager -->|"creates"| node_batch_builder
node_channel_drivers -->|"implements"| node_driver_contract
node_channel_drivers -->|"normalizes"| node_product_dto
node_channel_drivers -->|"parses"| node_inventory_dto
node_builders -->|"dispatches"| node_push_job
node_app_user -.->|"requests stock sync"| node_builders
node_catalog_builder -->|"dispatches"| node_batch_job
node_catalog_builder -.->|"queues catalog work"| node_catalog_jobs
node_push_job -->|"reads mapping"| node_channel_mapping
node_push_job -->|"checks capacity"| node_rate_limit
node_push_job -->|"dispatches events"| node_event_stream
node_store_admin -.->|"sends webhook"| node_webhook_controller
node_webhook_controller -->|"requires verification"| node_signature_middleware
node_webhook_controller -->|"processes request"| node_webhook_processor
node_signature_middleware -.->|"verifies signature"| node_webhook_verifiers
node_webhook_processor -->|"parses and fetches"| node_channel_drivers
node_webhook_processor -->|"dispatches events"| node_event_stream
node_webhook_processor -.->|"records activity"| node_webhook_log
node_service_provider -->|"registers route"| node_webhook_controller
node_service_provider -->|"registers routes"| node_dashboard
node_service_provider -->|"stores failed jobs"| node_dead_letter
node_app_user -.->|"views inventory"| node_dashboard

click node_facade "https://github.com/sneadxx/nexus-inventory/blob/main/src/Facades/Nexus.php"
click node_manager "https://github.com/sneadxx/nexus-inventory/blob/main/src/InventoryManager.php"
click node_builders "https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/ProductSyncBuilder.php"
click node_catalog_builder "https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/CatalogSyncBuilder.php"
click node_batch_builder "https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/BatchBuilder.php"
click node_push_job "https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/PushInventoryJob.php"
click node_catalog_jobs "https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/CatalogSyncJob.php"
click node_batch_job "https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/ChannelSyncBatchJob.php"
click node_driver_contract "https://github.com/sneadxx/nexus-inventory/blob/main/src/Contracts/InventoryDriver.php"
click node_channel_drivers "https://github.com/sneadxx/nexus-inventory/tree/main/src/Drivers"
click node_product_dto "https://github.com/sneadxx/nexus-inventory/blob/main/src/DataTransferObjects/NexusProduct.php"
click node_inventory_dto "https://github.com/sneadxx/nexus-inventory/blob/main/src/DataTransferObjects/NexusInventoryUpdate.php"
click node_channel_mapping "https://github.com/sneadxx/nexus-inventory/blob/main/src/Models/ChannelMapping.php"
click node_webhook_controller "https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Controllers/WebhookController.php"
click node_signature_middleware "https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Middleware/VerifyNexusWebhookSignature.php"
click node_webhook_processor "https://github.com/sneadxx/nexus-inventory/blob/main/src/Services/WebhookProcessor.php"
click node_webhook_verifiers "https://github.com/sneadxx/nexus-inventory/tree/main/src/Webhooks/Verifiers"
click node_webhook_log "https://github.com/sneadxx/nexus-inventory/blob/main/resources/views/livewire/webhook-log.blade.php"
click node_event_stream "https://github.com/sneadxx/nexus-inventory/blob/main/src/Events/InventoryUpdated.php"
click node_rate_limit "https://github.com/sneadxx/nexus-inventory/blob/main/src/RateLimiting/TokenBucket.php"
click node_dashboard "https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Controllers/DashboardController.php"
click node_dead_letter "https://github.com/sneadxx/nexus-inventory/blob/main/src/Models/NexusDeadLetterQueue.php"
click node_service_provider "https://github.com/sneadxx/nexus-inventory/blob/main/src/NexusServiceProvider.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_facade,node_manager,node_builders,node_catalog_builder,node_batch_builder,node_push_job,node_catalog_jobs,node_batch_job,node_app_user toneBlue
class node_driver_contract,node_channel_drivers,node_product_dto,node_inventory_dto,node_channel_mapping toneAmber
class node_webhook_controller,node_signature_middleware,node_webhook_processor,node_webhook_verifiers,node_webhook_log toneMint
class node_event_stream,node_rate_limit,node_dashboard,node_dead_letter,node_service_provider toneRose
class node_store_admin toneIndigo
```

## Components

### Sync API

- [Nexus Facade](https://github.com/sneadxx/nexus-inventory/blob/main/src/Facades/Nexus.php): `src/Facades/Nexus.php`
- [Inventory Manager](https://github.com/sneadxx/nexus-inventory/blob/main/src/InventoryManager.php): `src/InventoryManager.php`
- [Sync Builders](https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/ProductSyncBuilder.php): `src/Builders/ProductSyncBuilder.php`
- [Catalog Builder](https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/CatalogSyncBuilder.php): `src/Builders/CatalogSyncBuilder.php`
- [Batch Builder](https://github.com/sneadxx/nexus-inventory/blob/main/src/Builders/BatchBuilder.php): `src/Builders/BatchBuilder.php`
- [Inventory Push Job](https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/PushInventoryJob.php): `src/Jobs/PushInventoryJob.php`
- [Catalog Jobs](https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/CatalogSyncJob.php): `src/Jobs/CatalogSyncJob.php`
- [Channel Batch Job](https://github.com/sneadxx/nexus-inventory/blob/main/src/Jobs/ChannelSyncBatchJob.php): `src/Jobs/ChannelSyncBatchJob.php`

### Sales Channels

- [Driver Contract](https://github.com/sneadxx/nexus-inventory/blob/main/src/Contracts/InventoryDriver.php): `src/Contracts/InventoryDriver.php`
- [Channel Drivers](https://github.com/sneadxx/nexus-inventory/tree/main/src/Drivers): `src/Drivers`
- [Product DTO](https://github.com/sneadxx/nexus-inventory/blob/main/src/DataTransferObjects/NexusProduct.php): `src/DataTransferObjects/NexusProduct.php`
- [Inventory Update](https://github.com/sneadxx/nexus-inventory/blob/main/src/DataTransferObjects/NexusInventoryUpdate.php): `src/DataTransferObjects/NexusInventoryUpdate.php`
- [Channel Mapping](https://github.com/sneadxx/nexus-inventory/blob/main/src/Models/ChannelMapping.php): `src/Models/ChannelMapping.php`

### Webhook Intake

- [Webhook Controller](https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Controllers/WebhookController.php): `src/Http/Controllers/WebhookController.php`
- [Signature Middleware](https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Middleware/VerifyNexusWebhookSignature.php): `src/Http/Middleware/VerifyNexusWebhookSignature.php`
- [Webhook Processor](https://github.com/sneadxx/nexus-inventory/blob/main/src/Services/WebhookProcessor.php): `src/Services/WebhookProcessor.php`
- [Channel Verifiers](https://github.com/sneadxx/nexus-inventory/tree/main/src/Webhooks/Verifiers): `src/Webhooks/Verifiers`
- [Webhook Log](https://github.com/sneadxx/nexus-inventory/blob/main/resources/views/livewire/webhook-log.blade.php): `resources/views/livewire/webhook-log.blade.php`

### Operations

- [Inventory Events](https://github.com/sneadxx/nexus-inventory/blob/main/src/Events/InventoryUpdated.php): `src/Events/InventoryUpdated.php`
- [Token Bucket](https://github.com/sneadxx/nexus-inventory/blob/main/src/RateLimiting/TokenBucket.php): `src/RateLimiting/TokenBucket.php`
- [Dashboard](https://github.com/sneadxx/nexus-inventory/blob/main/src/Http/Controllers/DashboardController.php): `src/Http/Controllers/DashboardController.php`
- [Dead Letter Queue](https://github.com/sneadxx/nexus-inventory/blob/main/src/Models/NexusDeadLetterQueue.php): `src/Models/NexusDeadLetterQueue.php`
- [Package Wiring](https://github.com/sneadxx/nexus-inventory/blob/main/src/NexusServiceProvider.php): `src/NexusServiceProvider.php`

### Other components

- **Package User**
- **Store Admin**

## Connections

- Package User → Nexus Facade: uses
- Nexus Facade → Inventory Manager: resolves (evidence: `src/Facades/Nexus.php`)
- Inventory Manager → Channel Drivers: creates (evidence: `src/InventoryManager.php`)
- Inventory Manager → Catalog Builder: creates (evidence: `src/InventoryManager.php`)
- Inventory Manager → Sync Builders: creates (evidence: `src/InventoryManager.php`)
- Inventory Manager → Batch Builder: creates (evidence: `src/InventoryManager.php`)
- Channel Drivers → Driver Contract: implements (evidence: `src/Drivers/Amazon/AmazonDriver.php`)
- Channel Drivers → Product DTO: normalizes (evidence: `src/Drivers/Amazon/AmazonDriver.php`)
- Channel Drivers → Inventory Update: parses (evidence: `src/Drivers/Amazon/AmazonDriver.php`)
- Sync Builders → Inventory Push Job: dispatches (evidence: `src/Builders/ProductSyncBuilder.php`)
- Package User → Sync Builders: requests stock sync
- Catalog Builder → Channel Batch Job: dispatches (evidence: `src/Builders/CatalogSyncBuilder.php`)
- Catalog Builder → Catalog Jobs: queues catalog work
- Inventory Push Job → Channel Mapping: reads mapping (evidence: `src/Jobs/PushInventoryJob.php`)
- Inventory Push Job → Token Bucket: checks capacity (evidence: `src/Jobs/PushInventoryJob.php`)
- Inventory Push Job → Inventory Events: dispatches events (evidence: `src/Jobs/PushInventoryJob.php`)
- Store Admin → Webhook Controller: sends webhook
- Webhook Controller → Signature Middleware: requires verification (evidence: `src/Http/Controllers/WebhookController.php`)
- Webhook Controller → Webhook Processor: processes request (evidence: `src/Http/Controllers/WebhookController.php`)
- Signature Middleware → Channel Verifiers: verifies signature (evidence: `src/Http/Middleware/VerifyNexusWebhookSignature.php`)
- Webhook Processor → Channel Drivers: parses and fetches (evidence: `src/Services/WebhookProcessor.php`)
- Webhook Processor → Inventory Events: dispatches events (evidence: `src/Services/WebhookProcessor.php`)
- Webhook Processor → Webhook Log: records activity
- Package Wiring → Webhook Controller: registers route (evidence: `src/NexusServiceProvider.php`)
- Package Wiring → Dashboard: registers routes (evidence: `src/NexusServiceProvider.php`)
- Package Wiring → Dead Letter Queue: stores failed jobs (evidence: `src/NexusServiceProvider.php`)
- Package User → Dashboard: views inventory
