Guides & specifications

MMCA Business Workflow Analysis

Workflow List Summary

1. Identity Module Workflows

1.1 User Registration

Entry Point: POST /auth/register, AuthController.RegisterAsync(), AllowAnonymous

Execution Path:

AuthController.RegisterAsync()
  -> AuthenticationService.RegisterAsync()
    -> Repository: check email uniqueness
    -> PasswordHasher.HashPassword() (PBKDF2-HMAC-SHA512, 600k iterations, per-user salt)
    -> User.Create() factory method
    -> Repository.AddAsync() + UnitOfWork.SaveChangesAsync()
    -> [Domain Event] UserRegisteredHandler
      -> Customer.Create() (creates linked customer profile)
      -> User.LinkCustomer(customerId)
    -> TokenService.GenerateTokens()

Business Steps:

1. Validate registration input (email, password, first name, last name, optional address)
2. Check email is not already registered
3. Hash password with PBKDF2-HMAC-SHA512 (600,000 iterations, per-user salt)
4. Create User aggregate (IsActive=true, Role="Customer")
5. Persist user: triggers UserRegistered domain event
6. Domain event handler creates Customer profile and links it to User
7. Generate access token (15 min, JWT with claims: sub, jti, iat, user_id, email, role, customer_id) + refresh token (7 days, 64-byte random)
8. Return authentication response with tokens

Decision Points:

• Email already exists -> Conflict error
• Role="Admin" -> no Customer profile created; Role="Customer" -> Customer auto-created

State Changes:

• Creates User (Active, with RefreshToken and RefreshTokenExpiry)
• Creates Customer (linked via User.CustomerId)

Domain Events: UserRegistered -> triggers CustomerCreated

1.2 User Login

Entry Point: POST /auth/login, AuthController.LoginAsync(), AllowAnonymous

Execution Path:

AuthController.LoginAsync()
  -> AuthenticationService.LoginAsync()
    -> Repository: find User by email
    -> PasswordHasher.VerifyPassword() (constant-time comparison)
    -> Check User.IsActive
    -> TokenService.GenerateTokens()
    -> Update User.RefreshToken + RefreshTokenExpiry
    -> UnitOfWork.SaveChangesAsync()

Business Steps:

1. Look up user by email
2. Verify password against stored hash+salt
3. Verify user is active
4. Generate new access + refresh tokens
5. Store refresh token on user entity
6. Return tokens

Decision Points:

• Email not found -> Unauthorized
• Password mismatch -> Unauthorized
• User deactivated -> Unauthorized

State Changes: User.RefreshToken and User.RefreshTokenExpiry updated

1.3 Token Refresh

Entry Point: POST /auth/refresh, AllowAnonymous

Execution Path:

AuthController.RefreshAsync()
  -> TokenService.GetPrincipalFromExpiredToken() (validates structure, allows expired)
  -> Extract user_id claim -> fetch User
  -> Validate RefreshToken matches + not expired + user active
  -> Generate new tokens -> update User.RefreshToken
  -> SaveChangesAsync()

Decision Points:

• Invalid/expired refresh token -> Unauthorized
• User deactivated -> Unauthorized

State Changes: Refresh token rotated on User entity

1.4 Token Revocation

Entry Point: POST /auth/revoke, Requires Authorization

Business Steps: Clears User.RefreshToken and User.RefreshTokenExpiry to null.

1.5 Change Password

Entry Point: PUT /auth/password, Requires Authorization

Execution Path:

AuthController.ChangePasswordAsync()
  -> ChangePasswordHandler.Handle()
    -> Verify current password
    -> Hash new password
    -> User.ChangePassword() -> publishes UserPasswordChanged
    -> SaveChangesAsync()

Decision Points: Current password incorrect -> Bad Request

1.6 Customer Profile Management

Email change includes uniqueness check across customers.

1.7 Customer CRUD (Admin)

The controller is [Authorize(RequireAuthenticated)] with the collection reads and the create/delete actions individually raised to [Authorize(RequireAdmin)].

1.8 UI Preferences

1.9 Data Subject Rights (GDPR/CCPA)

Both endpoints authorize the account owner or an Admin, enforced in the handlers rather than by a controller-wide policy (ADR-005).

2. Catalog Module Workflows

2.1 Category Management

Create Category

Entry Point: POST /categories, Admin only, [Idempotent]

