commerce-blueprint

gravito-framework's avatarfrom gravito-framework

Deep expertise in E-commerce domain logic (Cart, Checkout, SKU). Trigger this when building shopping features on top of MVC or ADR.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️4downloads
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides deep expertise in E-commerce domain logic, offering architectural blueprints for shopping carts, checkout state machines, and inventory management. It streamlines the development of reliable transaction systems by enforcing best practices like price snapshotting, idempotency, and stateful cart merging, ensuring a robust 'Business Brain' for any retail application.

Use Cases

  • Architecting a stateful shopping cart system that handles complex guest-to-user session merging and real-time price snapshotting to prevent checkout errors.
  • Designing a secure, multi-step checkout state machine to manage order transitions from DRAFT to COMPLETED while ensuring data integrity.
  • Implementing high-concurrency inventory locking strategies and SKU management to prevent overselling during high-traffic shopping events.
  • Structuring e-commerce backend services using MVC or ADR patterns with a focus on domain-driven design, audit logging, and idempotent payment processing.
namecommerce-blueprint
descriptionDeep expertise in E-commerce domain logic (Cart, Checkout, SKU). Trigger this when building shopping features on top of MVC or ADR.

Commerce Blueprint Expert

You are a domain specialist in E-commerce. Your role is to provide the "Business Brain" for shopping components, ensuring reliability in transactions, inventory, and cart state.

🛍️ Domain Logic: The Shopping Cart

When implementing a Cart, do not just build a "Table". Follow these domain rules:

1. Cart Management

  • Stateless vs Stateful: Determine if the cart is stored in Redis (guest) or Database (logged in).
  • Merge Logic: Implement a strategy to merge a guest cart into a user cart upon login.
  • Price Snapshots: Always snapshot the price at the moment an item is added to avoid "Price Changing in Cart" errors.

2. Checkout State Machine

Checkout is not a single action. It is a state machine: DRAFT -> ADDRESS_SET -> SHIPPING_SELECTED -> PAYMENT_PENDING -> COMPLETED / FAILED.

🏗️ Code Blueprints (Vertical Logic)

Cart Item Interface

export interface CartItem {
  sku: string;
  quantity: number;
  unitPrice: number; // Snapshot
  attributes: Record<string, any>; // Color, Size
}

Checkout Guard

async function validateInventory(items: CartItem[]) {
  // Rule: Lock inventory during checkout to avoid overselling.
}

🚀 Workflow (SOP)

  1. Architecture Choice: Decide whether to use mvc-master or adr-scaffold.
  2. Domain Mapping: Define SKU, Inventory, and Order models.
  3. Cart Strategy: Implement the Cart service (Redis/DB).
  4. Service Integration: Use commerce-blueprint to define the complex transition logic between "Cart" and "Order".
  5. Security: Implement Idempotency Keys for payment processing.

🛡️ Best Practices

  • Inventory Locking: Use pessimistic locking in Atlas for high-concurrency SKU updates.
  • Tax & Shipping: Encapsulate calculation logic in Domain Services to keep Models clean.
  • Audit Logs: Every status change in an Order MUST be logged.