Skip to content
Ordermatic Docs

Order Processing State Machine

This document describes the state machine for order processing from PDF extraction through ERP integration.

Overview

Section titled “Overview”

The order processing system manages orders through multiple states, from initial PDF extraction through final ERP submission. Each state represents a specific stage in the validation and approval workflow.

State Diagram

Section titled “State Diagram”
stateDiagram-v2
    [*] --> pending_review: PDF Extracted


    pending_review --> approved: User Approves
    pending_review --> rejected: User Rejects
    pending_review --> pending_review: User Edits


    approved --> submitted: ERP Success
    approved --> failed: ERP Error
    approved --> pending_review: Validation Error


    submitted --> [*]: Complete


    failed --> approved: Retry After Fix
    failed --> rejected: Abandon Order


    rejected --> [*]: Complete


    note right of pending_review
        Order awaiting human review
        - Customer validation
        - Item validation
        - Address validation
    end note


    note right of approved
        Order approved for ERP
        - All validations passed
        - Ready for submission
    end note


    note right of submitted
        Successfully in ERP
        - Order created
        - ERP order ID assigned
    end note


    note right of failed
        ERP submission failed
        - Network errors
        - Validation errors
        - Business rule violations
    end note

State Definitions

Section titled “State Definitions”

pending_review

Section titled “pending_review”

Description: Order extracted from PDF, awaiting human review and validation.

Entry Conditions:

  • PDF processing completed successfully
  • Order data extracted and stored
  • Initial validation checks passed

Available Actions:

  • Edit order details
  • Validate customer information
  • Validate shipping addresses
  • Validate line items
  • Approve for ERP submission
  • Reject order

Exit Conditions:

  • User approves → approved
  • User rejects → rejected
  • User makes edits → remains in pending_review

approved

Section titled “approved”

Description: Order approved by user, ready for ERP submission.

Entry Conditions:

  • User has approved the order
  • All required validations completed
  • Customer and shipping information validated

Available Actions:

  • Submit to ERP system
  • Return to review if validation fails

Exit Conditions:

  • ERP submission successful → submitted
  • ERP submission failed → failed
  • Validation error discovered → pending_review

submitted

Section titled “submitted”

Description: Order successfully submitted to ERP system.

Entry Conditions:

  • ERP API call successful
  • ERP order ID received
  • Order verification completed

Available Actions:

  • View ERP order details
  • Track order status in ERP

Exit Conditions:

  • Terminal state (order complete)

failed

Section titled “failed”

Description: ERP submission failed due to errors.

Entry Conditions:

  • ERP API call failed
  • Business rule violations
  • Network or authentication errors

Available Actions:

  • Retry submission after fixing issues
  • Return to approved state
  • Abandon order (reject)

Exit Conditions:

  • Issues resolved → approved
  • Order abandoned → rejected

rejected

Section titled “rejected”

Description: Order rejected and will not be processed.

Entry Conditions:

  • User explicitly rejects order
  • Order abandoned after failures
  • Invalid order data

Available Actions:

  • View rejection reason
  • Archive order

Exit Conditions:

  • Terminal state (order complete)

Validation Workflow

Section titled “Validation Workflow”
flowchart TD
    A[Order in pending_review] --> B{Customer Valid?}
    B -->|No| C[Show Customer Options]
    B -->|Yes| D{Shipping Valid?}


    C --> E[User Selects Customer]
    E --> D


    D -->|No| F[Show Shipping Options]
    D -->|Yes| G{Items Valid?}


    F --> H[User Selects Shipping]
    H --> G


    G -->|No| I[Show Item Validation]
    G -->|Yes| J[Enable Approval]


    I --> K[User Fixes Items]
    K --> G


    J --> L[User Approves]
    L --> M[State: approved]


    style A fill:#fff3e0
    style M fill:#c8e6c9
    style C fill:#ffecb3
    style F fill:#ffecb3
    style I fill:#ffecb3

Error Handling States

Section titled “Error Handling States”

Validation Errors

Section titled “Validation Errors”
graph TD
    A[Validation Error] --> B{Error Type}
    B -->|Customer Not Found| C[Show Customer Search]
    B -->|Shipping Invalid| D[Show Address Options]
    B -->|Item Not Found| E[Show Item Search]
    B -->|Price Mismatch| F[Show Price Confirmation]


    C --> G[User Action Required]
    D --> G
    E --> G
    F --> G


    G --> H[Return to pending_review]


    style A fill:#ffcdd2
    style G fill:#fff3e0
    style H fill:#e1f5fe

ERP Integration Errors

Section titled “ERP Integration Errors”
graph TD
    A[ERP Submission] --> B{Result}
    B -->|Success| C[State: submitted]
    B -->|Network Error| D[Retry Logic]
    B -->|Auth Error| E[Refresh Credentials]
    B -->|Validation Error| F[Return to Review]
    B -->|Business Rule Error| G[Show Error Details]


    D --> H{Retry Count < 3?}
    H -->|Yes| I[Exponential Backoff]
    H -->|No| J[State: failed]


    I --> A
    E --> A
    F --> K[State: pending_review]
    G --> J


    style C fill:#c8e6c9
    style J fill:#ffcdd2
    style K fill:#fff3e0

State Transitions

Section titled “State Transitions”

User-Initiated Transitions

Section titled “User-Initiated Transitions”
From State Action To State Conditions
pending_review Approve approved All validations passed
pending_review Reject rejected User decision
pending_review Edit pending_review User modifications
failed Retry approved Issues resolved
failed Abandon rejected User decision

System-Initiated Transitions

Section titled “System-Initiated Transitions”
From State Event To State Conditions
approved ERP Success submitted Order created in ERP
approved ERP Failure failed Submission error
approved Validation Error pending_review Data issues found

Audit Trail

Section titled “Audit Trail”

State Change Logging

Section titled “State Change Logging”
interface StateChangeLog {
  orderId: string;
  fromState: OrderState;
  toState: OrderState;
  timestamp: Date;
  userId?: string;
  reason?: string;
  errorDetails?: any;
  metadata?: Record<string, any>;
}

Tracking Requirements

Section titled “Tracking Requirements”
  • User Actions: All manual state changes logged
  • System Events: Automatic transitions recorded
  • Error Context: Detailed error information
  • Performance Metrics: State transition timing

Business Rules

Section titled “Business Rules”

Approval Requirements

Section titled “Approval Requirements”
  • Customer must be validated against ERP
  • Shipping address must be confirmed
  • All line items must be validated
  • Pricing must be within acceptable ranges
  • User must have approval permissions

Retry Logic

Section titled “Retry Logic”
  • Maximum 3 retry attempts for ERP submission
  • Exponential backoff between retries
  • Different retry strategies for different error types
  • Manual retry option for failed orders

Data Integrity

Section titled “Data Integrity”
  • State changes are atomic
  • Concurrent modifications prevented
  • Audit trail maintained for all changes
  • Rollback capability for failed transitions

Integration Points

Section titled “Integration Points”

Database Schema

Section titled “Database Schema”
  • extracted_orders.status: Current order state
  • extracted_orders.erp_workflow_status: ERP-specific status
  • extracted_orders.error_details: Error information
  • State change audit logs

External Systems

Section titled “External Systems”
  • ERP APIs: Order submission and validation
  • User Interface: State display and actions
  • Notification System: Status change alerts
  • Monitoring: State transition metrics

Performance Considerations

Section titled “Performance Considerations”
  • State Indexing: Efficient state-based queries
  • Batch Processing: Bulk state updates
  • Caching: Frequently accessed state data
  • Monitoring: State transition performance
Section titled “Related Architecture”