CategoriesController.CreateAsync()
  -> CreateCategoryHandler
    -> CategoryCreateRequestValidator (name: required, max 255)
    -> Category.Create(id, name, parentCategoryId?) -> publishes CategoryCreated
    -> Repository.AddAsync() + SaveChangesAsync()

Response: 201 Created with CategoryDTO

Rename Category

Entry Point: PUT /categories/{id}/name, Admin only

CategoriesController.RenameAsync()
  -> RenameCategoryHandler
    -> Validate name (max 255)
    -> Fetch category -> category.Rename(name)
    -> Only updates if name differs (case-insensitive comparison)
    -> Publishes CategoryNameChanged if changed
    -> Cache invalidation

Assign Parent Category

Entry Point: PUT /categories/{id}/parentcategory, Admin only

Sets or clears ParentCategoryId to establish hierarchy. No domain event raised.

Delete Category

Entry Point: DELETE /categories/{id}, Admin only

Soft delete (IsDeleted=true). Publishes CategoryDeleted.

Query Endpoints

2.2 Product Management

Create Product

Entry Point: POST /products, Admin only, [Idempotent]

ProductsController.CreateAsync()
  -> CreateProductHandler
    -> Validate: name (required, max 100), description (max 4000), brand (max 100, no whitespace if provided)
    -> Product.Create() factory -> publishes ProductCreated
    -> Repository.AddAsync() + SaveChangesAsync()

Update Operations

Delete Product

Entry Point: DELETE /products/{id}, Admin only. Soft delete, publishes ProductDeleted.

Query Endpoints

2.3 Product Variant Management

Add Product Variant

Entry Point: POST /products/{id}/productvariants, Admin only

ProductVariantsController.CreateAsync()
  -> AddVariantHandler
    -> Validate: SKU (max 50), Price (positive Money)
    -> IProductVariantService.SkuExistsAsync() -> global SKU uniqueness check
    -> Fetch Product with variants
    -> product.AddProductVariant(variantId, sku, price)
      -> ProductVariant.Create() validates price not negative
      -> Publishes ProductVariantAdded
    -> SaveChangesAsync()

Cross-Module: SKU uniqueness checked via IProductVariantService

Change Variant SKU

Entry Point: PUT /products/{id}/productvariants/{variantId}/sku, Admin only

SKU uniqueness verified globally (excluding current variant). Publishes ProductVariantSkuChanged if changed.

Change Variant Price

Entry Point: PUT /products/{id}/productvariants/{variantId}/price, Admin only

Price must be positive. Publishes ProductVariantPriceChanged if changed.

Remove Product Variant

Entry Point: DELETE /products/{id}/productvariants/{variantId}, Admin only

Soft delete on variant. Publishes ProductVariantRemoved.

2.4 Product Image Management

Behind the CatalogFeatures.ProductImages feature gate (ADR-031). Image binaries live as rows in the Catalog database (ProductImageData), not in managed blob storage: ADR-045 is the MMCA.ADC avatar amendment and is not adopted here, which is why the output cache below exists. Mutations require Admin; retrieval is anonymous and output-cached for 300 seconds to keep repeated BLOB reads off the database.

Every mutation evicts the products cache so the next read reflects the change.

3. Sales Module Workflows

3.1 Shopping Cart

Add Item to Cart

Entry Point: POST /shoppingcarts/{customerId}/shoppingcartitems, Authenticated (owner or admin via OwnerOrAdminFilter)

ShoppingCartsController.CreateShoppingCartItemAsync()
  -> AddItemHandler
    -> Validate quantity > 0
    -> IProductVariantService.ExistsAsync() [cross-module: Catalog]
    -> Fetch ShoppingCart by CustomerId
    -> If no cart exists -> ShoppingCart.Create(customerId) -> ShoppingCartCreated event
    -> If cart is CheckedOut -> shoppingCart.Reactivate() (clears items, resets to Active)
    -> shoppingCart.AddShoppingCartItem(variantId, quantity)
      -> If item already in cart -> IncreaseQuantity -> ShoppingCartItemQuantityAdjusted
      -> If new item -> ShoppingCartItem.Create() -> ShoppingCartItemAdded
    -> SaveChangesAsync()

Decision Points:

• Product variant doesn't exist -> NotFound
• Quantity not positive -> Invariant error
• Cart checked out -> auto-reactivated (all old items cleared)

Change Item Quantity

Entry Point: PUT /shoppingcarts/{id}/shoppingcartitems/{variantId}/quantity

