Systems Architecture¶

How PopSockets' systems connect. This is the 30,000-foot view — what talks to what, what data flows where, and why.

The Big Picture¶

Storefronts generate orders, OMS manages them, fulfillment partners ship them, and confirmations flow back. Product data comes from Arena PLM and fans out to every system that needs it. EDI handles the B2B retail channel. All inter-system communication runs through the Camel integration layer — it's the middleware, not shown here.

Mermaid¶

graph LR
    SFCC[SFCC / Shopify] --> OMS
    DISCO[Discopify] --> OMS
    JK[Jackyun] --> OMS

    OMS --> CIRRO[Cirro 3PL]
    OMS --> XB[XB 3PL]
    OMS --> PRINT[PrintStation]

    CIRRO --> OMS

    SPS[SPS Commerce] --> NAV[NAV ERP]
    NAV --> CIRRO
    CIRRO --> SPS
    CIRRO --> NAV

    ARENA[Arena PLM] --> OMS
    ARENA --> JK
    ARENA --> PRINT

    CIRRO --> SNOW[Snowflake]
    OMS --> SNOW
    OMS --> GLADLY[Gladly CRM]

Excalidraw¶

Architecture overview (Excalidraw)

Same flow, two rendering styles. Mermaid is text-first and auto-laid-out; Excalidraw is hand-laid with color and grouping. Pick whichever reads better for the thing you're documenting.

Order Flows¶

B2C — Direct to Consumer¶

Customer places an order on popsockets.com. It needs to get to Cirro for fulfillment.

sequenceDiagram
    participant Store as SFCC / Shopify
    participant OMS
    participant Cirro as Cirro 3PL

    Store->>OMS: New order
    OMS->>OMS: Validate, check inventory
    OMS->>Cirro: Fulfillment request

    Note over Cirro: Fulfillment begins

    Cirro->>OMS: Shipment confirmation

B2B — Retail / EDI¶

Retailer sends a purchase order (EDI 850). NAV generates the warehouse order (940). Cirro fulfills. Ship notices (856) go back to the retailer, shipping advice (945) goes back to NAV.

sequenceDiagram
    participant SPS as SPS Commerce
    participant NAV
    participant Cirro as Cirro 3PL

    SPS->>NAV: 850 Purchase Order
    NAV->>NAV: Generate 940 warehouse order
    NAV->>Cirro: 940 fulfillment request

    Note over Cirro: Fulfillment & shipping

    Cirro->>SPS: 856 Advance Ship Notice
    Cirro->>NAV: 945 Shipping Advice

China — Jackyun / KH¶

Orders from the China market flow through the Jackyun/Qimen API and get routed to the XB 3PL.

sequenceDiagram
    participant JK as Jackyun (Qimen)
    participant OMS
    participant XB as XB 3PL

    JK->>OMS: New orders (polled every 5 min)
    OMS->>XB: Fulfillment request

Custom Print¶

Custom/personalized orders go through the batching system before hitting PrintStation.

sequenceDiagram
    participant OMS
    participant PS as PrintStation

    OMS->>PS: Orders grouped into batches
    PS->>PS: Print production
    PS->>OMS: Batch complete

Product Data Flow¶

Product information originates in Arena PLM and fans out to every system that needs it.

sequenceDiagram
    participant Arena as Arena PLM
    participant OMS
    participant PS as PrintStation
    participant JK as Jackyun (China)

    Arena->>OMS: Item updates
    Arena->>PS: Print batching updates
    Arena->>JK: SKU sync to China warehouse

Inventory Flow¶

Snowflake pulls inventory data from Cirro through the integration layer.

sequenceDiagram
    participant Snow as Snowflake
    participant Cirro as Cirro 3PL

    Snow->>Cirro: Request inventory history
    Cirro-->>Snow: Inventory data (via Blob staging)

Systems Reference¶

Storefronts & Order Sources¶

System	What It Does	Protocol
SFCC (Salesforce Commerce Cloud)	popsockets.com storefront	REST API → OMS
Shopify	Additional storefront	REST API → OMS
Discopify	B2B order portal	REST API → OMS
Jackyun / KH China	China market orders via Qimen API	REST API, polled every 5 min

Order Management¶

System	What It Does	Protocol
OMS / OSOR	Central order management — validation, inventory, status	REST API (Diff Agency hosted)
Gladly	Customer service CRM, pulls order details from OMS	REST API via cm-osor-sys

Fulfillment¶

System	What It Does	Protocol
Cirro	Primary 3PL (China-based fulfillment)	REST API via cm-cirro-sys
XB	Secondary 3PL (China/Jackyun orders)	REST API
PrintStation	Custom print production	REST API via cm-printprod-sys

ERP & EDI¶

System	What It Does	Protocol
NAV (Dynamics NAV)	ERP — generates 940s from 850s, receives 945 ship advice	SOAP over HTTPS
SPS Commerce	Retailer EDI gateway — 850 inbound, 856 outbound	SFTP (port 10022)
PS SFTP	Internal file exchange for NAV and EDI documents	SFTP (10.45.0.100:22)

Product & Data¶

System	What It Does	Protocol
Arena PLM	Product lifecycle management — source of truth for items	REST API (session-based auth)
Snowflake	Data warehouse — ingests order and inventory data	JDBC (JWT auth)
Azure Data Explorer	Operational analytics and audit logging	REST API (Kusto ingest)

Infrastructure¶

System	What It Does	Protocol
Azure Service Bus	Message backbone — topics per flow per environment	AMQP
PostgreSQL	Persistent storage — EDI docs, order tracking	JDBC
Azure Blob Storage	EDI document archive and bulk data staging	REST API
Hazelcast	Distributed cache — Arena tokens, locking	In-memory clustering

Notifications¶

System	What It Does	Protocol
Microsoft Teams	Alerts for EDI processing, order errors	Webhook (Power Automate)
Image Validator	AI-powered image classification for custom prints	REST API (OAuth)

Integration Microservices¶

The integration layer is a set of Camel-based microservices in the cm-* namespace. Each has a specific role:

Service	Role
cm-edi-prc	EDI document processing — 850/940/856/945 generation, SFTP polling, routing
cm-order-prc	Order routing and transformation — determines B2B vs pre-pack, batching
cm-fulfill-prc	Fulfillment request handling — decrypts, transforms, sends to 3PL
cm-ext-service-exp	External webhook receiver — Cirro shipment confirmations
cm-int-service-sys	Internal service layer — DB operations, watermarks, audit logging
cm-cirro-sys	Cirro API proxy — adds auth, routes to Cirro endpoints
cm-osor-sys	OMS proxy — order confirmation, Gladly integration
cm-product-sys	Arena PLM wrapper — item events, specs, search
cm-product-prc	Product distribution — fans Arena updates to downstream systems
cm-jackyun-sys	Jackyun/Qimen API wrapper — order polling, product sync
cm-batching-prc	Batch processing — groups custom print orders
cm-printprod-sys	Print production proxy — sends batches to PrintStation
cm-snowflake-sys	Snowflake integration — inventory data pipeline