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) |
1---2name: beam3description: Beam dropshipping and product sync context4---5
6# Beam Domain Context
7
8## What Is Beam?
9
10Beam enables **dropshipping** by syncing products FROM Violet TO destination e-commerce platforms (Shopify) and processing orders back.
11
12### Beam vs Prism
13
14| | Prism | Beam |
15|---|-------|------|
16| **Direction** | Read Products, Write Orders | Write Products, Read Orders |
17| **Flow** | Ingest products from stores → Create orders there | Publish Violet products to destinations → Read orders back |
18| **Customer** | Channels (marketplaces, platforms) | Destination merchants (dropshippers) |
19| **End User** | Merchants (suppliers) | Shoppers on destination stores |
20
21**Key Value Proposition**: Enables destination merchants to dropship products from multiple Violet suppliers through their own Shopify stores without holding inventory.
22
23## Core Data Model
24
25| Collection | Purpose | Key Fields |
26|------------|---------|------------|
27| `Shops` | Destination Shopify stores | shopId, accessToken, scopes |
28| `Products` | Published products | shopId, violetOfferId, shopifyProductId |
29| `Variants` | Product variants | sku, violetSkuId, shopifyVariantId |
30| `Orders` | Shopify orders | orderId, lineItems, fulfillmentStatus |
31| `Fulfillments` | Fulfillment tracking | orderId, trackingNumber, status |
32| `Mappings` | Variant SKU mappings | sourceSkuId, shopifyVariantId, confidence |
33| `SyncLogs` | Audit trail | timestamp, action, status, errors |
34
35## Core Temporal Workflows
36
37| Workflow | Purpose | Trigger |
38|----------|---------|---------|
39| `CatalogSyncWorkflow` | Sync products to Shopify | Scheduled / manual |
40| `ProductPublishWorkflow` | Publish single product | API / event |
41| `OrderProcessingWorkflow` | Process Shopify order | Webhook |
42| `FulfillmentWorkflow` | Handle fulfillment updates | Violet event |
43| `ReconciliationWorkflow` | Fix data inconsistencies | Scheduled |
44| `VariantMappingWorkflow` | Resolve SKU mappings | On demand |
45
46## Key Principles
47
48### 1. Reliability Over Speed
49Beam's value is making dropshipping **reliable**:
50- Order accuracy (right products, right quantities)
51- Fulfillment tracking (customers know where orders are)
52- Data consistency (Shopify ↔ Violet sync)
53
54### 2. Self-Healing Systems
55Design for automatic recovery:
56- Reconciliation workflows detect and fix issues
57- Confidence scoring for variant mappings
58- Retry logic with exponential backoff
59- Dead letter queues for failed webhooks
60
61### 3. Shopify-First
62Focus on Shopify until perfected:
63- Deep integration (OAuth, webhooks, GraphQL)
64- Handle all edge cases (partial fulfillment, cancellations, refunds)
65- Stay current with Shopify API changes
66
67### 4. Multi-Vendor Complexity
68Single Shopify orders can have products from multiple Violet merchants:
69- Split orders into multiple Violet bags
70- Track fulfillment per line item
71- Handle partial fulfillments gracefully
72
73## Key Metrics
74
75| Metric | Target | Alert Threshold |
76|--------|--------|-----------------|
77| Order Success Rate | >98% | <95% |
78| Product Sync Latency | <5 min | >10 min |
79| Webhook Processing | <30s | >60s |
80| Fulfillment Accuracy | >99% | <97% |
81| Broken Mappings | <0.1% | >1% |
82
83## Key Repositories
84
85| Repo | Purpose |
86|------|---------|
87| `BeamService` | Main backend service (Java 21, Spring Boot) |
88| `BeamContextLibrary` | Documentation & context |
89| `beam-migrations` | Database migrations |
90| `beam-brain` | Product brain (specs, strategy) |
majiayu000