Validates cart is Active, item exists, quantity > 0. Publishes ShoppingCartItemQuantityAdjusted.

Remove Item

Entry Point: DELETE /shoppingcarts/{id}/shoppingcartitems/{variantId}

Validates cart is Active. Soft-deletes item. Publishes ShoppingCartItemRemoved.

Clear Cart

Entry Point: PUT /shoppingcarts/{id}/clear

Deletes all items. Publishes ShoppingCartCleared.

Cart Query Endpoints

Ownership on the collection reads is enforced in the query, not against a route value: there is no owner parameter to compare, so the specification narrows the rows before they are read.

Shopping Cart Status State Machine

Active --(MarkAsCheckedOut)--> CheckedOut
  ^                                |
  +----(Reactivate on AddItem)-----+
        (clears all items)

3.2 Checkout (Cart to Order): Primary Business Workflow

Entry Point: PUT /shoppingcarts/{customerId}/checkout, authenticated, marked ICacheInvalidating. CheckOutCommand is deliberately NOT ITransactional (CheckOutCommand.cs:9): the handler opens its own transaction around the write phase only, so the cross-module price fetch never holds database locks.

ShoppingCartsController.CheckOutAsync()
  -> CheckOutHandler
    -> Fetch ShoppingCart with items (tracking)
    -> Collect productVariantIds from cart items
    -> IProductVariantService.GetUnitPricesAsync(ids) [cross-module: Catalog, OUTSIDE the transaction]
    -> Reject any variant missing from the price map (soft-deleted between add and checkout)
    -> Fetch InventoryItems for all variants
    -> CheckOutDomainService.Execute():
        1. Validate cart not empty
        2. Validate inventory exists for all items
        3. Fail-fast sufficiency check per item against the point-in-time snapshot
           (NOT the oversell guard: that is the atomic decrement below)
        4. Build order items (variant + price + quantity)
        5. Order.Create(customerId, items) -> publishes OrderPlaced
        6. shoppingCart.MarkAsCheckedOut() -> publishes ShoppingCartCheckedOut
    -> orderRepository.AddAsync(order)
    -> unitOfWork.ExecuteInTransactionAsync:            <-- the whole write phase, one transaction
         -> IInventoryAllocationService.DecrementAsync(decrements)
              atomic conditional UPDATE per variant (ExecuteUpdateAsync); a row that no longer has
              enough stock matches zero rows and fails the Result, rolling the transaction back
         -> unitOfWork.SaveChangesAsync()               <-- order insert + cart transition
    -> Return OrderDTO

Business Steps:

1. Validate cart exists and has items
2. Fetch current prices from Catalog module, and reject variants that no longer exist
3. Fail-fast inventory sufficiency check against the loaded snapshot
4. Create Order aggregate with OrderLines (price snapshot at time of purchase)
5. Transition cart to CheckedOut status
6. Commit the write phase in one explicit transaction: atomic inventory decrements, then the order insert and cart transition

Decision Points:

• Cart empty -> Validation error
• Product variant no longer exists in Catalog -> ProductVariant.NotFound, naming the offending variant
• Insufficient inventory at snapshot time -> Invariant error (fail-fast)
• Insufficient inventory at commit time -> the conditional UPDATE matches no row, the transaction rolls back
• Inventory record missing -> NotFound (specific missing variant ID reported)

State Changes:

• Creates Order (status: PendingPayment) with OrderLine children
• Decrements InventoryItem.AvailableQuantity for each item
• ShoppingCart.Status -> CheckedOut

Domain Events: OrderPlaced, ShoppingCartCheckedOut.

No InventoryAdjusted on the checkout path. The decrement runs as ExecuteUpdateAsync, which bypasses the save pipeline (and therefore the audit interceptor and domain-event dispatch) by design: that is what makes it a single atomic statement and the real oversell guard. InventoryAdjusted is still raised by the admin adjustment endpoints in 3.4, which go through the aggregate.

3.3 Order Lifecycle

Order Status State Machine

                    +------------------------------------------+
                    |                                          |
                    v                                          |
PendingPayment --> PaymentInitiated --> Paid -----------> Delivered
    |                    |               ^
    |                    |               |
    |                    v        (MarkAsPaidManually)
    |              PaymentFailed --------+
    |                    |
    |                    v (retry)
    |              PaymentInitiated
    |                    |
    v                    v
 Cancelled <------- Cancelled
