Guides & specifications

MMCA Business Specification Document

As of: 2026-09-07.

1. System Overview

MMCA is an e-commerce platform built with .NET 10.0 using DDD and Clean Architecture. The business logic is organized as modules (Catalog, Sales, Identity) that have been extracted into per-module service hosts behind a YARP Gateway. It enables customers to browse a product catalog, manage shopping carts, place orders, and process payments. Administrators manage the product catalog, inventory, and order fulfillment.

The system operates in the online retail / e-commerce domain, supporting the full purchase lifecycle from product browsing through payment and delivery.

Major Business Areas:

• Product Catalog Management: categories, products, and product variants with pricing
• Shopping & Ordering: cart management, checkout, order placement
• Payment Processing: Stripe-integrated checkout with webhook confirmation
• Order Fulfilment: carrier shipment tracking from payment through delivery
• Inventory Management: stock tracking per product variant
• Product Reviews: verified-purchase star ratings and reviews, with moderation
• Customer Identity & Authentication: registration, login, JWT-based sessions

Technical Stack:

• .NET 10.0 (LangVersion: preview), Blazor Server + WebAssembly hybrid (InteractiveAuto), MudBlazor UI
• SQL Server (primary, via Aspire), SQLite, Cosmos DB (alternative, via strategy pattern)
• Stripe payment gateway, PBKDF2-HMAC-SHA512 password hashing, JWT authentication
• .NET Aspire orchestration (SQL Server container + Gateway :6001 + 3 service hosts + UI)

2. Core Business Entities

2.1 Category

Description: A classification grouping for products. Supports hierarchical (parent-child) structures for nested categorization (e.g., "Jewelry" > "Rings").

Key Properties:

Relationships:

• A Category may have one parent Category (self-referencing hierarchy)
• A Category contains zero or more Products

Source: Source/Modules/Catalog/MMCA.Store.Catalog.Domain/Categories/Category.cs

2.2 Product

Description: A saleable item in the catalog. Products have descriptive attributes and belong to a category. Each product has one or more purchasable variants.

Key Properties:

Relationships:

• A Product belongs to zero or one Category
• A Product contains one or more Product Variants

Source: Source/Modules/Catalog/MMCA.Store.Catalog.Domain/Products/Product.cs

2.3 Product Variant

Description: A specific purchasable configuration of a product (e.g., "Gold Ring - Size 7"). Variants carry the actual price and SKU used for inventory and order processing.

Key Properties:

Relationships:

• A Product Variant belongs to exactly one Product
• A Product Variant has zero or one Inventory Item
• A Product Variant can appear in Shopping Cart Items and Order Lines

Source: Source/Modules/Catalog/MMCA.Store.Catalog.Domain/Products/ProductVariant.cs, Source/Modules/Catalog/MMCA.Store.Catalog.Shared/Products/VariantDiscount.cs

2.4 Shopping Cart

Description: A temporary collection of items a customer intends to purchase. Each customer has exactly one shopping cart (the cart ID equals the customer ID).

Key Properties:

Relationships:

• A Shopping Cart belongs to exactly one Customer (1:1 relationship, ID = CustomerId)
• A Shopping Cart contains zero or more Shopping Cart Items

Source: Source/Modules/Sales/MMCA.Store.Sales.Domain/ShoppingCarts/ShoppingCart.cs

2.5 Shopping Cart Item

Description: A line item in a shopping cart, representing a desired quantity of a specific product variant.

Key Properties:

Relationships:

• Belongs to exactly one Shopping Cart
• References one Product Variant (cross-module)

Source: Source/Modules/Sales/MMCA.Store.Sales.Domain/ShoppingCarts/ShoppingCartItem.cs

2.6 Order

Description: A confirmed purchase transaction created when a customer checks out their shopping cart. Orders track payment status and progress through a defined lifecycle.

Key Properties:

Relationships:

• An Order belongs to one Customer
• An Order contains one or more Order Lines

Source: Source/Modules/Sales/MMCA.Store.Sales.Domain/Orders/Order.cs

2.7 Order Line

Description: A single item within an order, capturing the product variant, quantity, and price at time of purchase.

Key Properties:

Relationships:

• Belongs to exactly one Order

Source: Source/Modules/Sales/MMCA.Store.Sales.Domain/Orders/OrderLine.cs, Source/Modules/Sales/MMCA.Store.Sales.Domain/Orders/OrderLinePricing.cs

2.8 Inventory Item

Description: Tracks available stock for a specific product variant. One inventory record per product variant (the inventory item ID equals the product variant ID).

Key Properties:

Relationships:

• One Inventory Item per Product Variant (1:1 relationship, ID = ProductVariantId)

Source: Source/Modules/Sales/MMCA.Store.Sales.Domain/Inventory/InventoryItem.cs

2.9 Customer

Description: A registered buyer with personal information and optional mailing address.

Key Properties:

Relationships:

• A Customer is linked 1:1 with a User account
• A Customer has one Shopping Cart
• A Customer has zero or more Orders

Source: Source/Modules/Identity/MMCA.Store.Identity.Domain/Customers/Customer.cs

2.10 User

Description: An authentication account with credentials and role-based access. Users are either administrators or customers.

