Inventory Management

This page covers inventory tracking, stock reservations, adjustments, and multi-location transfers.

Stock Action Types

stateDiagram-v2
    direction LR

    state "Stock Actions" as actions {
        [*] --> INCREMENT: Add Stock
        [*] --> DECREMENT: Remove Stock
        [*] --> RESERVATION: Reserve for Order
        [*] --> RELEASE: Release Reservation
        [*] --> TRANSFER: Move Between Locations
        [*] --> ADJUSTMENT: Manual Adjustment
        [*] --> DAMAGED: Mark as Damaged
        [*] --> EXPIRED: Mark as Expired
        [*] --> LOST: Mark as Lost
        [*] --> FOUND: Mark as Found
    }

    note right of INCREMENT
        Sources: receiving,
        returns, found items
    end note

    note right of DECREMENT
        Sources: sales,
        damage, expiry
    end note

Stock Action State Machine

stateDiagram-v2
    [*] --> PENDING: Create Action

    PENDING --> PROCESSING: Start Processing
    PENDING --> CANCELLED: Cancel

    PROCESSING --> VALIDATED: Validation Pass
    PROCESSING --> REJECTED: Validation Fail

    VALIDATED --> COMPLETED: Apply Changes
    REJECTED --> PENDING: Retry

    COMPLETED --> [*]
    CANCELLED --> [*]

    note right of PROCESSING
        Checks: availability,
        permissions, rules
    end note

Order Stock Reservation Flow

sequenceDiagram
    participant Order as Order Service
    participant Inv as Inventory Service
    participant DB as Database
    participant Alert as Alert Service

    Order->>Inv: reserveStock(orderId, items)

    loop For each item
        Inv->>DB: Get current stock
        DB-->>Inv: Stock data

        Inv->>Inv: Check availability

        alt Stock Available
            Inv->>DB: Create StockAction (RESERVATION)
            Inv->>DB: Update reservedQuantity
            DB-->>Inv: Updated
        else Insufficient Stock
            Inv->>Alert: notifyLowStock(productId)
            Inv-->>Order: Partial availability
        end
    end

    Inv-->>Order: Reservation result

Stock Levels Explained

flowchart TD
    subgraph "Stock Quantities"
        PHYSICAL[Physical Quantity<br/>Total in warehouse]
        RESERVED[Reserved Quantity<br/>For pending orders]
        AVAILABLE[Available Quantity<br/>Physical - Reserved]
        USABLE[Usable Quantity<br/>Available - Damaged/Held]
    end

    PHYSICAL --> AVAILABLE
    RESERVED --> AVAILABLE
    AVAILABLE --> USABLE

    subgraph "Example"
        EX_PHYS[Physical: 100]
        EX_RES[Reserved: 20]
        EX_DAM[Damaged: 5]
        EX_AVAIL[Available: 80]
        EX_USE[Usable: 75]
    end

    EX_PHYS --> EX_AVAIL
    EX_RES --> EX_AVAIL
    EX_AVAIL --> EX_USE
    EX_DAM --> EX_USE

Stock Decrement on Fulfillment

sequenceDiagram
    participant Fulfill as Fulfillment Service
    participant Inv as Inventory Service
    participant DB as Database
    participant Sync as Sync Service

    Fulfill->>Inv: decrementStock(orderId, items)

    loop For each item
        Inv->>DB: Get reservation
        DB-->>Inv: Reservation data

        Inv->>DB: Create StockAction (DECREMENT)
        Inv->>DB: Decrease physicalQuantity
        Inv->>DB: Decrease reservedQuantity
        Inv->>DB: Release reservation
        DB-->>Inv: Updated

        Inv->>Inv: Check low stock threshold

        alt Below Threshold
            Inv->>DB: Create low stock alert
        end
    end

    Inv->>Sync: syncStockToChannels(items)
    Note over Inv,Sync: Update PrestaShop, WooCommerce

    Inv-->>Fulfill: Decrement complete

Inventory Transfer Flow

stateDiagram-v2
    [*] --> PENDING: Create Transfer

    PENDING --> APPROVED: Approve Transfer
    PENDING --> REJECTED: Reject Transfer

    APPROVED --> IN_TRANSIT: Pick & Ship
    IN_TRANSIT --> RECEIVING: Arrive at Destination
    RECEIVING --> COMPLETED: Confirm Receipt
    RECEIVING --> PARTIAL: Partial Receipt
    RECEIVING --> DISPUTED: Discrepancy Found

    PARTIAL --> COMPLETED: Receive Remaining
    DISPUTED --> COMPLETED: Resolved

    COMPLETED --> [*]
    REJECTED --> [*]