(from PendingPayment, PaymentInitiated, or PaymentFailed)

Terminal States: Cancelled, Delivered

Create Stripe Checkout Session

Entry Point: POST /orders/{id}/checkout, Authenticated (owner or admin)

OrdersController.CreateCheckoutSessionAsync()
  -> CreateCheckoutSessionHandler
    -> Fetch Order with OrderLines
    -> IPaymentService.CreateCheckoutSessionAsync()
      -> StripePaymentService creates Stripe Checkout Session
      -> Converts Money to smallest currency unit (amount * 100)
      -> Sets success/cancel URIs, stores orderId in metadata
      -> Returns sessionId + checkoutUri
    -> order.InitiatePayment(sessionId)
      -> Validates status is PendingPayment or PaymentFailed
      -> Validates order not empty
      -> Sets StripeSessionId, status -> PaymentInitiated
      -> Publishes OrderPaymentInitiated
    -> SaveChangesAsync()
    -> Return sessionId + checkoutUri

External Interaction: Stripe API: creates payment session with order line items

Stripe Payment Webhook

Entry Point: POST /payments/webhook, AllowAnonymous, ITransactional, ICacheInvalidating

PaymentsController.HandleWebhookAsync()
  -> ProcessPaymentWebhookHandler
    -> IPaymentService.ParseWebhookEvent() (Stripe signature verification)
    -> Route by event type:

      checkout.session.completed:
        -> Find Order by StripeSessionId
        -> Idempotent: if already Paid, return success
        -> order.MarkAsPaid(paymentIntentId)
        -> Status -> Paid, publishes OrderPaid

      checkout.session.expired / payment_intent.payment_failed:
        -> Find Order by StripeSessionId
        -> Idempotent: if already PaymentFailed or Cancelled, return success
        -> order.MarkAsPaymentFailed()
        -> Status -> PaymentFailed, publishes OrderPaymentFailed

      Other events: silently ignored (returns success)

Idempotency: Already-paid or already-failed orders return success without modification.

Controller behavior: Returns 400 only for signature verification failures; returns 200 for all other cases (including handler errors) to prevent Stripe retries.

Manual Admin Payment

Entry Point: PUT /orders/{id}/pay, Admin only

Validates status allows manual payment (PendingPayment, PaymentInitiated, or PaymentFailed). Sets StripePaymentIntentId = "manual-admin-override", status -> Paid. Publishes OrderPaid.

Verify Payment (webhook backstop)

Entry Point: PUT /orders/{id}/verify-payment, owner or Admin (ownership validated in the controller)

Polls Stripe directly for the order's checkout session instead of waiting on a webhook, for the case where webhook delivery failed or is delayed. If Stripe reports the session paid, the order is marked Paid exactly as the webhook would have marked it; if the order is already Paid or is not in a verifiable state, the call succeeds without changes. This is the reconciliation half of ADR-054: the webhook is the fast path, this is the backstop that keeps a paid customer from sitting in PaymentInitiated forever.

Deliver Order

Entry Point: PUT /orders/{id}/deliver, Admin only

Validates status is Paid. Status -> Delivered. Publishes OrderDelivered.

Cancel Order

Entry Point: PUT /orders/{id}/cancel, Owner or Admin

OrdersController.CancelAsync()
  -> CancelOrderHandler
    -> Fetch Order with OrderLines
    -> order.MarkAsCancelled()
      -> Validates status is PendingPayment, PaymentInitiated, or PaymentFailed
      -> Status -> Cancelled, publishes OrderCancelled
    -> SaveChangesAsync()          <-- cancellation commits here; no inventory work inline

  (then, after commit)
  -> OrderCancelledSagaHandler  [ADR-054 compensating action, own DI scope]
    -> Skip if order.InventoryRestored is already set (idempotent under redelivery)
    -> Restore stock for each OrderLine
    -> order.MarkInventoryRestored()
    -> ONE SaveChangesAsync commits the marker and the inventory increases together

Inventory Impact: All reserved inventory is restored on cancellation, by a compensating handler that runs after the cancellation transaction, not inside it (ADR-054). Order.InventoryRestored is the idempotency marker, committed by the same SaveChangesAsync as the restoration, so an at-least-once redelivery cannot double-restore; the order's rowversion token makes two concurrent deliveries mutually exclusive. The sibling OrderPaymentFailedSagaHandler compensates the payment-failure path the same way. Splitting compensation out of CancelOrderHandler is what lets further compensating actions (refund, notification) be added as new handlers rather than edits.