Key Properties:

Relationships:

• A User with "Customer" role is linked 1:1 to a Customer entity
• Admin users have no Customer record

Source: Source/Modules/Identity/MMCA.Store.Identity.Domain/Users/User.cs

2.11 Value Objects

2.12 Product Review

Description: A shopper's review of a product: a star rating plus optional headline and text, written by a customer who received the product. Every review is a verified purchase by construction, so the aggregate carries no "verified" flag of its own.

Key Properties:

Relationships:

• One review per (customer, product); the entitling order is recorded on the row
• Counted into the product's RatingSummary while published and not deleted

Erasure: the aggregate is IAnonymizable (ADR-005). Anonymizing clears the reviewer name, title and body and keeps the rating, because a bare star with no name and no words identifies nobody while removing it would silently rewrite every product average an erasure touched.

Source: Source/Modules/Catalog/MMCA.Store.Catalog.Domain/Reviews/ProductReview.cs

2.13 Verified Purchase

Description: Catalog's own record that a customer received a product: one row per (order, product). It is the entitlement behind a review, so "verified purchase" is answerable without a query into Sales.

Key Properties:

Relationships:

• Written only by the consumer of Sales' OrderFulfilled integration event; nothing else creates one and nothing revokes one (delivery is terminal, so an entitlement earned stays earned)
• Unique on (OrderId, ProductId), which is the database-level backstop for an at-least-once redelivery

Carries no personal data (three identifiers and a date), so it is deliberately neither audited nor anonymizable, and it is deliberately not repeated in the data-subject export: it is a derived copy of order facts Sales already owns and already exports.

Source: Source/Modules/Catalog/MMCA.Store.Catalog.Domain/Reviews/VerifiedPurchase.cs

3. Business Workflows

3.1 Customer Registration

Trigger: A new user submits registration with first name, last name, email, and password.

Steps:

1. Validate registration request (email format, password requirements)
2. Verify email is not already registered (uniqueness check)
3. Hash the password using PBKDF2-HMAC-SHA512 (600,000 iterations) with a per-user salt
4. Create a User entity with "Customer" role
5. Generate JWT access token (15 min, with claims: sub, jti, iat, user_id, email, role, customer_id) and refresh token (7-day expiry, 64-byte random)
6. Domain event UserRegistered is published, which triggers automatic Customer creation:
   • A new Customer entity is created with the same name, email, and address
   • The User is linked to the newly created Customer via CustomerId
7. Return authentication tokens to the caller

Implemented in:

• Source/Modules/Identity/MMCA.Store.Identity.Application/Users/AuthenticationService.cs (RegisterAsync)
• Source/Modules/Identity/MMCA.Store.Identity.Application/Users/DomainEventHandlers/UserRegisteredHandler.cs

3.2 Customer Login

Trigger: A registered user submits email and password.

Steps:

1. Validate login request
2. Look up user by email
3. Verify password using PBKDF2-HMAC-SHA512 with constant-time comparison (legacy HMAC-SHA512 hashes still verify via salt-length detection)
4. Verify user is active
5. Generate new access token and refresh token
6. Update refresh token expiry (7 days from now)
7. Return authentication response with both tokens

Implemented in:

• Source/Modules/Identity/MMCA.Store.Identity.Application/Users/AuthenticationService.cs (LoginAsync)

3.3 Add Item to Shopping Cart

Trigger: An authenticated customer adds a product variant to their cart.

Steps:

1. Validate the request (quantity must be positive)
2. Verify the product variant exists in the Catalog (cross-module check via IProductVariantService)
3. Fetch or create the customer's shopping cart
4. If the cart was previously checked out, reactivate it (clears all old items, sets status back to Active)
5. If the same product variant already exists in the cart, increase its quantity
6. Otherwise, add a new cart item
7. Persist changes

Business Rules Applied:

• Cart must be in Active status to accept items (or will be reactivated)
• Product variant must exist in the catalog
• Quantity must be greater than zero
• Duplicate variants merge (quantities are combined)
• Reactivation clears all previous items

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/ShoppingCarts/UseCases/AddItem/AddItemHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Domain/ShoppingCarts/ShoppingCart.cs (AddShoppingCartItem)

3.4 Checkout (Cart to Order)

Trigger: A customer initiates checkout on their active shopping cart.

Steps:

1. Fetch the customer's shopping cart with all items
2. Retrieve current pricing for all product variants from the Catalog module (cross-module call): the effective price, the list price it was struck from, and the active promotion's label
3. Fetch inventory items for all product variants
4. Reject the checkout if any variant is missing from the price map (it was soft-deleted between cart-add and checkout), naming the offending variant
5. Execute the checkout domain service which: a. Validates the cart is not empty b. Validates inventory exists for every item in the cart c. Runs a fail-fast sufficiency check per item against the loaded snapshot d. Creates Order Lines with the current pricing triple (price snapshot at time of purchase) e. Creates the Order with status PendingPayment f. Transitions the cart to CheckedOut status
6. Commit the write phase inside one explicit transaction: the atomic conditional inventory decrements first, then the order insert and cart transition
7. Return the Order details

Business Rules Applied:

