Beam Domain Context

What Is Beam?

Beam enables dropshipping by syncing products FROM Violet TO destination e-commerce platforms (Shopify) and processing orders back.

Beam vs Prism

| | Prism | Beam | |---|-------|------| | Direction | Read Products, Write Orders | Write Products, Read Orders | | Flow | Ingest products from stores → Create orders there | Publish Violet products to destinations → Read orders back | | Customer | Channels (marketplaces, platforms) | Destination merchants (dropshippers) | | End User | Merchants (suppliers) | Shoppers on destination stores |

Key Value Proposition: Enables destination merchants to dropship products from multiple Violet suppliers through their own Shopify stores without holding inventory.

Core Data Model

| Collection | Purpose | Key Fields | |------------|---------|------------| | Shops | Destination Shopify stores | shopId, accessToken, scopes | | Products | Published products | shopId, violetOfferId, shopifyProductId | | Variants | Product variants | sku, violetSkuId, shopifyVariantId | | Orders | Shopify orders | orderId, lineItems, fulfillmentStatus | | Fulfillments | Fulfillment tracking | orderId, trackingNumber, status | | Mappings | Variant SKU mappings | sourceSkuId, shopifyVariantId, confidence | | SyncLogs | Audit trail | timestamp, action, status, errors |

Core Temporal Workflows

| Workflow | Purpose | Trigger | |----------|---------|---------| | CatalogSyncWorkflow | Sync products to Shopify | Scheduled / manual | | ProductPublishWorkflow | Publish single product | API / event | | OrderProcessingWorkflow | Process Shopify order | Webhook | | FulfillmentWorkflow | Handle fulfillment updates | Violet event | | ReconciliationWorkflow | Fix data inconsistencies | Scheduled | | VariantMappingWorkflow | Resolve SKU mappings | On demand |

Key Principles

1. Reliability Over Speed

Beam's value is making dropshipping reliable:

• Order accuracy (right products, right quantities)
• Fulfillment tracking (customers know where orders are)
• Data consistency (Shopify ↔ Violet sync)

2. Self-Healing Systems

Design for automatic recovery:

• Reconciliation workflows detect and fix issues
• Confidence scoring for variant mappings
• Retry logic with exponential backoff
• Dead letter queues for failed webhooks

3. Shopify-First

Focus on Shopify until perfected:

• Deep integration (OAuth, webhooks, GraphQL)
• Handle all edge cases (partial fulfillment, cancellations, refunds)
• Stay current with Shopify API changes

4. Multi-Vendor Complexity

Single Shopify orders can have products from multiple Violet merchants:

• Split orders into multiple Violet bags
• Track fulfillment per line item
• Handle partial fulfillments gracefully

Key Metrics

| Metric | Target | Alert Threshold | |--------|--------|-----------------| | Order Success Rate | >98% | <95% | | Product Sync Latency | <5 min | >10 min | | Webhook Processing | <30s | >60s | | Fulfillment Accuracy | >99% | <97% | | Broken Mappings | <0.1% | >1% |

Key Repositories

| Repo | Purpose | |------|---------| | BeamService | Main backend service (Java 21, Spring Boot) | | BeamContextLibrary | Documentation & context | | beam-migrations | Database migrations | | beam-brain | Product brain (specs, strategy) |