Transfer Sequence

sequenceDiagram
    participant Source as Source Location
    participant API as TRPC Router
    participant Service as Transfer Service
    participant DB as Database
    participant Dest as Destination Location

    Source->>API: createTransfer(items, destination)
    API->>Service: initiateTransfer(transfer)

    Service->>DB: Validate source stock
    DB-->>Service: Stock available

    Service->>DB: Create InventoryTransfer (PENDING)
    Service->>DB: Create TransferItems
    DB-->>Service: Transfer created

    Note over Service: Await approval

    Source->>API: approveTransfer(transferId)
    API->>Service: approveTransfer(transferId)
    Service->>DB: Update status (APPROVED)

    Service->>DB: Reserve stock at source
    DB-->>Service: Reserved

    Source->>API: markInTransit(transferId)
    API->>Service: startTransit(transferId)
    Service->>DB: Decrement source stock
    Service->>DB: Update status (IN_TRANSIT)

    Note over Service: Physical transport

    Dest->>API: receiveTransfer(transferId, items)
    API->>Service: completeTransfer(transferId, items)

    Service->>Service: Compare received vs expected

    alt All Items Received
        Service->>DB: Increment destination stock
        Service->>DB: Update status (COMPLETED)
    else Discrepancy
        Service->>DB: Log discrepancy
        Service->>DB: Update status (DISPUTED)
    end

    Service-->>API: Transfer result

Stock Adjustment Flow

flowchart TD
    START[Adjustment Needed] --> REASON{Reason?}

    REASON -->|Inventory Count| COUNT[Physical Count Difference]
    REASON -->|Damage| DAMAGE[Product Damaged]
    REASON -->|Expiry| EXPIRY[Product Expired]
    REASON -->|Loss| LOSS[Product Lost/Stolen]
    REASON -->|Found| FOUND[Product Found]
    REASON -->|System Error| ERROR[Data Correction]

    COUNT --> CREATE[Create Adjustment]
    DAMAGE --> CREATE
    EXPIRY --> CREATE
    LOSS --> CREATE
    FOUND --> CREATE
    ERROR --> CREATE

    CREATE --> APPROVAL{Needs Approval?}

    APPROVAL -->|Value > Threshold| REVIEW[Manager Review]
    APPROVAL -->|Value <= Threshold| AUTO[Auto-Approve]

    REVIEW --> DECISION{Decision}
    DECISION -->|Approve| APPLY
    DECISION -->|Reject| REJECT[Reject Adjustment]

    AUTO --> APPLY[Apply Adjustment]

    APPLY --> UPDATE[Update Stock Levels]
    UPDATE --> LOG[Log Action]
    LOG --> SYNC[Sync to Channels]

    style APPLY fill:#e8f5e9
    style REJECT fill:#ffebee

Multi-Location Stock Model