• Cart must contain at least one item
• Every product variant must still exist in the Catalog module
• All product variants must have corresponding inventory records
• Sufficient inventory must be available for each item
• Prices are locked at checkout time (not at cart-add time)
• The price locked is the effective price: Catalog resolves each variant's list price against any active discount at the instant of the call, so the order line, the receipt and the Stripe total all carry the discounted amount and Sales never reasons about promotions (ADR-112)
• The list price and the promotion label are frozen beside the effective price on the same line, so the order can say what it saved later without asking Catalog again. Only the effective price is money owed: the line total, the order total and the Stripe amount all follow from it alone
• The write phase is atomic, but the command is deliberately not ITransactional: the handler opens the transaction itself so the cross-module price fetch stays outside it and cross-service latency never extends lock hold time

Concurrency: the domain service's sufficiency check reads a point-in-time snapshot and is only a fail-fast. The real oversell guard is IInventoryAllocationService.DecrementAsync, which issues one atomic conditional UPDATE per variant: a row that no longer has enough stock matches zero rows, the Result fails, and the whole transaction rolls back. Because that path uses ExecuteUpdateAsync it bypasses the save pipeline, so no InventoryAdjusted domain event is raised on checkout.

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/ShoppingCarts/UseCases/CheckOut/CheckOutHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Domain/Services/CheckOutDomainService.cs
• Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Services/InventoryAllocationService.cs

3.5 Payment Processing (Stripe)

Trigger: After checkout, the customer initiates payment for a pending order.

Steps:

1. Fetch the order with its order lines
2. Call Stripe API to create a checkout session (converts Money to smallest currency unit: cents)
3. Transition order status to PaymentInitiated
4. Store the Stripe session ID on the order
5. Return the checkout URL for the customer to complete payment

Webhook Confirmation (asynchronous):

1. Stripe sends a webhook notification to POST /payments/webhook
2. System verifies the webhook signature using Stripe's EventUtility.ConstructEvent()
3. Based on event type:
   • checkout.session.completed -> Mark order as Paid, store payment intent ID
   • checkout.session.expired or payment_intent.payment_failed -> Mark order as PaymentFailed
4. Idempotent: skips processing if order is already in the appropriate terminal state

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/CreateCheckoutSession/CreateCheckoutSessionHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/ProcessPaymentWebhook/ProcessPaymentWebhookHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Services/StripePaymentService.cs

3.6 Order Cancellation

Trigger: A customer or admin cancels an order.

Steps:

1. Fetch the order with its order lines
2. Validate the order is in a cancellable state (PendingPayment, PaymentInitiated, or PaymentFailed)
3. Transition order status to Cancelled and persist. The cancellation commits on its own; no inventory work happens inside this transaction.
4. After the commit, the OrderCancelled domain event drives OrderCancelledSagaHandler, which runs in its own DI scope and restores inventory for each order line

Business Rules Applied:

• Orders in PendingPayment, PaymentInitiated, or PaymentFailed can be cancelled
• Paid or delivered orders cannot be cancelled (no refund workflow)
• Inventory is restored by a compensating handler, not inline (ADR-054)
• Restoration is idempotent under at-least-once redelivery: Order.InventoryRestored is the marker, and it is committed by the same SaveChangesAsync as the inventory increases. The order's rowversion token makes two concurrent deliveries mutually exclusive; the loser fails and the outbox retry then sees the committed marker.

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/Cancel/CancelOrderHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/Saga/OrderCancelledSagaHandler.cs

3.7 Manual Payment Override

Trigger: An administrator manually marks an order as paid (e.g., for cash payments or payment system issues).

Steps:

1. Fetch the order
2. Validate order status allows manual payment (PendingPayment, PaymentInitiated, or PaymentFailed)
3. Set payment intent ID to "manual-admin-override"
4. Transition status to Paid
5. Persist changes

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/Pay/PayOrderHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Domain/Orders/Order.cs (MarkAsPaidManually)

3.8 Order Shipping and Delivery

Trigger: An administrator records that a paid order left with a carrier, corrects what was recorded, or confirms the order arrived.

Ship (PUT /Orders/{id}/ship, OrdersManage permission, mandatory If-Match):

1. Fetch the order
2. Validate status is Paid (the only state that may ship)
3. Build the Shipment value object: carrier, tracking number, ship date, optional estimated delivery
4. Transition status to Shipped and raise OrderShipped
5. Persist changes; the domain-event handler emails the customer the carrier, the tracking number and the tracking link

Correct the shipment (PUT /Orders/{id}/shipment, OrdersManage permission, mandatory If-Match): Same request body, because the shipment is a value object and a correction replaces it whole rather than patching a field. Allowed from Shipped only, and the status does not move. OrderShipped is raised again on purpose, so a customer who was told the wrong tracking number gets the right one. The two verbs stay separate endpoints deliberately: ship must refuse an already-shipped order, the correction must refuse an order that never shipped, and folding them together would make "silently re-ship" indistinguishable from "fix the tracking number".

Deliver (PUT /Orders/{id}/deliver, OrdersManage permission, mandatory If-Match):

