---
name: beam
description: Beam dropshipping and product sync context
---

# 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) |