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