1. Fetch the order
2. Validate status is Paid or Shipped (the carrier leg is optional; see the state machine)
3. Transition status to Delivered, stamp FulfilledPublishedOn, and raise both the in-process OrderDelivered domain event and the OrderFulfilled integration event carrying the delivered line snapshot
4. Persist changes; OrderFulfilled leaves through the outbox and Catalog turns it into the verified-purchase entitlements behind product reviews (Section 3.13)

Tracking links: for UPS, FedEx, USPS and DHL the public link is computed from the carrier's own template plus the tracking number, so the URL is written down in exactly one place; only the Other carrier accepts a caller-supplied absolute https URL, and supplying one for a known carrier is refused rather than stored as a second copy that could contradict the template.

Backfill: OrderFulfilledBackfillService is a settings-gated, bounded one-shot startup sweep that publishes OrderFulfilled for orders that reached Delivered before the event existed, which is the only way those customers can ever review what they demonstrably bought. Order.FulfilledPublishedOn is the marker: the sweep selects only Delivered orders where it is still null, and the marker and the outbox row commit in the same unit of work, so a run converges, every later start is a no-op, and a host that dies mid-sweep resumes where it stopped.

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/Ship/ShipOrderHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/UpdateShipment/UpdateShipmentHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/Deliver/DeliverOrderHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/DomainEventHandlers/OrderShippedHandler.cs
• Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Persistence/Backfill/OrderFulfilledBackfillService.cs

3.9 Payment Verification (webhook backstop)

Trigger: The customer (or an admin) asks the system to re-check a payment whose webhook never arrived, typically from a "Retry / check payment" affordance on the order.

Steps:

1. Validate ownership (owner or admin)
2. Query Stripe directly for the order's checkout session
3. If Stripe reports the session paid, mark the order Paid exactly as the webhook path would
4. If the order is already Paid, or is not in a verifiable state, succeed without changes

Business Rules Applied:

• Webhooks are the fast path but are not guaranteed; this is the reconciliation backstop that keeps a paid customer from sitting in PaymentInitiated indefinitely (ADR-054)
• The operation is idempotent by construction: it converges the order onto whatever Stripe says

Implemented in:

• Source/Modules/Sales/MMCA.Store.Sales.Application/Orders/UseCases/VerifyPayment/VerifyPaymentHandler.cs

3.10 Product Images

Trigger: An administrator manages the image collection on a product; any visitor views one.

Behind the CatalogFeatures.ProductImages feature gate. Image binaries are stored as rows in the Catalog database (ProductImageData, written through ProductImageStorageService), NOT in managed blob storage: ADR-045 records the BR-116 amendment for MMCA.ADC avatars and MMCA.Store does not adopt it here. IProductImageStorageService is deliberately storage-agnostic, so moving to blob storage later is an infrastructure swap rather than a handler change. Uploads are capped at 6 MB of request body (the 5 MB domain constraint plus multipart overhead). Reads are anonymous and output-cached for 300 seconds; every mutation evicts the products cache. Both a legacy single-image route set (/image) and the current collection route set (/images) are exposed, sharing one upload handler. Reordering reassigns display order from the supplied id list, and the first id becomes the primary image.

Implemented in:

• Source/Modules/Catalog/MMCA.Store.Catalog.API/Controllers/ProductImagesController.cs

3.11 Data Subject Rights (GDPR/CCPA)

Trigger: A user exports or erases their own account data; an administrator does it on their behalf.

Export returns the personal data held for the user in a portable JSON format. Erasure deletes the account and irreversibly anonymizes its personal data, which is distinct from the soft-delete used for ordinary lifecycle (ADR-005). Both endpoints authorize the owner or an Admin, enforced in the handlers rather than by a controller-wide policy.

Implemented in:

• Source/Modules/Identity/MMCA.Store.Identity.API/Controllers/UsersController.cs

3.12 Password Reset

Trigger: A customer who cannot sign in asks for a reset link from /forgot-password, then sets a new password on /reset-password.

Steps (request):

1. POST /Auth/forgot-password with { "email": "..." }. The request validator checks the shape of the address only
2. Look up the account behind the address without tracking it
3. Increment the per-address request counter and check it against the rolling-hour throttle
4. Mint a 256-bit single-use token, store only its SHA-256 hash under the address with the configured TTL, and hand the raw token back
5. Email the reset link ({PasswordReset:ResetUrl}?email=...&token=...) plus the raw token, so a client that cannot follow a deep link can have the token entered by hand
6. Return HTTP 202 Accepted, which is also what an unknown address, a throttled address and a failed email send return: the response never discloses whether an address holds an account

Steps (reset):

1. POST /Auth/reset-password with { "email": "...", "token": "...", "newPassword": "..." }. The new password goes through the same strength rules registration uses
2. Validate the presented token against the stored hash in constant time and consume it before any write, so it cannot be redeemed twice
3. Load the account, hash the new password (PBKDF2-HMAC-SHA512), and apply it through the aggregate
4. Persist, then clear the account's login brute-force counters so a customer who was locked out can sign in immediately
5. Return HTTP 204 No Content. Every rejection (unknown, expired, replayed, mismatched or attempt-capped token, or an unresolvable account) collapses to one generic Auth.InvalidResetToken HTTP 401