erDiagram
    PRODUCT ||--o{ PRODUCT_STOCK_AVAILABLE : tracked_in
    PRODUCT ||--o{ LOCATION_INVENTORY : has
    SHOP ||--o{ PRODUCT_STOCK_AVAILABLE : tracks
    WAREHOUSE ||--o{ LOCATION_INVENTORY : contains
    LOCATION ||--o{ LOCATION_INVENTORY : has

    PRODUCT_STOCK_AVAILABLE {
        string id PK
        string productId FK
        string shopId FK
        int quantity
        int physicalQuantity
        int reservedQuantity
        boolean outOfStock
    }

    LOCATION_INVENTORY {
        string id PK
        string productId FK
        string locationId FK
        string warehouseId FK
        int quantity
        int minQuantity
        int maxQuantity
        string binLocation
    }

    INVENTORY_TRANSFER ||--o{ INVENTORY_TRANSFER_ITEM : contains
    INVENTORY_TRANSFER {
        string id PK
        string fromLocationId FK
        string toLocationId FK
        enum status
        timestamp createdAt
        timestamp completedAt
    }

    STOCK_ACTION {
        string id PK
        string productId FK
        string locationId FK
        enum actionType
        enum source
        int quantityBefore
        int quantityChange
        int quantityAfter
        string reason
        timestamp createdAt
    }

Low Stock Alert Flow

flowchart TD
    DECREMENT[Stock Decremented] --> CHECK{Below Threshold?}

    CHECK -->|No| END1[No Action]
    CHECK -->|Yes| ALERT_TYPE{Alert Type?}

    ALERT_TYPE -->|Low Stock| LOW[Create Low Stock Alert]
    ALERT_TYPE -->|Out of Stock| OOS[Create Out of Stock Alert]
    ALERT_TYPE -->|Critical| CRITICAL[Create Critical Alert]

    LOW --> NOTIFY[Notify Purchasing Team]
    OOS --> NOTIFY
    CRITICAL --> URGENT[Urgent Notification]

    NOTIFY --> AUTO_ORDER{Auto-Order Enabled?}
    URGENT --> AUTO_ORDER

    AUTO_ORDER -->|Yes| CREATE_PO[Create Supplier Order]
    AUTO_ORDER -->|No| MANUAL[Manual Review]

    CREATE_PO --> SEND[Send to Vendor]

Batch/Lot Tracking

flowchart TD
    subgraph "Receiving"
        RECEIVE[Receive Shipment] --> ASSIGN[Assign Batch Number]
        ASSIGN --> RECORD[Record Lot Details]
        RECORD --> STOCK[Add to Stock]
    end

    subgraph "Tracking"
        STOCK --> FIFO[FIFO Queue]
        FIFO --> PICK[Pick Oldest First]
        PICK --> SHIP[Ship to Customer]
    end

    subgraph "Traceability"
        SHIP --> LINK[Link Batch to Order]
        LINK --> TRACE[Full Traceability]
    end

    subgraph "Expiry Management"
        RECORD --> EXPIRY[Set Expiry Date]
        EXPIRY --> MONITOR[Monitor Approaching]
        MONITOR --> ALERT[Alert Before Expiry]
        ALERT --> ACTION{Action}
        ACTION -->|Sell| DISCOUNT[Apply Discount]
        ACTION -->|Donate| DONATE[Donate]
        ACTION -->|Dispose| DISPOSE[Mark Expired]
    end

Stock Sync with External Channels

sequenceDiagram
    participant Inv as Inventory Service
    participant Queue as Sync Queue
    participant PS as PrestaShop Sync
    participant WC as WooCommerce Sync
    participant DB as Database

    Note over Inv: Stock changed

    Inv->>Queue: queueStockSync(productId)

    Queue->>PS: syncStock(productId)
    PS->>DB: Get current stock
    DB-->>PS: Stock data
    PS->>PS: Call PrestaShop API
    PS-->>Queue: Synced

    Queue->>WC: syncStock(productId)
    WC->>DB: Get current stock
    DB-->>WC: Stock data
    WC->>WC: Call WooCommerce API
    WC-->>Queue: Synced

    Queue->>DB: Update sync status

Inventory Valuation

flowchart LR
    subgraph "Valuation Methods"
        FIFO[FIFO<br/>First In First Out]
        LIFO[LIFO<br/>Last In First Out]
        AVG[Weighted Average]
        SPEC[Specific Identification]
    end

    subgraph "Calculations"
        COGS[Cost of Goods Sold]
        INV_VALUE[Inventory Value]
        MARGIN[Profit Margin]
    end

    FIFO --> COGS
    LIFO --> COGS
    AVG --> COGS
    SPEC --> COGS

    COGS --> MARGIN
    INV_VALUE --> MARGIN

Inventory Audit Trail

erDiagram
    STOCK_ACTION ||--|| PRODUCT : affects
    STOCK_ACTION }o--o| ORDER : references
    STOCK_ACTION }o--o| SUPPLIER_ORDER : references
    STOCK_ACTION }o--o| INVENTORY_TRANSFER : references
    STOCK_ACTION }o--|| USER : created_by

    STOCK_ACTION {
        string id PK
        string productId FK
        enum actionType
        enum source
        enum status
        int quantityBefore
        int quantityChange
        int quantityAfter
        string referenceType
        string referenceId
        string reason
        string notes
        string location
        string batchNumber
        timestamp createdAt
        string createdBy FK
    }

Cycle Count Process

flowchart TD
    SCHEDULE[Schedule Cycle Count] --> SELECT[Select Products/Locations]
    SELECT --> GENERATE[Generate Count Sheets]
    GENERATE --> ASSIGN[Assign to Staff]

    ASSIGN --> COUNT[Perform Physical Count]
    COUNT --> ENTER[Enter Counts]

    ENTER --> COMPARE[Compare to System]
    COMPARE --> VARIANCE{Variance?}

    VARIANCE -->|None| CONFIRM[Confirm Count]
    VARIANCE -->|Within Tolerance| ADJUST[Auto-Adjust]
    VARIANCE -->|Over Tolerance| RECOUNT[Recount Required]

    RECOUNT --> COUNT

    ADJUST --> CONFIRM
    CONFIRM --> COMPLETE[Mark Complete]
    COMPLETE --> REPORT[Generate Report]

    style COMPLETE fill:#e8f5e9

Inventory Management

On this page