# sd2389/devjewels-channels architecture

> Architecture diagram of the GitHub repository sd2389/devjewels-channels, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sd2389/devjewels-channels
- Repository: https://github.com/sd2389/devjewels-channels

## Overview

DevJewels Channels is a multi-platform commerce synchronization service, with Shopify implemented first and WooCommerce still a webhook stub. The principal flow ingests Django catalog and inventory events, deduplicates and fans them out to queued jobs, then workers synchronize Shopify products and inventory; order webhooks are normalized and reserved through Django. The graph also includes Shopify installation, connection administration, and the shared channels-schema state. The README documents several capabilities whose implementations were not sampled, so those links are shown only where its workflow explicitly supports them.

Main entry points: [`apps/core/src/workers/handlers.ts`](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/workers/handlers.ts) (Worker dispatch), [`apps/core/src/services/productSyncService.ts`](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/productSyncService.ts) (Product sync), [`apps/core/src/services/queue.ts`](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/queue.ts) (Job queues), [`apps/core/src/integrations/deverp/client.ts`](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/integrations/deverp/client.ts) (Django API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Dashboard and connections"]
  node_dashboard["Dashboard"]
  node_admin_routes["Admin routes<br/>[admin.ts]"]
  node_shopify_connect["Shopify connect<br/>[shopifyConnect.ts]"]
  node_connect_service["Connection service"]
end

subgraph group_ingest["Events and queues"]
  node_event_route["Event ingest<br/>[internalEvents.ts]"]
  node_events["Event processing<br/>[events.ts]"]
  node_fanout["Event fan-out<br/>[inventoryFanOut.ts]"]
  node_queue["Job queues<br/>[queue.ts]"]
end

subgraph group_sync["Sync workers"]
  node_workers["Worker dispatch<br/>[handlers.ts]"]
  node_inventory_sync["Inventory sync"]
  node_product_sync["Product sync"]
  node_catalog_import["Catalog import"]
  node_order_sync["Order processing"]
end

subgraph group_platform["Platform integrations"]
  node_oauth["OAuth flow<br/>[shopifyAuth.ts]"]
  node_webhook_route["Shopify webhooks<br/>[shopifyWebhooks.ts]"]
  node_shopify_adapter["Shopify adapter<br/>[adapter.ts]"]
  node_woocommerce_hook["WooCommerce webhook stub<br/>[route.ts]"]
  node_deverp_client["Django API client<br/>[client.ts]"]
end

subgraph group_state["Shared state"]
  node_shared_db[("Channels schema<br/>[client.ts]")]
  node_connections["Connection records<br/>[connections.ts]"]
  node_event_store["Ingest and webhook state"]
end

node_operator(("Operator"))
node_django["DevJewels Django"]
node_shopify_ext["Shopify"]

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_admin_routes
node_admin_routes -->|"manages"| node_connections
node_admin_routes -->|"looks up customers"| node_deverp_client
node_operator -->|"starts install"| node_shopify_connect
node_shopify_connect -->|"initiates"| node_connect_service
node_connect_service -->|"stores connection"| node_connections
node_connect_service -->|"creates Shopify install"| node_shopify_ext
node_operator -->|"approves install"| node_oauth
node_oauth -->|"exchanges OAuth"| node_shopify_ext
node_oauth -->|"persists credentials"| node_connections
node_django -->|"posts events"| node_event_route
node_event_route -->|"validates and processes"| node_events
node_events -->|"claims event ID"| node_event_store
node_events -->|"dispatches event"| node_fanout
node_fanout -->|"reads mappings"| node_shared_db
node_fanout -->|"enqueues jobs"| node_queue
node_queue -->|"dispatches jobs"| node_workers
node_workers -->|"runs inventory jobs"| node_inventory_sync
node_workers -->|"runs product jobs"| node_product_sync
node_workers -->|"runs imports"| node_catalog_import
node_inventory_sync -->|"reads inventory"| node_deverp_client
node_inventory_sync -->|"sets quantities"| node_shopify_adapter
node_product_sync -->|"reads catalog and prices"| node_deverp_client
node_product_sync -->|"creates or updates"| node_shopify_adapter
node_product_sync -->|"enqueues inventory"| node_queue
node_product_sync -->|"updates mappings"| node_shared_db
node_catalog_import -->|"loads catalog"| node_deverp_client
node_catalog_import -->|"enqueues product jobs"| node_queue
node_shopify_ext -->|"sends webhooks"| node_webhook_route
node_webhook_route -->|"verifies webhook"| node_shopify_adapter
node_webhook_route -->|"claims webhook"| node_event_store
node_webhook_route -->|"enqueues order job"| node_queue
node_workers -->|"runs order jobs"| node_order_sync
node_order_sync -->|"reserves order"| node_deverp_client
node_order_sync -->|"normalizes order"| node_shopify_adapter
node_woocommerce_hook -.-> node_shopify_ext

click node_dashboard "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/app/(dashboard)/ConnectDashboard.tsx"
click node_admin_routes "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/admin.ts"
click node_shopify_connect "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyConnect.ts"
click node_oauth "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyAuth.ts"
click node_connect_service "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/connectShopifyService.ts"
click node_event_route "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/internalEvents.ts"
click node_events "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/events.ts"
click node_fanout "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/inventoryFanOut.ts"
click node_queue "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/queue.ts"
click node_workers "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/workers/handlers.ts"
click node_inventory_sync "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/inventorySyncService.ts"
click node_product_sync "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/productSyncService.ts"
click node_catalog_import "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/catalogImportService.ts"
click node_order_sync "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/orderProcessingService.ts"
click node_webhook_route "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyWebhooks.ts"
click node_shopify_adapter "https://github.com/sd2389/devjewels-channels/blob/main/apps/shopify/src/adapter.ts"
click node_woocommerce_hook "https://github.com/sd2389/devjewels-channels/blob/main/apps/woocommerce/app/api/woocommerce/webhooks/route.ts"
click node_deverp_client "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/integrations/deverp/client.ts"
click node_shared_db "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/db/shared/client.ts"
click node_connections "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/connections.ts"
click node_event_store "https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/eventIdempotency.ts"

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_dashboard,node_admin_routes,node_shopify_connect,node_connect_service toneBlue
class node_event_route,node_events,node_fanout,node_queue toneAmber
class node_workers,node_inventory_sync,node_product_sync,node_catalog_import,node_order_sync toneMint
class node_oauth,node_webhook_route,node_shopify_adapter,node_woocommerce_hook,node_deverp_client toneRose
class node_shared_db,node_connections,node_event_store,node_operator,node_django,node_shopify_ext toneIndigo
```

## Components

### Dashboard and connections

- [Dashboard](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/app/(dashboard)/ConnectDashboard.tsx): `apps/core/src/app/(dashboard)/ConnectDashboard.tsx`
- [Admin routes](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/admin.ts): `apps/core/src/http/routes/admin.ts`
- [Shopify connect](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyConnect.ts): `apps/core/src/http/routes/shopifyConnect.ts`
- [Connection service](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/connectShopifyService.ts): `apps/core/src/services/connectShopifyService.ts`

### Events and queues

- [Event ingest](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/internalEvents.ts): `apps/core/src/http/routes/internalEvents.ts`
- [Event processing](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/events.ts): `apps/core/src/services/events.ts`
- [Event fan-out](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/inventoryFanOut.ts): `apps/core/src/services/inventoryFanOut.ts`
- [Job queues](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/queue.ts): `apps/core/src/services/queue.ts`

### Sync workers

- [Worker dispatch](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/workers/handlers.ts): `apps/core/src/workers/handlers.ts`
- [Inventory sync](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/inventorySyncService.ts): `apps/core/src/services/inventorySyncService.ts`
- [Product sync](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/productSyncService.ts): `apps/core/src/services/productSyncService.ts`
- [Catalog import](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/catalogImportService.ts): `apps/core/src/services/catalogImportService.ts`
- [Order processing](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/orderProcessingService.ts): `apps/core/src/services/orderProcessingService.ts`

### Platform integrations

- [OAuth flow](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyAuth.ts): `apps/core/src/http/routes/shopifyAuth.ts`
- [Shopify webhooks](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/http/routes/shopifyWebhooks.ts): `apps/core/src/http/routes/shopifyWebhooks.ts`
- [Shopify adapter](https://github.com/sd2389/devjewels-channels/blob/main/apps/shopify/src/adapter.ts): `apps/shopify/src/adapter.ts`
- [WooCommerce webhook stub](https://github.com/sd2389/devjewels-channels/blob/main/apps/woocommerce/app/api/woocommerce/webhooks/route.ts): `apps/woocommerce/app/api/woocommerce/webhooks/route.ts`
- [Django API client](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/integrations/deverp/client.ts): `apps/core/src/integrations/deverp/client.ts`

### Shared state

- [Channels schema](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/db/shared/client.ts): `apps/core/src/db/shared/client.ts`
- [Connection records](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/connections.ts): `apps/core/src/services/connections.ts`
- [Ingest and webhook state](https://github.com/sd2389/devjewels-channels/blob/main/apps/core/src/services/eventIdempotency.ts): `apps/core/src/services/eventIdempotency.ts`

### Other components

- **Operator**
- **DevJewels Django**
- **Shopify**

## Connections

- Operator → Dashboard: uses
- Dashboard → Admin routes: requests
- Admin routes → Connection records: manages
- Admin routes → Django API client: looks up customers
- Operator → Shopify connect: starts install
- Shopify connect → Connection service: initiates
- Connection service → Connection records: stores connection
- Connection service → Shopify: creates Shopify install
- Operator → OAuth flow: approves install
- OAuth flow → Shopify: exchanges OAuth
- OAuth flow → Connection records: persists credentials
- DevJewels Django → Event ingest: posts events
- Event ingest → Event processing: validates and processes
- Event processing → Ingest and webhook state: claims event ID
- Event processing → Event fan-out: dispatches event
- Event fan-out → Channels schema: reads mappings
- Event fan-out → Job queues: enqueues jobs
- Job queues → Worker dispatch: dispatches jobs
- Worker dispatch → Inventory sync: runs inventory jobs
- Worker dispatch → Product sync: runs product jobs
- Worker dispatch → Catalog import: runs imports
- Inventory sync → Django API client: reads inventory
- Inventory sync → Shopify adapter: sets quantities
- Product sync → Django API client: reads catalog and prices
- Product sync → Shopify adapter: creates or updates
- Product sync → Job queues: enqueues inventory
- Product sync → Channels schema: updates mappings
- Catalog import → Django API client: loads catalog
- Catalog import → Job queues: enqueues product jobs
- Shopify → Shopify webhooks: sends webhooks
- Shopify webhooks → Shopify adapter: verifies webhook
- Shopify webhooks → Ingest and webhook state: claims webhook
- Shopify webhooks → Job queues: enqueues order job
- Worker dispatch → Order processing: runs order jobs
- Order processing → Django API client: reserves order
- Order processing → Shopify adapter: normalizes order
- WooCommerce webhook stub → Shopify