Both endpoints are anonymous by necessity (the caller has lost the credential), carry the auth-ip per-IP rate limit that login and register carry, and are idempotent. They live on their own controller routed to the same Auth prefix, which the Gateway's /Auth/{**catch-all} route already forwards.

No schema change: the token lifecycle lives entirely in the cache, so expired tokens are reaped by cache TTL rather than by a sweeper and the feature ships without a migration. A cache eviction invalidates outstanding tokens, which costs the user one more request. See ADR-091.

Implemented in:

• Source/Modules/Identity/MMCA.Store.Identity.API/Controllers/PasswordResetController.cs
• Source/Modules/Identity/MMCA.Store.Identity.Application/Users/UseCases/ForgotPassword/ForgotPasswordHandler.cs
• Source/Modules/Identity/MMCA.Store.Identity.Application/Users/UseCases/ResetPassword/ResetPasswordHandler.cs

3.13 Product Reviews

Trigger: A customer who received a product rates it; anyone reads the ratings; a moderator hides a review that should not be public.

Aggregates: ProductReview (Section 2.12) and VerifiedPurchase (Section 2.13), both in the Catalog module, with the derived RatingSummary on Product.

Entitlement (the verified-purchase rule): a review can only be written by a customer who holds a VerifiedPurchase for the product. Those rows are minted by Catalog's consumer of Sales' OrderFulfilled integration event, one per (order, product): the event names variants, because that is all Sales knows, and Catalog resolves them to products and de-duplicates, so the entitlement is "you received this product", not "you received this variant". A variant Catalog cannot resolve is logged and skipped rather than failing the whole order's entitlements. Delivered, not Paid, is the trigger on purpose: it is terminal and never reversed, so an entitlement never needs revoking.

Submission rules: the submit handler enforces the two checks the aggregate cannot make for itself, because both read rows outside it: no entitlement fails with Review.NotVerifiedPurchase, and a second review of the same product by the same customer fails with Review.AlreadyReviewed rather than landing as a unique-index violation. The entitling row also supplies the order the review is filed against (the lowest order id, the earliest entitlement). The reviewing customer and the frozen display name both come from the caller's validated token, never from the body.

Rating summary: every review transition (submitted, revised, hidden, unhidden, anonymized, removed) raises the ProductReviewChanged domain event, and the handler recomputes the product's average and count from its published, non-deleted reviews rather than adjusting them incrementally, so a lost or redelivered event still converges on the right numbers.

Moderation: reviews publish immediately (there is no approval queue). A moderator holding the catalog:reviews:moderate permission can hide a review and restore it; hidden reviews leave the storefront and drop out of the rating summary. Hide and unhide are conditional writes on the same terms as every other review write (ADR-035), so two moderators acting on the same stale list cannot silently overwrite each other.

Erasure: Catalog consumes Identity's CustomerErased and anonymizes every review that customer wrote, soft-deleted and hidden rows included. The name, title and body are cleared and the rating is kept (ADR-005, PRIVACY.md section 5). Because the rating does not move, erasure disturbs no product average.

Export: the reviews a customer wrote are a section of the data-subject export document, served by Catalog through the IUserCatalogExportService cross-module contract and aggregated by Identity's GET /Users/{userId}/export (Section 3.11). Hidden reviews are included: a moderator's decision does not stop the text from being the subject's own data. The verified-purchase rows are deliberately not exported, because they duplicate order facts Sales already exports.

Endpoints:

A caller who is not the owner is answered 404 rather than 403, so the existence of another customer's review id cannot be probed for. Every mutation evicts the catalog:products output-cache tag, because a review moves the stars the product reads carry. The Gateway forwards /Reviews/** to the Catalog cluster (catalog-reviews route).

Field rules: rating 1 to 5, title at most 120 characters, body at most 2,000, frozen reviewer name at most 201; title and body are both optional and a review with neither is a bare star rating.

Implemented in:

• Source/Modules/Catalog/MMCA.Store.Catalog.API/Controllers/ReviewsController.cs
• Source/Modules/Catalog/MMCA.Store.Catalog.Application/Reviews/UseCases/
• Source/Modules/Catalog/MMCA.Store.Catalog.Application/Reviews/IntegrationEventHandlers/OrderFulfilledHandler.cs
• Source/Modules/Catalog/MMCA.Store.Catalog.Application/Reviews/IntegrationEventHandlers/CustomerErasedHandler.cs
• Source/Modules/Catalog/MMCA.Store.Catalog.Application/Reviews/DomainEventHandlers/ProductReviewChangedHandler.cs

4. Order Status State Machine

                    +------------------------------------------+
                    |                                          |
                    v                                          |
 +-----------------+----+    InitiatePayment    +--------------+------+
 |   PendingPayment     |--------------------->|  PaymentInitiated    |
 +----------------------+                      +---------------------+
        |       ^                                    |           |
        |       |                                    |           |
        |       +------------ PaymentFailed <--------+           |
        |                    (can retry)                         |
        |                         |                              |
   MarkAsCancelled           MarkAsCancelled               MarkAsPaid
        |                         |                       (webhook or manual)
        v                         v                              |
 +--------------+                                    +-----------+-----+
 |  Cancelled   | <---- MarkAsCancelled ------------ |      Paid       |
 +--------------+   (from PaymentInitiated)          +-----------------+
                                                          |       |
                                                        Ship      |
                                                          |       |
                                                          v       |
                                                  +-----------+   |
                                                  |  Shipped  |   | MarkAsDelivered
                                                  +-----------+   | (no carrier leg)
                                                          |       |
                                                   MarkAsDelivered|
                                                          |       |
                                                          v       v
                                                     +-----------------+
                                                     |    Delivered    |
                                                     +-----------------+

 UpdateShipment is a self-transition on Shipped: it replaces the recorded
 shipment and re-raises OrderShipped without moving the status.

