Cart ↔ Order Synchronization System

Overview

This document explains the synchronization workflow between Cart management, Commercial Orders, and Logistic Orders within the Nuxt 3 e-commerce B2B application. The system manages the complete order lifecycle from shopping cart to fulfillment.

Architecture Overview

The system supports multiple parallel carts per user, with each cart potentially becoming a complete order workflow:

graph TB
    subgraph "User Shopping Layer"
        Cart1[Cart 1 - INIT]
        Cart2[Cart 2 - ON_GOING]
        Cart3[Cart 3 - COMPLETED]
        CartN[Cart N...]
    end

    subgraph "Commercial Order Layer"
        CO1[Commercial Order 1]
        CO2[Commercial Order 2]
    end

    subgraph "Logistic Order Layer"
        LO1[Logistic Order 1A / DRAFT ORDER]
        LO2[Logistic Order 1B / DRAFT ORDER]
        LO3[Logistic Order 2A / CREATED]
    end



    Cart2 --> CO1
    Cart3 --> CO2
    CO1 --> LO1
    CO1 --> LO2
    CO2 --> LO3


    style Cart1 fill:#e1f5fe
    style Cart2 fill:#e1f5fe
    style Cart3 fill:#e1f5fe
    style CO1 fill:#f3e5f5
    style CO2 fill:#f3e5f5

Status Flow

• Cart: INIT → ON_GOING → COMPLETED
• Logistic Orders: DRAFT_ORDER → DRAFT_ORDER_ON_HOLD → CREATED

Workflow Process

The complete synchronization workflow managed by the Djust Back-end:

sequenceDiagram
    participant User as User
    participant Frontend as Nuxt Frontend
    participant API as Nuxt API Routes
    participant Backend as Djust Back-end
    participant DB as Database

    %% Phase 1: Cart Creation and Population
    User->>Frontend: Initialize Shopping
    Frontend->>API: createCart()
    API->>Backend: Create Cart Request
    Backend->>DB: Create Cart (Status: INIT)
    DB-->>Backend: Cart Created
    Backend-->>API: Cart Response
    API-->>Frontend: Cart Created
    Frontend-->>User: Display Cart

    User->>Frontend: Add/Modify Products
    Frontend->>API: addOrUpdateCartLines()
    API->>Backend: Update Cart Request
    Backend->>DB: Update Cart Lines
    DB-->>Backend: Cart Updated
    Backend-->>API: Updated Cart
    API-->>Frontend: Cart Response
    Frontend-->>User: Updated Cart Display

    %% Phase 2: Order Creation
    User->>Frontend: Proceed to Checkout
    Frontend->>API: createCommercialOrder()
    API->>Backend: Create Order Request

    Backend->>DB: Create Commercial Order (DRAFT)
    Backend->>DB: Create Logistic Orders (DRAFT_ORDER)
    Backend->>DB: Update Cart Status (INIT → ON_GOING)

    DB-->>Backend: Orders Created
    Backend-->>API: Order Response
    API-->>Frontend: Order Created
    Frontend-->>User: Order Summary

    %% Phase 3: Cart Modifications (Auto-sync)
    User->>Frontend: Modify Cart
    Frontend->>API: updateCartLines()
    API->>Backend: Update Request

    Backend->>DB: Update Cart
    Backend->>DB: Auto-sync Commercial Order
    Backend->>DB: Auto-sync Logistic Orders

    DB-->>Backend: All Updated
    Backend-->>API: Sync Response
    API-->>Frontend: Updated Data
    Frontend-->>User: Reactive Updates

    %% Phase 4: Order Confirmation
    User->>Frontend: Confirm Order
    Frontend->>API: setCommercialOrderStatusAsCreated() OR setLogisticOrderStatusAsCreated()
    API->>Backend: Confirmation Request

    alt Global Commercial Order Confirmation
        Backend->>DB: Commercial Order: DRAFT → CREATED
        Backend->>DB: ALL Logistic Orders: DRAFT_ORDER → DRAFT_ORDER_ON_HOLD
        Backend->>DB: Cart: ON_GOING → COMPLETED
    else Individual Logistic Order Confirmation
        Backend->>DB: Specific Logistic Order: DRAFT_ORDER → CREATED
        Backend->>DB: Check if all logistics confirmed
        alt All Confirmed
            Backend->>DB: Cart: ON_GOING → COMPLETED
        end
    end

    DB-->>Backend: Status Updated
    Backend-->>API: Confirmation Response
    API-->>Frontend: Order Confirmed
    Frontend-->>User: Confirmation Display

         Note over Backend: All status changes and object creation handled by Djust Back-end
     Note over Backend: Automatic synchronization between Cart, Commercial and Logistic Orders

Business Rules

Key Rules

1. Multiple Carts: Users can have multiple carts in parallel with different statuses
2. Status Flow: Cart (INIT → ON_GOING → COMPLETED) drives order creation and lifecycle
3. Auto-Synchronization: Cart modifications automatically update linked orders when status allows
4. Djust Back-end Control: All status changes and object creation managed by Djust Back-end
5. Confirmation Flexibility: Two confirmation paths (global commercial vs individual logistic)

Modification Rules

Confirmation Behavior

• setCommercialOrderStatusAsCreated(): All logistics → DRAFT_ORDER_ON_HOLD, Cart → COMPLETED
• setLogisticOrderStatusAsCreated(): Individual logistics → CREATED, Cart → COMPLETED only when all logistics confirmed