Order System

Complete order management and workflow automation for logistics operations - from warehouse tasks to complex multi-stage fulfillment processes.

Order System Overview

De. Order System provides comprehensive order lifecycle management:

• Order Hierarchy - Parent-child relationships with full lineage tracking
• Lifecycle Validation - Enforced policies for completion, cancellation, failures
• Process-Stage Maps - Valid workflow transitions per order type
• Compensation Strategies - Automatic rollback and cleanup on failures
• Dual Operation Modes - Manual operations + optional pipeline automation
• Query Optimization - Denormalized descendants for fast hierarchy queries

Built for: 3PL providers, warehouse operations, fulfillment centers, delivery networks, and any logistics operation requiring order orchestration.

What is the Order System?

The order system is the central coordination engine for logistics operations. It manages the entire lifecycle of orders - from creation through completion or cancellation - while maintaining parent-child relationships, enforcing business rules, and handling failure scenarios automatically.

Unlike traditional order management systems that treat orders as isolated entities, De. recognizes that logistics operations involve complex hierarchies. A single customer order might spawn dozens of internal tasks (picking, packing, labeling, shipping) that must be coordinated, tracked, and managed as a cohesive unit.

Core Philosophy

1. Traditional System First The order system works perfectly as a manual operation tool. Create orders, update them, complete them - all through straightforward API calls without requiring any automation infrastructure.

2. Optional Automation Layer When you need automation, the pipeline system sits on top as an optional enhancement. Pipelines can auto-create child orders, transition stages, and handle failures - but the base system remains fully functional without them.

3. Validation at the Core Whether you're operating manually or using pipelines, the same validation layer enforces business rules. This prevents invalid state transitions, ensures parent-child consistency, and maintains data integrity.

Who Uses the Order System?

3PL/4PL Providers

• Multi-client warehouse operations
• Complex fulfillment workflows
• Inbound/outbound coordination
• Cross-dock operations

Warehouse Operations

• Receiving and put-away
• Picking and packing tasks
• Cycle counting and inventory
• Quality control processes

Fulfillment Centers

• E-commerce order processing
• Multi-SKU order assembly
• Kitting and bundling
• Returns processing

Distribution Networks

• Hub sortation workflows
• Cross-dock coordination
• Last-mile preparation
• Multi-leg shipping

Delivery Services

• Route planning integration
• Driver task management
• Proof of delivery
• Exception handling

Order Types

De. supports diverse order types for comprehensive logistics coverage:

Inbound Operations

Type	Description	Use Case
InboundOrder	External shipments arriving	Vendor deliveries, transfers, returns

Processes: RECEIVING, QUALITY_CHECK, PUT_AWAY, CROSS_DOCK

Outbound Operations

Type	Description	Use Case
OutboundOrder	Customer fulfillment orders	E-commerce, B2B shipments

Processes: FULFILLMENT (allocate → pick → pack → ship)

Internal Operations

Type	Description	Use Case
InternalOrder	Warehouse tasks	Picking, counting, moving, assembly

Processes: PICKING, PACKING, REPLENISHMENT, CYCLE_COUNT, RELOCATION, KITTING, ASSEMBLY

Shipping Operations

Type	Description	Use Case
ShippingOrder	Last-mile delivery	Driver assignments, route execution

Processes: PICKUP, TRANSIT, DELIVERY

Hub Operations

Type	Description	Use Case
PassthroughOrder	Cross-dock operations	No storage, direct routing
SortingOrder	Hub sortation	Package sorting by destination
CrossDockOrder	Transfer operations	Hub-to-hub transfers

Key Capabilities

Hierarchical Order Management

Build complex workflows with parent-child relationships:

OutboundOrder (OUT-001)
├── InternalOrder (PICK-001)  // Mandatory child
├── InternalOrder (PACK-001)  // Mandatory child
├── InternalOrder (LABEL-001) // Optional child
└── ShippingOrder (SHIP-001)  // Mandatory child