Cancellable States: PendingPayment, PaymentInitiated, PaymentFailed. Shipped is deliberately NOT cancellable, for the same reason Paid is not: the goods and the money have both already moved. Shippable States: Paid (only) Shipment-correctable States: Shipped (only) Deliverable States: Paid, Shipped. The carrier leg is optional: a fulfilment with no tracking to record still goes Paid -> Delivered directly, which is why Paid keeps both outgoing edges. Manual Payment States: PendingPayment, PaymentInitiated, PaymentFailed Terminal States: Cancelled, Delivered

The OrderStatus numeric values are persisted and travel on the user_sales_export gRPC contract, so members are only ever appended: Shipped is last in the enum even though it sits mid-lifecycle.

5. Business Rules

5.1 Product & Catalog Rules

5.2 Shopping Cart Rules

5.3 Order Rules

5.4 Inventory Rules

5.5 Identity & Authentication Rules

6. Use Cases

Customer-Facing

Administrator-Facing

7. Domain Events and State Changes

Most mutations raise a single {Entity}Changed lifecycle event carrying a DomainEntityState discriminator (Added, Updated, Deleted) rather than one event per verb (ADR-083). Those events derive from EntityChangedEvent<TId>; the remaining ones are business events that name a specific transition and derive from BaseDomainEvent. The Kind / State column below says which is which, and the states a given event actually reaches. Every event listed is a real record type under the module's Domain/{Aggregate}/DomainEvents/ folder.

Catalog Events

Variant-level changes raise no Catalog domain event at all: adding, removing, re-pricing and re-SKU-ing a variant all signal through the ProductVariantChanged integration event described below. Setting a variant discount, clearing one, and applying one across a whole product do the same, each raising ProductVariantChanged with the Updated state and the variant's list price. The event contract does not grow a discount field: its consumers denormalize catalog labels and stock rows and none of them price anything, so a consumer that ever needs what a shopper pays asks IProductVariantService.GetUnitPricesAsync, which answers with the effective price, the list price it was struck from and the active promotion's label (ADR-112).

Sales Events

Identity Events

Integration Events (cross-service)

The events above are in-process domain events. These four cross the service boundary through the outbox and the message broker, and each one is a signal for the consumer to create or refresh a denormalized copy IT owns, never a prompt to query back into the publisher (ADR-006). Contracts live in the publisher's Shared layer, so a consumer never references the publisher's Domain. Their payloads are frozen by IntegrationEventContractTests in the architecture test project, which fails on any member added, removed or retyped without a new contract version.

8. External Integrations

8.1 Stripe Payment Gateway

Purpose: Processes online customer payments for orders.

Business Impact: Enables the system to collect payments from customers and confirm payment success or failure asynchronously via webhooks.

Integration Points:

• Checkout Session Creation: Creates hosted payment pages with order details, converting internal Money values to Stripe's smallest currency unit (cents). Maps order lines to Stripe line items with product name, quantity, and unit amount.
• Webhook Processing: Receives and verifies payment status notifications using Stripe's signature verification (EventUtility.ConstructEvent()). Handles checkout.session.completed, checkout.session.expired, and payment_intent.payment_failed events.
• Error Handling: Stripe API errors return Result.Failure with code "Payment.Stripe.SessionCreationFailed". Signature verification failures return "Payment.SignatureVerification.Failed".
• Configuration: Stripe API key (SecretKey) and webhook secret (WebhookSecret) configured per environment via StripeSettings (user secrets recommended).

Source: Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Services/StripePaymentService.cs

8.2 SMTP Email Service

Purpose: Infrastructure for sending email notifications.

Business Impact: Provides the capability for system-to-user communication.

Configuration:

• Host, Port (default 25), Username, Password, EnableSsl, From, To
• Default: localhost:25 with SSL disabled

Source: Source/Common/MMCA.Common.Infrastructure/Services/SmtpEmailSender.cs

Consumers: the forgot-password handler (Section 3.12) sends the reset email through IEmailSender, alongside the Sales domain-event handlers OrderPaidHandler, OrderShippedHandler (carrier, tracking number and tracking link, re-sent on every correction to the recorded shipment) and OrderPaymentFailedSagaHandler. Every one of those resolves the customer's contact details through ICustomerService and treats a send failure as non-fatal: the order transition is already committed before the handler runs. On the reset path delivery is awaited but never fatal: a send failure is logged and the request still answers 202, because reporting it would be an enumeration oracle, and the token stays live so the customer can retry.

9. Authorization Model