Order Query Endpoints

3.4 Inventory Management

All mutation operations validate that the product variant exists via IProductVariantService and publish InventoryAdjusted when the quantity actually changes. IncreaseInventory and DecreaseInventory both route through SetInventory, which is the single place the event is raised.

The whole controller is [Authorize(Policy = RequireAdmin)]; there is no anonymous inventory read.

4. UI Workflows

4.1 Customer Shopping Experience (UI-Side)

The UI provides a complete shopping experience through the CartDrawer component and Blazor pages.

Cart Drawer (Sole Cart Interface)

The CartDrawer is the only cart UI: there is no dedicated cart page. It is a 380px right-side temporary drawer accessible from any page via the cart icon in the top app bar.

Features:

• View cart items with product name, SKU, and quantity
• Quantity +/- controls per item (when cart is Active)
• Remove individual items (when cart is Active)
• Clear all items
• Checkout & Pay (creates order + Stripe session, redirects to payment)
• "Checked Out" chip display when cart is not Active
• Read-only quantity display when cart is CheckedOut
• "Continue Shopping" navigation to catalog
• Empty cart state with "Browse Products" link

State Management: ICartStateService singleton manages cart state centrally: all cart operations go through this service which refreshes the cart DTO after each mutation and notifies subscribers via OnChange event. Cart items are enriched with product names and SKUs from the Catalog API.

Catalog Browse & Product Detail

• /catalog, Product grid with name search, category filter, name/newest sort, quick "Add to Cart" per variant
• /catalog/{id}, Product detail with breadcrumbs, variant list, quantity selector, "Add to Cart" button, "Buy Now" (direct Stripe checkout)

Order Management

• /orders, MudDataGrid listing orders with ID, customer, total, status chips, item count
• /orders/{id}, Two-column layout: order summary (status, total, payment/delivery actions) + order lines

4.2 Admin UI Workflows

4.3 User Profile & Auth

4.4 Navigation Structure

Sidebar Navigation (role-based, dynamically populated from IUIModule registrations):

Customer:

• Home (/)
• Shop (/catalog)
• My Orders (/orders)
• My Profile (/profile)

Admin:

• Home (/)
• Categories (/categories)
• Products (/products)
• Inventory (/inventory)
• Shopping Carts (/shoppingcarts)
• Orders (/orders)
• Customers (/customers)
• My Profile (/profile)

Top App Bar:

• Shopping cart icon with badge (authenticated, opens CartDrawer)
• User email display
• Logout button (authenticated)
• Login / Register buttons (anonymous)

5. Cross-Module Interactions

Module dependency: Sales declares a hard dependency on Catalog (RequiresDependencies = true). When Catalog is disabled, a DisabledProductVariantService stub is registered and Sales will fail to start.

6. External Interactions

7. Cross-Cutting Concerns Participating in Workflows

8. End-to-End Customer Journey

1. Register          POST /auth/register        -> User + Customer created, tokens issued
2. Browse Catalog    GET /products               -> View products with variants and prices
3. Add to Cart       POST /shoppingcarts/{id}/shoppingcartitems  -> Cart created/updated
4. Adjust Cart       PUT/DELETE cart items        -> Modify quantities or remove items
5. Checkout          PUT /shoppingcarts/{id}/checkout  -> Order created, inventory reserved
6. Pay               POST /orders/{id}/checkout   -> Stripe session created, redirect to payment
7. Payment Complete  POST /payments/webhook        -> Stripe confirms, order marked Paid
8. Delivery          PUT /orders/{id}/deliver      -> Admin marks as Delivered

Alternative Flows:

• Payment fails -> Order status PaymentFailed -> customer can retry (create new Stripe session)
• Cancel order -> Status Cancelled (from PendingPayment, PaymentInitiated, or PaymentFailed) -> inventory restored
• Cart reactivation -> Checked-out cart auto-reactivated on next add-item (all old items cleared)
• Manual payment -> Admin bypasses Stripe, sets StripePaymentIntentId = "manual-admin-override"

9. Potentially Missing or Incomplete Workflows

This document is derived from source code analysis. All workflows, decisions, and behaviors described above are confirmed implementations traceable to the referenced source files. Last updated: 2026-07-27 (re-verified against MMCA.Store HEAD 1dfdc991).