Features:

• Unlimited hierarchy depth (configurable limit)
• Parent-child relationship validation
• Automatic lineage tracking (root order reference)
• Composition metadata (why/when/how child was created)
• Denormalized descendants for fast queries

→ Learn More: Order Hierarchy

Lifecycle Validation

Enforce business rules for order state transitions:

Completion Rules:

• Can parent complete with pending children?
• Which child statuses are acceptable?
• Can child auto-trigger parent completion?

Cancellation Rules:

• Can parent cancel with active children?
• What happens to children? (cascade, orphan, suspend)
• Can children block parent cancellation?

Relationship Flags:

• canBlockParent - Does this child block parent completion?
• type - MANDATORY, OPTIONAL, CONDITIONAL

→ Learn More: Lifecycle Policies

Process-Stage Transitions

Validate workflow stages within each process:

// Outbound Fulfillment Process
ALLOCATION → PICKING → PACKING → SHIPPING → DELIVERY
   ✅ Valid    ✅ Valid   ✅ Valid    ✅ Valid
   ❌ Cannot skip stages
   ❌ Cannot go backwards (unless configured)

Features:

• Process-specific stage flows
• Invalid transition prevention
• Pipeline integration with validation
• Manual stage updates with checks

→ Learn More: Process-Stage Maps

Compensation & Rollback

Automatic failure handling with cleanup strategies:

On Child Failure:

• ROLLBACK_ALL - Cancel all siblings
• ROLLBACK_SIBLINGS - Cancel only active siblings
• COMPENSATE - Execute compensating actions
• MARK_FAILED - Mark parent as failed
• MANUAL_INTERVENTION - Require operator action
• IGNORE - Continue operation

On Parent Failure:

• Cancel active children
• Execute compensating actions
• Maintain audit trail

→ Learn More: Compensation Strategies

Dual Operation Modes

Manual Operations:

# Create order manually
POST /api/lsp/orders/tasks/create

# Update status manually
PATCH /api/lsp/orders/:ref/stage

# Complete with validation
PATCH /api/lsp/orders/:ref/complete

Pipeline Automation:

// Pipeline auto-creates children
// Auto-transitions stages
// Auto-handles failures
// All using the same validation layer

→ Learn More: Workflows

Architecture Highlights

Two-Layer Design

Base Order System (Always active)

• Order CRUD operations
• Lifecycle validation
• Process-stage validation
• Compensation execution
• Hierarchy management

Pipeline Layer (Optional)

• Workflow automation
• Auto-child creation
• Stage orchestration
• Failure recovery

Independent Validation

All validation logic lives in helper functions, not in routes:

// Used by both manual routes AND pipelines
canCompleteOrder(order, type, db, context)
isValidStageTransition(type, process, from, to)
compensateOnParentFailure(order, type, db, context)

This ensures consistency whether you're operating manually or through automation.

Denormalized Performance

Order hierarchies maintain denormalized descendant tracking:

{
  allDescendantReferences: ["PICK-001", "PACK-001", "SHIP-001"],
  descendantCount: 3,
  descendantsByType: {
    InternalOrder: ["PICK-001", "PACK-001"],
    ShippingOrder: ["SHIP-001"]
  }
}

Benefits:

• Single query to get all descendants (vs recursive queries)
• Fast "get all children" operations
• Efficient hierarchy reports
• 5-10x performance improvement

Getting Started

Workflow Overview

1

Understand Order Types

Choose the right order types for your operations

Review the order types that match your logistics operations:

• InboundOrder - Receiving operations
• OutboundOrder - Fulfillment operations
• InternalOrder - Warehouse tasks
• ShippingOrder - Delivery operations

→ See Order Types

2

Define Workflows

Map your operational processes

Identify your business processes and stages:

1. What are your main workflows? (receiving, picking, packing, etc.)
2. What are the stages within each process?
3. Which transitions are valid?
4. What are your completion/cancellation rules?

→ Review Process-Stage Maps