Permission-based endpoints: an endpoint states the capability it needs with [HasPermission(...)] over a constant from the owning module's {Module}Permissions, and each module grants those to roles in its API DependencyInjection (Admin holds all of them today). The shipment endpoints (PUT /Orders/{id}/ship, PUT /Orders/{id}/shipment) carry sales:orders:manage alongside pay and deliver; the review moderation surface (GET /Reviews/paged, PUT /Reviews/{id}/hide, PUT /Reviews/{id}/unhide) carries catalog:reviews:moderate.

Writing a review needs a customer profile, not a role. The reviews controller resolves the caller through the customer_id claim and fails closed when the token carries none; admins are deliberately not exempted, because writing a review is an act by a customer and an admin account with no customer profile has nothing to write one as.

Ownership Enforcement: The OwnerOrAdminFilter validates that the route parameter id (CustomerIdentifierType) matches the authenticated user's customer ID, or that the user has the Admin role. Applied to shopping cart and order endpoints. Returns 403 Forbidden if unauthorized.

JWT Claims: Access tokens contain: sub, jti, iat, user_id, email, role, and customer_id (when applicable).

10. Cross-Module Communication

The system enforces strict module boundaries. Modules communicate only through shared interface contracts:

Across process boundaries these interfaces are satisfied by gRPC clients, resolved through service discovery (ADR-007). Both export edges out of Identity are best-effort: an unreachable peer degrades that one section of the export rather than failing the export, so neither carries a startup wait.

Confirmed behaviors:

