Order & Inventory MCP — Real-Time Orders and Stock

flowchart TD
    TC([Tool Call]) --> RT{Data type?}

    RT -->|Real-time\norder status / stock| LP[Live Path]
    RT -->|Policy / FAQ\norder-related question| RP[RAG Path]

    LP --> EC{ElastiCache\nCache hit?}
    EC -->|HIT TTL=30s| CR([Cached Result])
    EC -->|MISS| RDS[(RDS Aurora\norder_items · inventory)]
    RDS --> WC[Write cache TTL=30s]
    WC --> LR([Live Result])

    RP --> EB[Embed Question\nTitan v2]
    EB --> OS[(OpenSearch\nPolicy Doc Index)]
    OS --> RK[Rerank]
    RK --> PR([Policy Result])

    style TC fill:#4A90D9,color:#fff
    style CR fill:#27AE60,color:#fff
    style LR fill:#27AE60,color:#fff
    style PR fill:#27AE60,color:#fff
    style RT fill:#8E44AD,color:#fff

-- Orders table
SELECT o.order_id, o.status, o.created_at,
       oi.manga_id, oi.volume_number, oi.quantity, oi.unit_price,
       s.carrier, s.tracking_number, s.estimated_delivery
FROM orders o
JOIN order_items oi ON o.order_id = oi.order_id
LEFT JOIN shipments s ON o.order_id = s.order_id
WHERE o.user_id = :user_id
ORDER BY o.created_at DESC
LIMIT 10;

CACHE_TTL = {
    "order_status":  30,   # seconds — orders change infrequently once shipped
    "stock_level":   10,   # seconds — inventory is high-frequency
    "price":         300,  # seconds — prices stable within 5 min window
    "shipping_eta":  120,  # seconds — carrier estimates refresh slowly
}

sequenceDiagram
    participant Claude
    participant OrderMCP
    participant Redis
    participant Aurora
    participant Kinesis

    Claude->>OrderMCP: check_stock(manga_id="BER42", volume=42)
    OrderMCP->>Redis: GET stock:BER42:42
    alt Cache HIT
        Redis-->>OrderMCP: {quantity: 14, warehouse: "TKY-1"}
        OrderMCP-->>Claude: In stock · 14 units · ships from Tokyo
    else Cache MISS
        OrderMCP->>Aurora: SELECT quantity FROM inventory WHERE ...
        Aurora-->>OrderMCP: {quantity: 14}
        OrderMCP->>Redis: SET stock:BER42:42 TTL=10s
        OrderMCP->>Kinesis: Publish stock_check_event (analytics)
        OrderMCP-->>Claude: In stock · 14 units · ships from Tokyo
    end

stateDiagram-v2
    [*] --> Placed
    Placed --> PaymentPending
    PaymentPending --> Confirmed : Payment success
    PaymentPending --> Cancelled : Payment failed / timeout
    Confirmed --> Packed
    Packed --> Shipped
    Shipped --> OutForDelivery
    OutForDelivery --> Delivered
    Shipped --> DeliveryFailed
    DeliveryFailed --> ReturnInitiated
    Delivered --> [*]
    Cancelled --> [*]
    ReturnInitiated --> Refunded
    Refunded --> [*]

@app.tool()
async def get_price(manga_id: str, volume_number: int | None = None) -> dict:
    """
    Returns current retail price and discount status for a manga volume.
    NEVER infer or estimate prices — always return from this tool.
    """
    price = await aurora.fetch_price(manga_id, volume_number)
    if price is None:
        return {
            "status": "not_found",
            "message": f"Price unavailable for manga_id={manga_id}. Do not estimate.",
            "manga_id": manga_id,
        }
    return {
        "status": "found",
        "price_jpy": price.amount,
        "currency": "JPY",
        "discount_active": price.discount_pct > 0,
        "discount_pct": price.discount_pct,
        "valid_until": price.valid_until.isoformat(),
    }

flowchart LR
    Q([e.g. 'Can I cancel a\npre-order?']) --> EB[Embed\nTitan v2]
    EB --> OS[(OpenSearch\nPolicy Docs)]
    OS --> HY[Hybrid Retrieval\nBM25 + kNN]
    HY --> RK[Rerank]
    RK --> CH[Context chunk\nwith policy text + version]
    CH --> TR([Tool Result\nPolicy answer + source URL])

    style Q fill:#4A90D9,color:#fff
    style TR fill:#27AE60,color:#fff