3

Configure Policies

Set up lifecycle and compensation rules

Define your business rules:

• Lifecycle policies (completion, cancellation)
• Compensation strategies (failure handling)
• Parent-child relationships

→ Lifecycle Policies→ Compensation Strategies

4

Start Operations

Create and manage orders

Begin with manual operations:

1. Create orders via API
2. Update stages and statuses
3. Complete or cancel with validation
4. Optional: Add pipeline automation later

→ Manual Workflows

Use Cases

E-Commerce Fulfillment

Scenario: Online retailer processing 1,000+ orders daily

Workflow:

OutboundOrder (Customer order)
├── InternalOrder (Picking task)
├── InternalOrder (Packing task)  
├── InternalOrder (Quality check)
└── ShippingOrder (Last-mile delivery)

Key Features:

• Auto-create child tasks from parent order
• Enforce sequential stages (can't pack before picking)
• Auto-complete parent when all children complete
• Cancel entire hierarchy if customer cancels

Services Used:

• Order hierarchy management
• Lifecycle validation
• Optional pipeline automation

Cross-Dock Operations

Scenario: Hub receiving shipments for immediate re-routing

Workflow:

InboundOrder (Receiving)
└── PassthroughOrder (Direct routing, no storage)
    ├── SortingOrder (Sort by destination)
    └── ShippingOrder (Outbound to next hub)

Key Features:

• Time-sensitive operations (no storage)
• Automatic child creation on inbound scan
• Real-time routing decisions
• Fast sortation workflows

Services Used:

• Process-stage transitions
• Compensation on routing failures
• Pipeline automation

Returns Processing

Scenario: E-commerce handling product returns

Workflow:

InboundOrder (Return received)
├── InternalOrder (Quality inspection)
├── InternalOrder (Restock or disposal)
└── OutboundOrder (Refund shipment if exchange)

Key Features:

• Conditional child creation (restock vs disposal)
• Optional children don't block completion
• Exception handling for damaged items
• Compensating actions on failures

Services Used:

• Conditional relationships
• Lifecycle policies
• Compensation strategies

Performance & Scale

Optimized for High Volume:

• 10,000+ orders per day per workspace
• Single-query hierarchy lookups
• Sub-second validation checks
• Automatic descendant tracking

Real-time Operations:

• Instant status updates
• WebSocket push notifications
• Low-latency API responses
• Concurrent order processing

Integration Patterns

Helper Functions

The order system provides reusable helper functions for common operations:

// Hierarchy management
createChildOrder(params, db, context)
updateAncestorsDescendants(db, context, parent, action, ref, type)

// Lifecycle validation  
canCompleteOrder(order, type, db, context)
canCancelOrder(order, type, db, context)

// Process-stage validation
isValidStageTransition(type, process, from, to)
getValidNextStages(type, process, currentStage)

// Compensation
compensateOnParentFailure(order, type, db, context)
compensateOnChildFailure(parent, failedChild, type, db, context)

→ Helper Functions Reference

Pipeline Integration

Pipelines use the same validation layer as manual operations:

// Pipeline creates child using same function
await createChildOrder({
  parentOrder,
  childOrderType: 'InternalOrder',
  creationReason: 'PIPELINE_STAGE',
  created: { by: { type: 'PIPELINE', id, name }, at },
  relationship: { type: 'MANDATORY', canBlockParent: true }
}, db, context)

// Same validation applies
const validation = await canCompleteOrder(order, type, db, context)

API Reference

For detailed API documentation including endpoints, request/response schemas, and examples, see the auto-generated Postman documentation.

Key Endpoint Categories:

• Order Management (/api/lsp/orders/*) - Lifecycle operations
• Type-Specific CRUD - Order creation and updates
• Helper Functions - Programmatic integration

Next Steps

Order HierarchyLifecycle PoliciesWorkflowsPipeline Automation

---

Related Services:

• Pipelines - Workflow Automation
• Inventory Management
• Shipment Tracking