# jame2026/retailer-system-dropshipping architecture

> Architecture diagram of the GitHub repository jame2026/retailer-system-dropshipping, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jame2026/retailer-system-dropshipping
- Repository: https://github.com/jame2026/retailer-system-dropshipping

## Overview

This is a Shopify dropshipping operations platform: administrators monitor orders, manage supplier SKU mappings and pricing, and submit sourcing requests; Shopify order events enter the backend, are held for safety checks, mapped and dispatched to CJ or Zendrop, then tracking is synchronized back to Shopify. The graph includes the documented dashboard capabilities and background billing/retry work. Some frontend wiring and background-job implementation were not sampled, so uncertain connections are omitted or marked unverified.

Main entry points: [`server/services/order.service.ts`](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/order.service.ts) (Order lifecycle), [`server/services/fulfillment.service.ts`](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/fulfillment.service.ts) (Fulfillment sync), [`server/routes/webhooks/shopify.routes.ts`](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/webhooks/shopify.routes.ts) (Shopify webhook routes), [`server/controllers/order.controller.ts`](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/order.controller.ts) (Order endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin dashboard"]
  node_client["Dashboard application<br/>[App.tsx]"]
  node_dashboard["Operations dashboard<br/>[DashboardPage.tsx]"]
  node_orders_ui["Order management<br/>[OrdersPage.tsx]"]
  node_detail_ui["Order inspection"]
  node_catalog_ui["Catalog mappings<br/>[CatalogPage.tsx]"]
  node_pricing_ui["Pricing rules"]
  node_sourcing_ui["Product sourcing<br/>[SourcingPage.tsx]"]
  node_order_hook["Order data hook<br/>[useOrders.ts]"]
  node_order_client["Order API client<br/>[orderService.ts]"]
end

subgraph group_api["API and webhooks"]
  node_backend["Express API<br/>[app.ts]"]
  node_webhook_routes["Shopify webhook routes<br/>[shopify.routes.ts]"]
  node_webhook_auth["Webhook signature check"]
  node_webhook_controller["Webhook processing"]
  node_admin_routes["Admin API routes<br/>[order.routes.ts]"]
  node_auth["Admin authentication<br/>[authAdmin.ts]"]
  node_order_controller["Order endpoints"]
  node_catalog_routes["Catalog routes<br/>[catalog.routes.ts]"]
  node_sourcing_routes["Sourcing routes<br/>[sourcing.routes.ts]"]
end

subgraph group_orders["Order operations"]
  node_order_service["Order lifecycle<br/>[order.service.ts]"]
  node_address["Address normalization"]
  node_db[("PostgreSQL database<br/>[client.ts]")]
  node_hold_job["Six-hour hold worker"]
  node_billing_job["Billing retry job"]
  node_tracking_job["Tracking sync job"]
  node_fulfillment["Fulfillment sync"]
end

subgraph group_catalog["Catalog and sourcing"]
  node_mapping["Supplier SKU mapping<br/>[mapping.service.ts]"]
  node_pricing["Dynamic pricing<br/>[pricing.service.ts]"]
  node_catalog_controller["Catalog endpoints"]
  node_sourcing_controller["Sourcing endpoints"]
end

subgraph group_integrations["Supplier and store integrations"]
  node_shopify(("Shopify"))
  node_cj_sourcing["CJ product sourcing<br/>[cj.sourcing.ts]"]
  node_cj_order["CJ order integration<br/>[cj.order.ts]"]
  node_zendrop["Zendrop integration<br/>[zendrop.client.ts]"]
end

node_admin(("Administrator"))

node_admin -.->|"uses"| node_client
node_shopify -.->|"sends events"| node_webhook_routes
node_backend -->|"mounts routes"| node_webhook_routes
node_webhook_routes -->|"verifies requests"| node_webhook_auth
node_webhook_routes -->|"routes events"| node_webhook_controller
node_webhook_controller -->|"handles orders"| node_order_service
node_admin_routes -->|"protects endpoints"| node_auth
node_admin_routes -->|"routes requests"| node_order_controller
node_order_controller -->|"invokes operations"| node_order_service
node_order_controller -->|"reads order detail"| node_db
node_order_service -->|"reads and writes"| node_db
node_order_service -->|"normalizes address"| node_address
node_order_service -->|"resolves SKUs"| node_mapping
node_order_service -->|"dispatches orders"| node_cj_order
node_order_service -->|"fallback dispatch"| node_zendrop
node_catalog_routes -->|"routes requests"| node_catalog_controller
node_catalog_controller -->|"manages mappings"| node_mapping
node_catalog_controller -->|"calculates prices"| node_pricing
node_mapping -->|"calculates selling price"| node_pricing
node_sourcing_routes -->|"routes requests"| node_sourcing_controller
node_sourcing_controller -->|"searches and submits"| node_cj_sourcing
node_hold_job -->|"processes held orders"| node_order_service
node_fulfillment -->|"reads and updates"| node_db
node_fulfillment -->|"fetches tracking"| node_cj_order
node_fulfillment -->|"fetches tracking"| node_zendrop
node_fulfillment -.->|"pushes fulfillment"| node_shopify
node_order_hook -->|"calls"| node_order_client
node_order_client -.->|"requests API"| node_backend

click node_client "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/App.tsx"
click node_dashboard "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/DashboardPage.tsx"
click node_orders_ui "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/OrdersPage.tsx"
click node_detail_ui "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/OrderDetailPage.tsx"
click node_catalog_ui "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/CatalogPage.tsx"
click node_pricing_ui "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/PricingRulesPage.tsx"
click node_sourcing_ui "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/SourcingPage.tsx"
click node_order_hook "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/hooks/useOrders.ts"
click node_order_client "https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/services/orderService.ts"
click node_backend "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/app.ts"
click node_webhook_routes "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/webhooks/shopify.routes.ts"
click node_webhook_auth "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/middleware/verifyShopifyHmac.ts"
click node_webhook_controller "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/webhook.controller.ts"
click node_admin_routes "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/order.routes.ts"
click node_auth "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/middleware/authAdmin.ts"
click node_order_controller "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/order.controller.ts"
click node_order_service "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/order.service.ts"
click node_address "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/utils/addressNormalizer.ts"
click node_mapping "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/mapping.service.ts"
click node_pricing "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/pricing.service.ts"
click node_catalog_routes "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/catalog.routes.ts"
click node_catalog_controller "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/catalog.controller.ts"
click node_sourcing_routes "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/sourcing.routes.ts"
click node_sourcing_controller "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/sourcing.controller.ts"
click node_cj_sourcing "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/cj/cj.sourcing.ts"
click node_db "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/database/client.ts"
click node_hold_job "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/holdBuffer.worker.ts"
click node_billing_job "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/retryBilling.job.ts"
click node_tracking_job "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/trackingSync.job.ts"
click node_fulfillment "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/fulfillment.service.ts"
click node_cj_order "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/cj/cj.order.ts"
click node_zendrop "https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/zendrop/zendrop.client.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_client,node_dashboard,node_orders_ui,node_detail_ui,node_catalog_ui,node_pricing_ui,node_sourcing_ui,node_order_hook,node_order_client toneBlue
class node_backend,node_webhook_routes,node_webhook_auth,node_webhook_controller,node_admin_routes,node_auth,node_order_controller,node_catalog_routes,node_sourcing_routes toneAmber
class node_order_service,node_address,node_db,node_hold_job,node_billing_job,node_tracking_job,node_fulfillment toneMint
class node_mapping,node_pricing,node_catalog_controller,node_sourcing_controller toneRose
class node_shopify,node_cj_sourcing,node_cj_order,node_zendrop,node_admin toneIndigo
```

## Components

### Admin dashboard

- [Dashboard application](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Operations dashboard](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/DashboardPage.tsx): `client/src/pages/DashboardPage.tsx`
- [Order management](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/OrdersPage.tsx): `client/src/pages/OrdersPage.tsx`
- [Order inspection](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/OrderDetailPage.tsx): `client/src/pages/OrderDetailPage.tsx`
- [Catalog mappings](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/CatalogPage.tsx): `client/src/pages/CatalogPage.tsx`
- [Pricing rules](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/PricingRulesPage.tsx): `client/src/pages/PricingRulesPage.tsx`
- [Product sourcing](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/pages/SourcingPage.tsx): `client/src/pages/SourcingPage.tsx`
- [Order data hook](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/hooks/useOrders.ts): `client/src/hooks/useOrders.ts`
- [Order API client](https://github.com/jame2026/retailer-system-dropshipping/blob/main/client/src/services/orderService.ts): `client/src/services/orderService.ts`

### API and webhooks

- [Express API](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/app.ts): `server/app.ts`
- [Shopify webhook routes](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/webhooks/shopify.routes.ts): `server/routes/webhooks/shopify.routes.ts`
- [Webhook signature check](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/middleware/verifyShopifyHmac.ts): `server/middleware/verifyShopifyHmac.ts`
- [Webhook processing](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/webhook.controller.ts): `server/controllers/webhook.controller.ts`
- [Admin API routes](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/order.routes.ts): `server/routes/api/order.routes.ts`
- [Admin authentication](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/middleware/authAdmin.ts): `server/middleware/authAdmin.ts`
- [Order endpoints](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/order.controller.ts): `server/controllers/order.controller.ts`
- [Catalog routes](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/catalog.routes.ts): `server/routes/api/catalog.routes.ts`
- [Sourcing routes](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/routes/api/sourcing.routes.ts): `server/routes/api/sourcing.routes.ts`

### Order operations

- [Order lifecycle](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/order.service.ts): `server/services/order.service.ts`
- [Address normalization](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/utils/addressNormalizer.ts): `server/utils/addressNormalizer.ts`
- [PostgreSQL database](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/database/client.ts): `server/database/client.ts`
- [Six-hour hold worker](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/holdBuffer.worker.ts): `server/jobs/holdBuffer.worker.ts`
- [Billing retry job](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/retryBilling.job.ts): `server/jobs/retryBilling.job.ts`
- [Tracking sync job](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/jobs/trackingSync.job.ts): `server/jobs/trackingSync.job.ts`
- [Fulfillment sync](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/fulfillment.service.ts): `server/services/fulfillment.service.ts`

### Catalog and sourcing

- [Supplier SKU mapping](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/mapping.service.ts): `server/services/mapping.service.ts`
- [Dynamic pricing](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/services/pricing.service.ts): `server/services/pricing.service.ts`
- [Catalog endpoints](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/catalog.controller.ts): `server/controllers/catalog.controller.ts`
- [Sourcing endpoints](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/controllers/sourcing.controller.ts): `server/controllers/sourcing.controller.ts`

### Supplier and store integrations

- **Shopify**
- [CJ product sourcing](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/cj/cj.sourcing.ts): `server/integrations/cj/cj.sourcing.ts`
- [CJ order integration](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/cj/cj.order.ts): `server/integrations/cj/cj.order.ts`
- [Zendrop integration](https://github.com/jame2026/retailer-system-dropshipping/blob/main/server/integrations/zendrop/zendrop.client.ts): `server/integrations/zendrop/zendrop.client.ts`

### Other components

- **Administrator**

## Connections

- Administrator → Dashboard application: uses
- Shopify → Shopify webhook routes: sends events (evidence: `README.md`)
- Express API → Shopify webhook routes: mounts routes (evidence: `server/app.ts`)
- Shopify webhook routes → Webhook signature check: verifies requests (evidence: `server/routes/webhooks/shopify.routes.ts`)
- Shopify webhook routes → Webhook processing: routes events (evidence: `server/routes/webhooks/shopify.routes.ts`)
- Webhook processing → Order lifecycle: handles orders (evidence: `server/controllers/webhook.controller.ts`)
- Admin API routes → Admin authentication: protects endpoints (evidence: `server/routes/api/order.routes.ts`)
- Admin API routes → Order endpoints: routes requests (evidence: `server/routes/api/order.routes.ts`)
- Order endpoints → Order lifecycle: invokes operations (evidence: `server/controllers/order.controller.ts`)
- Order endpoints → PostgreSQL database: reads order detail (evidence: `server/controllers/order.controller.ts`)
- Order lifecycle → PostgreSQL database: reads and writes (evidence: `server/services/order.service.ts`)
- Order lifecycle → Address normalization: normalizes address (evidence: `server/services/order.service.ts`)
- Order lifecycle → Supplier SKU mapping: resolves SKUs (evidence: `server/services/order.service.ts`)
- Order lifecycle → CJ order integration: dispatches orders (evidence: `server/services/order.service.ts`)
- Order lifecycle → Zendrop integration: fallback dispatch (evidence: `server/services/order.service.ts`)
- Catalog routes → Catalog endpoints: routes requests (evidence: `server/routes/api/catalog.routes.ts`)
- Catalog endpoints → Supplier SKU mapping: manages mappings (evidence: `server/controllers/catalog.controller.ts`)
- Catalog endpoints → Dynamic pricing: calculates prices (evidence: `server/controllers/catalog.controller.ts`)
- Supplier SKU mapping → Dynamic pricing: calculates selling price (evidence: `server/services/mapping.service.ts`)
- Sourcing routes → Sourcing endpoints: routes requests (evidence: `server/routes/api/sourcing.routes.ts`)
- Sourcing endpoints → CJ product sourcing: searches and submits (evidence: `server/controllers/sourcing.controller.ts`)
- Six-hour hold worker → Order lifecycle: processes held orders (evidence: `server/jobs/holdBuffer.worker.ts`)
- Fulfillment sync → PostgreSQL database: reads and updates (evidence: `server/services/fulfillment.service.ts`)
- Fulfillment sync → CJ order integration: fetches tracking (evidence: `server/services/fulfillment.service.ts`)
- Fulfillment sync → Zendrop integration: fetches tracking (evidence: `server/services/fulfillment.service.ts`)
- Fulfillment sync → Shopify: pushes fulfillment (evidence: `server/services/fulfillment.service.ts`)
- Order data hook → Order API client: calls (evidence: `client/src/hooks/useOrders.ts`)
- Order API client → Express API: requests API