• Sales module cannot directly access Catalog domain entities
• When Catalog module is disabled, a stub DisabledProductVariantService is registered
• Sales module declares a hard dependency on Catalog (RequiresDependencies = true): it will not start without Catalog
• Module discovery uses reflection; registration follows topological dependency order (Kahn's algorithm)

11. User Interface

11.1 Technology

The UI is a Blazor Server + WebAssembly hybrid (InteractiveAuto render mode) using MudBlazor component library. It supports multiple hosting targets:

• Web (Server + WASM): Source/UI/Hosts/MMCA.Store.UI.Web
• WebAssembly Client: Source/UI/Hosts/MMCA.Store.UI.Web.Client
• MAUI (iOS, Android, macOS, Windows): Source/UI/Hosts/MMCA.Store.UI

11.2 Shopping Cart UX

The shopping cart is exclusively accessible through a 380px right-side drawer (CartDrawer), opened via the cart icon in the top app bar. There is no dedicated cart page.

Features:

• Quantity +/- controls per item when cart is Active
• Remove individual items, clear all items
• "Checkout & Pay" button triggers order creation + Stripe redirect
• "Checked Out" chip and read-only mode for checked-out carts
• Empty state with "Browse Products" navigation
• "Continue Shopping" link to catalog

State Management: The ICartStateService singleton manages cart state centrally. It enriches cart items with product names and SKUs from the Catalog API after each refresh.

11.3 Catalog Browse

The catalog browse page (/catalog) provides:

• Product grid with search by name
• Category filter dropdown
• Sort by name or price
• Star rating and review count on each card, read straight off the product's denormalized RatingSummary so a grid of cards costs no per-card aggregate query
• Effective-price range per card, with a sale badge and the struck-through list price when any variant on the card carries an active discount
• Quick "Add to Cart" buttons per variant
• "View Details" navigation to product detail page

The product detail page (/catalog/{id}) shows:

• Breadcrumbs (Home > Catalog > Product)
• Product description, brand, category
• Variant list with SKU, price, quantity selector, and "Add to Cart". A discounted variant shows the effective price beside the struck-through list price and a sale badge, and carries an accessible "Was X, now Y" label so a screen reader hears both numbers rather than the visual strike alone
• "Buy Now" option (direct Stripe checkout for single variant)
• A reviews section (anchor #reviews) listing the published reviews, plus the review editor for a signed-in customer who is eligible to write or revise one

11.4 Navigation Structure

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

• Customer: Home, Shop, My Orders, My Profile
• Admin: Home, Categories, Products, Reviews, Inventory, Shopping Carts, Orders, Customers, My Profile

Top App Bar: Cart icon with badge count, user email, Logout button (authenticated) or Login/Register buttons (anonymous)

11.5 Module Registration

UI modules implement IUIModule (providing NavItems and Assembly for route discovery). Modules can be conditionally enabled via UIModuleConfiguration.IsModuleEnabled(configuration, moduleName).

12. Cross-Cutting Infrastructure

12.1 Command/Query Pipeline Decorators

12.2 Idempotency

The IdempotencyFilter (applied via [Idempotent] attribute on Create endpoints) caches the first response for a given Idempotency-Key header value for 24 hours. Duplicate requests receive the cached response with an X-Idempotent-Replay: true header. Per-key SemaphoreSlim locking prevents concurrent duplicate execution.

12.3 Exception Handling

Five exception handlers (registered as middleware in priority order):

1. DomainExceptionHandler -> HTTP 400
2. ValidationExceptionHandler (FluentValidation) -> HTTP 400 with grouped errors
3. DbUpdateExceptionHandler -> HTTP 409 Conflict
4. OperationCanceledExceptionHandler -> HTTP 499
5. GlobalExceptionHandler -> HTTP 500 (catch-all)

12.4 Multi-Database Strategy

The IDbContextFactory implements a strategy pattern supporting three data sources:

• SQL Server (default, via Aspire container)
• SQLite (alternative)
• Cosmos DB (alternative, no transaction support)

Entity types are routed to data sources via [UseDataSource] attribute on EF configurations. The IDataSourceService caches entity-to-datasource mappings.

13. Testing

13.1 Test Structure

13.2 Key Test Scenarios

• Full customer journey: Register -> Browse -> Add to Cart -> Checkout -> Admin Pay -> Deliver
• Order lifecycle: all state transitions including cancellation with inventory restoration
• Cart operations: add, change quantity, remove, clear, checkout
• Authorization: anonymous, customer, admin role enforcement
• Cross-module: Catalog -> Sales pricing, inventory validation

14. Missing or Unclear Business Logic

14.1 Email Notifications Cover Payment and Shipping Only

Observation: Four handlers send email today: the password-reset request (Section 3.12), OrderPaidHandler (payment receipt, which prints a struck "Was" amount and the promotion label on a discounted line and a "You saved" total when the order saved anything), OrderShippedHandler (carrier, tracking number and tracking link, re-sent on every shipment correction) and OrderPaymentFailedSagaHandler. There is still no email at order placement (OrderChanged with the Added state), at delivery (OrderDelivered), or at cancellation (OrderCancelled). Recommendation: Confirm whether an order-confirmation and a delivery-confirmation message are wanted; both would be additional IDomainEventHandler<T> registrations on events that already exist, not new plumbing.

14.2 No Return/Refund Workflow

Observation: Once an order reaches Paid or Delivered status, there are no further state transitions available. No return, refund, or exchange workflow exists. Cancellation is only possible before payment succeeds. Recommendation: Clarify whether returns/refunds are in scope and whether Stripe refund integration is needed.

14.3 No Inventory Check at Cart-Add Time

Observation: When a customer adds an item to the cart, the system verifies the product variant exists but does not check if inventory is available. Inventory is only validated at checkout. Recommendation: This may be intentional (allowing customers to add items that are temporarily out of stock) or may warrant a stock availability indicator on the cart.

14.4 Cart Reactivation Clears All Items

Observation: When a customer adds an item to a previously checked-out cart, all previous items are deleted and the cart is reactivated empty (with only the new item). The business intent behind clearing the cart rather than preserving previous items is unclear. Recommendation: Confirm this is the desired behavior: some systems prefer to retain unchecked-out items.

14.5 No Price Change Protection

Observation: Product variant prices can be changed at any time by administrators. If a customer has items in their cart and prices change before checkout, the customer will be charged the new price (prices are fetched at checkout, not at cart-add time). Recommendation: Determine if customers should be notified of price changes or if cart items should display price warnings.

14.6 One Parcel Per Order

Observation: Delivery tracking exists (Section 3.8): an order carries a single Shipment value object with a carrier, a tracking number and the two dates. An order that physically leaves in two parcels can therefore only record one of them, and correcting the recorded shipment replaces it rather than adding to it. Recommendation: A second parcel needs the shipment to become a collection on the order, which is the same modelling change 14.7 asks for; clarify whether split shipments are a real business case before making it.

14.7 No Partial Order Fulfillment

Observation: Orders are delivered as a whole: there is no concept of partial shipments or split deliveries, and Shipped applies to the order rather than to individual lines. Recommendation: Clarify if partial fulfillment is a future requirement.

14.8 No Customer/User Deactivation Endpoint

Observation: User.Deactivate() method and UserDeactivated domain event exist in the domain model, but no API endpoint or UI action exposes this functionality. Recommendation: May be an admin feature not yet implemented.

14.9 Category Deletion Has No Cascade Check

Observation: Deleting a category doesn't check for assigned products. Products with a deleted category may have an orphaned CategoryId. Recommendation: Consider validating no products reference the category before deletion, or cascading the nullification.

14.10 Inventory List Endpoint Not Exposed

Observation: The InventoryItemsController only exposes GetById, the GetAll, GetPaged, and Lookup endpoints from the base class are not overridden. The UI InventoryItemList page may need these endpoints. Recommendation: Verify how the inventory list page fetches its data and whether list endpoints should be added.

15. Seed Data (Initial System State)

The system seeds the following data at startup:

Users:

• Admin: one seeded administrator account (Admin role, no Customer record; credentials are environment-specific and not published)
• Customer: one seeded demo customer account (Customer role)

Catalog:

• Categories: "Jewelry" (id=1), "Watches" (id=2)
• Product: "Gold Ring" (id=11, brand: "WhatNot", category: Jewelry)
• Variants: "Gold Ring - Size 6" ($15.00), "Gold Ring - Size 7" ($15.50), "Gold Ring - Size 8" ($16.00): all USD

Inventory: 100,000 units per variant (for all 3 Gold Ring sizes)

Seeding is idempotent: seeders check for existing data via ExistsAsync() before inserting, and only run for enabled modules.

This specification is derived entirely from the source code. All business rules, workflows, and behaviors described above are confirmed implementations traceable to the referenced source files. Last updated: 2026-09-05 (order shipment tracking and product reviews).