System Requirements Document for beauty-cosmetics

1. Introduction

beauty-cosmetics is a complete, production-ready, mobile-first beauty and cosmetics e-commerce platform. It is an original premium beauty shopping brand — not a clone of any existing store — whose visual layout is inspired by two uploaded reference screenshots used strictly as visual and structural inspiration. The brand's design language is built on pink, white, lavender, and teal, and it must feel premium, playful, and confident rather than austere.

The platform serves the full commerce lifecycle end-to-end: a customer storefront with search, a product catalog, product details, offers, a wishlist, a cart, secure checkout with real payment gateway integration, order tracking, notifications, and customer support; plus an administrative and merchant back office covering an admin dashboard, catalog management, inventory management, seller management, offer management, support management, and seller-owned listings and inventory. All backend APIs and database functionality are in scope.

Audience. The primary audience is a mobile-first, mostly 20–35 shopper who browses beauty products by mood and identity, alongside the operational staff (store administrators, sellers, and support agents) who keep the storefront accurate and resolve customer issues.

Non-negotiable product intent. Every button, menu, form, and shopping feature must work end-to-end. There is no mock functionality. Payments must never be reported as successful without verified payment gateway confirmation. There are no unfinished pages, broken links, placeholder buttons, or fake checkout flows. The deliverable is a working, tested, deployable full-stack application with setup and deployment steps explained.

2. System Overview

beauty-cosmetics is delivered as a first-party full-stack web application with a mobile-first responsive storefront and a role-protected back office, backed by first-party APIs and a persistent database.

Actors. The accepted active human personas are the Shopper, the Registered Customer, the Store Administrator, the Seller, and the Support Agent. The payment gateway is a typed non-persona external actor: it is a provider-owned service that authorizes and confirms payments, and its confirmation is the sole authority for reporting payment success.

Accepted behavior. Shoppers browse the catalog, search, view product details, view offers, and add items to a cart. Registered customers additionally keep a persistent wishlist, order history, order tracking, notifications, and support requests across sessions. Store administrators manage the catalog, inventory, sellers, offers, and support requests through role-based access. Sellers maintain their own product listings and stock. Support agents handle customer support requests and communicate resolutions back to customers.

Ownership. All customer-facing and back-office surfaces are first-party application pages. Payment authorization and confirmation are owned by the external payment gateway; the application only reflects gateway-confirmed outcomes. Identity is application-owned: shoppers self-enroll, returning users verify, and administrators provision staff roles.

Narrow exclusions. The platform does not implement mock or simulated payment success, does not ship placeholder or unfinished UI, and does not copy the uploaded reference screenshots — they inform layout only. No adjacent capabilities beyond the accepted scope (for example, loyalty programs, subscriptions, or marketplace-wide analytics suites) are introduced.

2a. Product Interpretation and Delivery Boundary

beauty-cosmetics is a first-party, application-owned commerce platform. The storefront is publicly reachable for browsing, search, catalog, product details, and offers, so a visitor can evaluate products before committing to an account. Persistent, customer-specific state — wishlist, cart continuity, checkout, orders, notifications, and support — is bound to an application-owned identity so that a commitment, entitlement, or order remains attached to the correct person across sessions.

Identity is established in two ways. Shoppers self-enroll through Sign Up and verify on return through Login. Staff roles — Store Administrator, Seller, and Support Agent — are provisioned by an administrator rather than self-selected, and they verify through the same Login surface. Access to protected destinations is role-restricted: a customer's own orders, wishlist, cart, notifications, and support are visible only to that customer, and back-office workspaces are visible only to the roles that own them.

Payment is delivered through a real external payment gateway. The application never asserts payment success on its own; it reports success only after the gateway confirms it, and it presents a retry path when confirmation does not arrive. Everything described in this document is current scope. No future-horizon features are asserted.

2b. Source Content Inventory

Not applicable. No reference directive declares a content_source; the uploaded screenshots are declared inspiration_only for visual layout and structure, and therefore supply no product names, copy, facts, or capabilities.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression of the premium beauty brand — brand wordmark, hero headline, a short statement of what the store sells, and entry points into shopping. No account required.
• Primary actions: Enter the Product Catalog; open Search; open Offers; proceed to Sign Up or Login.
• Supporting actions: Navigate to a featured product's Product Details; open the Cart.
• Domain entities: Brand, Product (featured), Offer (featured), Category.
• Component responsibilities: Sticky top bar (wordmark, search pill, cart count); full-bleed hero colour block; horizontally scrollable category rail; featured product grid; offers ticker; footer with support and account links.
• States: Loading — skeleton hero and product tiles. Empty — if no featured products or offers exist, the section shows a plain "nothing featured right now" message with a link to the full catalog. Success — hero, categories, and featured products render. Error — if catalog data fails to load, an inline error with a retry action replaces the affected section while the rest of the page remains usable. Recovery — retry re-requests the failed section only.

Login

• Information/state: Anonymous returning-verification surface shared by customers and provisioned staff. Collects credentials only.
• Primary actions: Submit credentials to verify identity; navigate to Sign Up.
• Supporting actions: Recover from an invalid-credential error by correcting input.
• Domain entities: Account, Role (customer, store administrator, seller, support agent), Session.
• Component responsibilities: Credential form with inline validation; submit control with pending state; error region; link to Sign Up.
• States: Loading — submit control shows a pending state and the form is not double-submittable. Empty — not applicable; the form is always present. Success — verified identity is routed to the destination appropriate to its role. Error — invalid credentials show a non-enumerating error and preserve entered input for correction. Recovery — the user may retry immediately; repeated failures do not lock the surface without a stated recovery path.

Product Catalog

• Information/state: Public storefront listing of beauty and cosmetics products with category, price, and availability context.
• Primary actions: Browse and filter the catalog; open a product's Product Details; add an in-stock product to the Cart.
• Supporting actions: Open Search; open Offers; open the Wishlist when signed in.
• Domain entities: Product, Category, Price, Stock status, Seller (as listing source).
• Component responsibilities: Filter and sort controls; product grid; pagination or incremental loading; per-card add-to-bag control; stock indicator.
• States: Loading — skeleton grid. Empty — no products match the current filters: a clear message with a control to clear filters. Success — grid renders with accurate prices and stock. Error — catalog request failure shows an inline error with retry. Recovery — retry or clear filters restores a usable grid.

Search

• Information/state: Catalog search destination accepting a query and presenting matching products.
• Primary actions: Enter a query and submit; open a result's Product Details; add an in-stock result to the Cart.
• Supporting actions: Refine the query; clear the query; return to the full catalog.
• Domain entities: Product, Category, Query.
• Component responsibilities: Search input with submit; result list; result count; no-results guidance.
• States: Loading — result area shows a pending indicator. Empty — no matches: a message stating no products matched, with suggestions to broaden the query and a link to the catalog. Success — matching products render. Error — search failure shows an inline error with retry. Recovery — retry or a revised query restores results.

Product Details

• Information/state: Focused view of a single product: name, imagery, description, price, availability, and seller context.
• Primary actions: Add the product to the Cart; add the product to the Wishlist when signed in.
• Supporting actions: Select quantity; return to the catalog or search results; open Offers.
• Domain entities: Product, Price, Stock status, Seller, Wishlist entry, Cart line.
• Component responsibilities: Product media; title and price block; quantity selector; add-to-bag control; wishlist control; availability indicator.
• States: Loading — skeleton product block. Empty — not applicable for a valid product; an unknown or removed product shows a not-found message with a link back to the catalog. Success — product renders and add-to-bag reflects real stock. Error — load failure shows an inline error with retry; add-to-bag failure shows a non-blocking error and leaves the cart unchanged. Recovery — retry reloads the product; a failed add can be retried.

Offers

• Information/state: Customer destination listing currently available offers and their conditions.
• Primary actions: View an offer's terms; apply an eligible offer to the Cart.
• Supporting actions: Open the affected product's Product Details; proceed to the Cart.
• Domain entities: Offer, Discount, Eligibility condition, Cart.
• Component responsibilities: Offer list with terms; apply control; eligibility feedback.
• States: Loading — skeleton offer list. Empty — no offers currently available: a clear message with a link to the catalog. Success — offers render and an eligible offer applies to the cart with a visible discount. Error — apply failure or ineligible offer shows an explanatory message and leaves the cart total unchanged. Recovery — the customer may remove or reapply an offer.

Sign Up

• Information/state: Anonymous self-service enrollment for shoppers becoming registered customers.
• Primary actions: Submit enrollment details to create an account.
• Supporting actions: Navigate to Login if already enrolled; correct validation errors inline.
• Domain entities: Account, Credential, Role (customer).
• Component responsibilities: Enrollment form with field-level validation; submit control with pending state; error region; link to Login.
• States: Loading — submit control shows a pending state and prevents duplicate submission. Empty — not applicable; the form is always present. Success — the account is created and the customer proceeds to verified access. Error — validation errors are shown per field; a duplicate-account error is explained without revealing unrelated account data. Recovery — the customer corrects the form and resubmits, or switches to Login.

Wishlist

• Information/state: Persistent, customer-owned list of saved products. Role-restricted to the signed-in customer.
• Primary actions: View saved products; remove a saved product; move a saved product to the Cart.
• Supporting actions: Open a saved product's Product Details; open the Cart.
• Domain entities: Wishlist entry, Product, Price, Stock status, Cart line.
• Component responsibilities: Saved-product list; remove control; move-to-bag control; availability indicator.
• States: Loading — skeleton list. Empty — no saved products: a message with a link to the catalog. Success — saved products render with current price and stock. Error — load or mutation failure shows an inline error and leaves the list unchanged. Recovery — retry reloads the wishlist; a failed removal or move can be retried.

Cart

• Information/state: Focused destination for the customer's current cart lines, quantities, and running total. Role-restricted to the signed-in customer.
• Primary actions: Change line quantity; remove a line; proceed to Checkout.
• Supporting actions: Apply an eligible offer; return to the catalog; open a line's Product Details.
• Domain entities: Cart, Cart line, Product, Price, Discount, Stock status.
• Component responsibilities: Line list with quantity controls; remove control; subtotal and discount summary; checkout control; stock warnings.
• States: Loading — skeleton line list. Empty — empty cart: a message with a link to the catalog. Success — lines, quantities, and totals render accurately. Error — quantity or removal failure shows an inline error and preserves the prior cart state; an out-of-stock line is flagged and blocks checkout for that line. Recovery — retry the failed mutation, adjust the flagged line, or remove it.

Checkout

• Information/state: Protected checkout destination for order details, payment, and order submission. Role-restricted to the signed-in customer.
• Primary actions: Provide required order details; submit payment to the payment gateway; place the order.
• Supporting actions: Review the order summary; return to the Cart to adjust lines; retry a failed payment.
• Domain entities: Order, Order line, Shipping details, Payment, Payment gateway confirmation, Cart.
• Component responsibilities: Order summary panel; details form with validation; payment step; progress indicator across the named steps; confirmation state; retry control.
• States: Loading — pending state during payment submission; the order is not reported as placed while pending. Empty — checkout with an empty cart redirects to the Cart with an explanatory message. Success — the order is reported as placed only after verified payment gateway confirmation, and the customer is shown the confirmed order. Error — a declined or unconfirmed payment is reported as not successful, the order is not marked paid, and a retry action is offered. Recovery — the customer retries payment or returns to the Cart; no order is created as paid without gateway confirmation.

Orders

• Information/state: Authenticated order history and order-status tracking for the signed-in customer's own orders. Role-restricted to that customer.
• Primary actions: View an order's detail and current status; track its progress.
• Supporting actions: Open a purchased product's Product Details; raise a support request about an order.
• Domain entities: Order, Order line, Order status, Payment status, Shipment/tracking status.
• Component responsibilities: Order list; order detail panel; status timeline; support entry point.
• States: Loading — skeleton order list. Empty — no orders yet: a message with a link to the catalog. Success — orders render with accurate status and payment state. Error — load failure shows an inline error with retry. Recovery — retry reloads the order list.

Notifications

• Information/state: Authenticated destination for the signed-in customer's order, offer, and support notifications. Role-restricted to that customer.
• Primary actions: Read a notification; follow its link to the related order, offer, or support request.
• Supporting actions: Mark notifications as read.
• Domain entities: Notification, Order, Offer, Support request.
• Component responsibilities: Notification list; read/unread state; deep link to the related record.
• States: Loading — skeleton list. Empty — no notifications: a clear message. Success — notifications render with accurate read state. Error — load failure shows an inline error with retry. Recovery — retry reloads notifications.

Support

• Information/state: Customer destination for submitting and following support requests. Role-restricted to the signed-in customer.
• Primary actions: Submit a support request; view the status of an existing request.
• Supporting actions: Attach a request to a related order; add follow-up detail.
• Domain entities: Support request, Message, Order reference, Status.
• Component responsibilities: Request form with validation; request list; status indicator; conversation view.
• States: Loading — skeleton request list. Empty — no requests: a message with the submission form available. Success — the request is created and appears with its status. Error — submission failure shows an inline error and preserves the entered content. Recovery — the customer resubmits or edits the request.

Admin Dashboard

• Information/state: Role-protected operational summary and entry point for administration. Role-restricted to the Store Administrator.
• Primary actions: Open Catalog Management, Inventory Management, Seller Management, Offer Management, and Support Management.
• Supporting actions: Review current operational counts and outstanding support requests.
• Domain entities: Product, Inventory level, Seller, Offer, Support request, Order.
• Component responsibilities: Summary tiles; navigation into each management workspace; outstanding-work indicators.
• States: Loading — skeleton tiles. Empty — a newly provisioned store shows zeroed summaries with direct links into each workspace. Success — summaries reflect current platform state. Error — a failed summary request shows an inline error with retry while navigation remains usable. Recovery — retry reloads summaries.

Catalog Management

• Information/state: Administrator workspace for maintaining product catalog records. Role-restricted to the Store Administrator.
• Primary actions: Create, edit, and remove product records; set category, price, and descriptive content.
• Supporting actions: Search and filter the catalog record list; open a record for editing.
• Domain entities: Product, Category, Price, Seller association.
• Component responsibilities: Record list with search and filters; create/edit form with validation; delete confirmation; save feedback.
• States: Loading — skeleton list. Empty — no products: a message with a create action. Success — changes persist and are reflected in the storefront. Error — validation or save failure shows a field-level or inline error and does not partially persist. Recovery — the administrator corrects and resaves.

Inventory Management

• Information/state: Administrator workspace for managing platform inventory levels. Role-restricted to the Store Administrator.
• Primary actions: View and adjust stock levels for products.
• Supporting actions: Filter inventory by product or low-stock status; identify items needing restock.
• Domain entities: Inventory level, Product, Stock status.
• Component responsibilities: Inventory list; stock adjustment control with validation; low-stock indicator.
• States: Loading — skeleton list. Empty — no inventory records: a message linking to Catalog Management. Success — adjustments persist and storefront availability reflects them. Error — invalid adjustment or save failure shows an inline error and leaves the prior level intact. Recovery — the administrator corrects the value and resaves.

Seller Management

• Information/state: Administrator workspace for managing seller records. Role-restricted to the Store Administrator.
• Primary actions: Create, edit, and deactivate seller records; associate sellers with their listings.
• Supporting actions: Search and filter seller records; review a seller's associated products.
• Domain entities: Seller, Product association, Account (seller role).
• Component responsibilities: Seller list; create/edit form with validation; status control; association view.
• States: Loading — skeleton list. Empty — no sellers: a message with a create action. Success — seller records persist and their listings remain correctly attributed. Error — validation or save failure shows an inline error without partial persistence. Recovery — the administrator corrects and resaves.

Offer Management

• Information/state: Administrator workspace for maintaining customer offers. Role-restricted to the Store Administrator.
• Primary actions: Create, edit, and end offers; define discount and eligibility conditions.
• Supporting actions: Search and filter offers; review an offer's current status.
• Domain entities: Offer, Discount, Eligibility condition, Product/Category scope.
• Component responsibilities: Offer list; create/edit form with validation; activation and end controls.
• States: Loading — skeleton list. Empty — no offers: a message with a create action. Success — offers persist and appear on the customer Offers page when active. Error — validation or save failure shows an inline error without partial persistence. Recovery — the administrator corrects and resaves.

Support Management

• Information/state: Administrator workspace for handling customer support requests. Role-restricted to the Store Administrator.
• Primary actions: Review incoming support requests; assign or respond to a request; update its status.
• Supporting actions: Filter by status; open a request's conversation; reference the related order.
• Domain entities: Support request, Message, Status, Order reference, Support Agent assignment.
• Component responsibilities: Request queue with filters; conversation view; response composer; status control.
• States: Loading — skeleton queue. Empty — no open requests: a clear message. Success — responses and status changes persist and are visible to the customer. Error — response or status failure shows an inline error and preserves the composed text. Recovery — the administrator retries the response.

Seller Listings

• Information/state: Seller workspace for maintaining owned product listings. Role-restricted to the Seller, scoped to that seller's own listings.
• Primary actions: Create, edit, and withdraw the seller's own product listings.
• Supporting actions: Search and filter own listings; review a listing's storefront representation.
• Domain entities: Product listing, Category, Price, Seller ownership.
• Component responsibilities: Own-listings list; create/edit form with validation; withdraw control; save feedback.
• States: Loading — skeleton list. Empty — no listings yet: a message with a create action. Success — listings persist and appear in the storefront. Error — validation or save failure shows an inline error without partial persistence. Recovery — the seller corrects and resaves.

Seller Inventory

• Information/state: Seller workspace for maintaining stock for owned products. Role-restricted to the Seller, scoped to that seller's own products.
• Primary actions: View and adjust stock for the seller's own products.
• Supporting actions: Filter own inventory by low-stock status.
• Domain entities: Inventory level, Product listing, Stock status, Seller ownership.
• Component responsibilities: Own-inventory list; stock adjustment control with validation; low-stock indicator.
• States: Loading — skeleton list. Empty — no owned products: a message linking to Seller Listings. Success — adjustments persist and storefront availability reflects them. Error — invalid adjustment or save failure shows an inline error and leaves the prior level intact. Recovery — the seller corrects the value and resaves.

3. Functional Requirements

FR-1 — Storefront browsing. As a Shopper, I should browse the beauty and cosmetics product catalog so that I can discover products to buy. (explicit)

• Trigger/input: opening the Product Catalog.
• Observable result: a product grid renders with accurate names, prices, and availability.
• Access state: publicly reachable without an account.
• Failure/recovery: a failed catalog request shows an inline error with retry; an empty result set shows a clear message with a control to clear filters.
• Continuation: the shopper opens a product's Product Details or adds an in-stock product to the Cart.

FR-2 — Product search. As a Shopper, I should search the catalog by query so that I can find a specific product quickly. (explicit)

• Trigger/input: submitting a query on Search.
• Observable result: matching products render with a result count.
• Access state: publicly reachable without an account.
• Failure/recovery: a failed search shows an inline error with retry; no matches shows guidance to broaden the query with a link to the catalog.
• Continuation: the shopper opens a result's Product Details or revises the query.

FR-3 — Product detail review. As a Shopper, I should review a single product's details so that I can decide whether to buy it. (explicit)

• Trigger/input: opening Product Details for a product.
• Observable result: the product's name, imagery, description, price, availability, and seller context render.
• Access state: publicly reachable without an account.
• Failure/recovery: a load failure shows an inline error with retry; an unknown or removed product shows a not-found message with a link to the catalog.
• Continuation: the shopper adds the product to the Cart or continues browsing.

FR-4 — Add to cart. As a Shopper, I should add an in-stock product to my cart so that I can purchase it. (explicit)

• Trigger/input: selecting add-to-bag on a product card or Product Details.
• Observable result: the cart gains the line and the cart count reflects the change.
• Access state: available to shoppers; cart continuity for a signed-in customer is bound to that customer's account.
• Failure/recovery: an out-of-stock or failed add shows a non-blocking error and leaves the cart unchanged.
• Continuation: the shopper opens the Cart or continues shopping.

FR-5 — Cart management. As a Registered Customer, I should manage my cart lines and quantities so that my order reflects what I intend to buy. (explicit)

• Trigger/input: changing a quantity or removing a line on Cart.
• Observable result: lines, quantities, and totals update accurately.
• Access state: role-restricted to the signed-in customer.
• Failure/recovery: a failed mutation shows an inline error and preserves the prior cart state; an out-of-stock line is flagged and blocks checkout for that line.
• Continuation: the customer proceeds to Checkout or adjusts the flagged line.

FR-6 — Customer account enrollment. As a Shopper, I should create an account so that my cart, wishlist, orders, and notifications persist across sessions. (required_inference)

• Trigger/input: submitting enrollment details on Sign Up.
• Observable result: an account is created and the customer proceeds to verified access.
• Access state: anonymous entry; the account becomes the customer's own identity.
• Failure/recovery: field-level validation errors are shown; a duplicate-account error is explained without revealing unrelated account data.
• Continuation: the customer verifies through Login and reaches their protected destinations.

FR-7 — Returning verification. As a Registered Customer, Store Administrator, Seller, or Support Agent, I should verify my identity on return so that I can reach the destinations my role owns. (required_inference)

• Trigger/input: submitting credentials on Login.
• Observable result: verified identity is routed to the destination appropriate to its role.
• Access state: anonymous entry surface; protected destinations remain unavailable until verification succeeds.
• Failure/recovery: invalid credentials show a non-enumerating error and preserve entered input for correction.
• Continuation: the user retries or, if a shopper without an account, proceeds to Sign Up.

FR-8 — Staff role provisioning. As a Store Administrator, I should provision Store Administrator, Seller, and Support Agent roles so that staff can perform their accepted work under role-based access. (required_inference)

• Trigger/input: creating or updating a staff account and its role in the administrative workspaces.
• Observable result: the provisioned role can verify through Login and reach exactly the destinations that role owns.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: validation or save failure shows an inline error without partial persistence.
• Continuation: the provisioned staff member verifies and begins their role's work.

FR-9 — Wishlist management. As a Registered Customer, I should save products to a wishlist so that I can return to them later. (explicit)

• Trigger/input: selecting the wishlist control on Product Details or a product card.
• Observable result: the product appears in the customer's Wishlist and persists across sessions.
• Access state: role-restricted to the signed-in customer.
• Failure/recovery: a failed save or removal shows an inline error and leaves the wishlist unchanged.
• Continuation: the customer opens Wishlist, removes a saved product, or moves it to the Cart.

FR-10 — Offers viewing and application. As a Shopper or Registered Customer, I should view available offers and apply an eligible one so that I receive the stated discount. (explicit)

• Trigger/input: opening Offers and applying an eligible offer.
• Observable result: the offer's terms are shown and an eligible offer applies a visible discount to the cart total.
• Access state: publicly viewable; applying affects the customer's own cart.
• Failure/recovery: an ineligible or failed application shows an explanatory message and leaves the cart total unchanged.
• Continuation: the customer proceeds to Checkout or removes the offer.

FR-11 — Secure checkout with verified payment. As a Registered Customer, I should complete checkout with a real payment gateway so that my order is placed only when payment is genuinely confirmed. (explicit)

• Trigger/input: providing required order details and submitting payment on Checkout.
• Observable result: the order is reported as placed only after verified payment gateway confirmation; the customer sees the confirmed order.
• Access state: role-restricted to the signed-in customer; checkout with an empty cart redirects to Cart with an explanatory message.
• Failure/recovery: a declined or unconfirmed payment is reported as not successful, the order is not marked paid, and a retry action is offered.
• Continuation: the customer retries payment, returns to the Cart, or proceeds to Orders once confirmed.

FR-12 — Order history and tracking. As a Registered Customer, I should view my orders and track their status so that I know where my purchase stands. (explicit)

• Trigger/input: opening Orders.
• Observable result: the customer's own orders render with accurate order, payment, and shipment status.
• Access state: role-restricted to the signed-in customer; only that customer's orders are visible.
• Failure/recovery: a load failure shows an inline error with retry.
• Continuation: the customer opens an order's detail, tracks progress, or raises a support request about it.

FR-13 — Notifications. As a Registered Customer, I should receive and read notifications about my orders, offers, and support requests so that I stay informed. (explicit)

• Trigger/input: opening Notifications or following a notification's link.
• Observable result: the customer's own notifications render with accurate read state and link to the related record.
• Access state: role-restricted to the signed-in customer.
• Failure/recovery: a load failure shows an inline error with retry.
• Continuation: the customer follows the notification to the related order, offer, or support request.

FR-14 — Customer support requests. As a Registered Customer, I should submit and follow support requests so that my issues are resolved. (explicit)

• Trigger/input: submitting a support request on Support.
• Observable result: the request is created and appears with its status; the customer can follow the conversation.
• Access state: role-restricted to the signed-in customer.
• Failure/recovery: a submission failure shows an inline error and preserves the entered content.
• Continuation: the customer adds follow-up detail or awaits a response.

FR-15 — Support handling. As a Support Agent, I should handle customer support requests so that customer issues are resolved and communicated back. (explicit)

• Trigger/input: reviewing and responding to a request in Support Management.
• Observable result: the response and status change persist and become visible to the customer on Support and in Notifications.
• Access state: role-restricted to the Support Agent and Store Administrator.
• Failure/recovery: a response or status failure shows an inline error and preserves the composed text.
• Continuation: the agent continues the conversation or closes the request.

FR-16 — Admin dashboard. As a Store Administrator, I should use an admin dashboard so that I can see platform state and reach each management workspace. (explicit)

• Trigger/input: opening Admin Dashboard.
• Observable result: operational summaries render and each management workspace is reachable.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: a failed summary request shows an inline error with retry while navigation remains usable.
• Continuation: the administrator opens a management workspace.

FR-17 — Catalog management. As a Store Administrator, I should maintain product catalog records so that the storefront stays accurate. (explicit)

• Trigger/input: creating, editing, or removing a product record in Catalog Management.
• Observable result: changes persist and are reflected in the storefront.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: validation or save failure shows a field-level or inline error and does not partially persist.
• Continuation: the administrator corrects and resaves, or moves to Inventory Management.

FR-18 — Inventory management. As a Store Administrator, I should manage platform inventory levels so that storefront availability is truthful. (explicit)

• Trigger/input: adjusting a stock level in Inventory Management.
• Observable result: the adjustment persists and storefront availability reflects it.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: an invalid adjustment or save failure shows an inline error and leaves the prior level intact.
• Continuation: the administrator corrects the value or reviews low-stock items.

FR-19 — Seller management. As a Store Administrator, I should manage seller records so that merchant participants and their listings are correctly represented. (explicit)

• Trigger/input: creating, editing, or deactivating a seller record in Seller Management.
• Observable result: seller records persist and their listings remain correctly attributed.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: validation or save failure shows an inline error without partial persistence.
• Continuation: the administrator reviews the seller's associated products.

FR-20 — Offer management. As a Store Administrator, I should maintain customer offers so that promotions shown to customers are correct. (explicit)

• Trigger/input: creating, editing, or ending an offer in Offer Management.
• Observable result: offers persist and active offers appear on the customer Offers page.
• Access state: role-restricted to the Store Administrator.
• Failure/recovery: validation or save failure shows an inline error without partial persistence.
• Continuation: the administrator reviews the offer's status or ends it.

FR-21 — Seller listing maintenance. As a Seller, I should maintain my own product listings so that my products are correctly represented and sellable. (explicit)

• Trigger/input: creating, editing, or withdrawing a listing in Seller Listings.
• Observable result: the listing persists and appears in the storefront under the seller's ownership.
• Access state: role-restricted to the Seller, scoped to that seller's own listings.
• Failure/recovery: validation or save failure shows an inline error without partial persistence.
• Continuation: the seller corrects and resaves, or moves to Seller Inventory.

FR-22 — Seller stock maintenance. As a Seller, I should maintain stock for my own products so that availability is accurate. (explicit)

• Trigger/input: adjusting a stock level in Seller Inventory.
• Observable result: the adjustment persists and storefront availability reflects it.
• Access state: role-restricted to the Seller, scoped to that seller's own products.
• Failure/recovery: an invalid adjustment or save failure shows an inline error and leaves the prior level intact.
• Continuation: the seller corrects the value or reviews low-stock items.

FR-23 — Backend APIs and database persistence. As the platform, I should provide backend APIs and database functionality for all durable workflows so that every accepted capability persists and enforces its rules. (explicit)

• Trigger/input: any accepted client action.
• Observable result: the action is persisted or rejected by a first-party API against the database, with authorization enforced.
• Access state: authorization is enforced per role for every protected operation.
• Failure/recovery: validation and error handling return actionable failures without partial persistence.
• Continuation: the client surfaces the outcome and the user continues.

FR-24 — End-to-end functional completeness. As the platform, every button, menu, form, and shopping feature should work end-to-end with no mock functionality, no unfinished pages, no broken links, no placeholder buttons, and no fake checkout flows. (explicit)

• Trigger/input: any user interaction with a control.
• Observable result: the control performs its stated action against real data and real services.
• Access state: consistent with the destination's access rule.
• Failure/recovery: real failures are surfaced honestly with a recovery path rather than simulated success.
• Continuation: the user proceeds with the resulting state.

4. User Personas

Shopper

The Shopper is the primary customer and the reason the storefront exists. They arrive mobile-first, often on a 375px phone, and browse by mood and identity rather than by specification. Their product context is discovery: they want to see what the brand offers, compare products, and decide whether something is worth buying.

Primary goal: find beauty and cosmetics products they want and get them into a cart ready to purchase.

Distinct accepted responsibilities: browsing the Product Catalog, searching on Search, reviewing Product Details, viewing Offers, and adding in-stock products to the Cart. The Shopper's work is exploratory and non-committal — nothing they do requires an account until they want their cart, wishlist, or orders to persist.

Relevant inputs or decisions: which category or query to explore, which product to open, whether a product is in stock, and whether to add it to the cart.

Interactions with other accepted participants: the Shopper's browsing depends on the Store Administrator's catalog and inventory accuracy and on the Seller's listing and stock accuracy; inaccurate data directly degrades the Shopper's experience. The Shopper becomes a Registered Customer when they enroll.

Observable success: products render with accurate prices and availability, search returns relevant results, and an in-stock product can be added to the cart with the cart count reflecting it.

Registered Customer

The Registered Customer is a Shopper who has enrolled so that their shopping state persists. Their product context is continuity: they expect their cart, wishlist, orders, notifications, and support history to be there when they return, on any session.

Primary goal: complete purchases and keep track of everything they have bought, saved, and asked about.

Distinct accepted responsibilities: managing the Cart, saving to the Wishlist, completing secure Checkout with verified payment, viewing and tracking Orders, reading Notifications, and submitting and following Support requests. This is materially different from the Shopper's work: the Registered Customer owns durable, private state and makes a payment commitment.

Relevant inputs or decisions: order details at checkout, whether to apply an offer, whether to retry a failed payment, and whether to raise a support request about an order.

Interactions with other accepted participants: the Registered Customer's payment is confirmed by the external payment gateway; their support requests are handled by the Support Agent; their orders depend on the Store Administrator's and Seller's catalog, inventory, and listing accuracy.

Observable success: an order is reported as placed only after verified gateway confirmation, the order appears in Orders with accurate status, notifications link to the related records, and support requests receive a visible response.

Store Administrator

The Store Administrator is the operator who keeps the storefront truthful. Their product context is the back office: they work across the whole platform rather than within a single customer's state.

Primary goal: keep catalog, inventory, sellers, offers, and support accurate and handled so that customers can shop without friction.

Distinct accepted responsibilities: using the Admin Dashboard, maintaining product records in Catalog Management, adjusting stock in Inventory Management, managing seller records in Seller Management, maintaining offers in Offer Management, handling support requests in Support Management, and provisioning staff roles. This is materially different from every other persona: the Store Administrator is the only role with platform-wide authority and the only one who provisions other roles.

Relevant inputs or decisions: product and category data, stock levels, seller associations, offer terms and eligibility, support request status, and staff role assignment.

Interactions with other accepted participants: the Store Administrator's catalog and inventory decisions directly determine what Shoppers and Registered Customers can buy; seller records determine what Sellers can maintain; offer records determine what customers see on Offers; support handling overlaps with the Support Agent.

Observable success: storefront data stays accurate, active offers appear to customers, and support requests move to resolution.

Seller

The Seller is a merchant participant managed through seller management who supplies and maintains their own products within the platform. Their product context is narrow and owned: they see and change only their own listings and stock.

Primary goal: have their products correctly represented and sellable in the storefront.

Distinct accepted responsibilities: maintaining owned product listings in Seller Listings and maintaining stock for owned products in Seller Inventory. This is materially different from the Store Administrator's work: the Seller's authority is scoped to their own products and does not extend to platform-wide catalog, inventory, offers, or support.

Relevant inputs or decisions: listing content, category, price, and stock levels for their own products.

Interactions with other accepted participants: the Seller's listings and stock are what Shoppers and Registered Customers browse and buy; the Store Administrator manages the seller record that establishes the Seller's participation.

Observable success: their listings appear in the storefront under their ownership and their stock levels are reflected in availability.

Support Agent

The Support Agent is a staff member who handles customer support requests and notifications raised by shoppers. Their product context is the support queue and the conversations within it.

Primary goal: resolve customer issues and communicate the resolution back to the customer.

Distinct accepted responsibilities: reviewing incoming support requests, responding to them, and updating their status in Support Management. This is materially different from the Store Administrator's work: the Support Agent's focus is the customer conversation and its resolution rather than platform configuration.

Relevant inputs or decisions: the customer's request content, the related order reference, and the appropriate response and status.

Interactions with other accepted participants: the Support Agent responds to Registered Customers' requests, and those responses become visible to the customer on Support and in Notifications.

Observable success: customer issues are resolved and the resolution is communicated back to the customer.

5. Core User Flows

Flow 1 — Shopper discovers and adds a product (Shopper)

1. The Shopper opens Landing without an account and sees the brand, featured products, and category rail.
2. The Shopper enters the Product Catalog and browses or filters the grid; products render with accurate prices and availability.
3. The Shopper opens Search, submits a query, and reviews matching results with a result count. If nothing matches, the page states that no products matched and offers to broaden the query with a link back to the catalog.
4. The Shopper opens a result's Product Details and reviews the name, imagery, description, price, availability, and seller context.
5. The Shopper selects add-to-bag on an in-stock product. The cart gains the line and the cart count reflects the change. If the product is out of stock or the add fails, a non-blocking error appears and the cart is unchanged.
6. The Shopper continues browsing or opens the Cart. If the Shopper wants their cart, wishlist, and orders to persist, they proceed to Flow 2.

Flow 2 — Shopper enrolls and verifies (Shopper → Registered Customer)

1. The Shopper opens Sign Up and submits enrollment details.
2. Field-level validation errors are shown inline if any field is invalid; a duplicate-account error is explained without revealing unrelated account data.
3. On success, the account is created and the Shopper proceeds to verified access.
4. The Shopper verifies on Login. Invalid credentials show a non-enumerating error and preserve the entered input for correction.
5. On success, the Shopper is routed to the destination appropriate to their role and is now a Registered Customer with persistent cart, wishlist, orders, notifications, and support.

Flow 3 — Registered Customer manages cart, wishlist, and offers (Registered Customer)

1. The Registered Customer opens Wishlist and reviews saved products with current price and stock. If nothing is saved, the page offers a link to the catalog.
2. The customer removes a saved product or moves one to the Cart. A failed removal or move shows an inline error and leaves the list unchanged.
3. On Cart, the customer changes quantities or removes lines; lines, quantities, and totals update accurately. An out-of-stock line is flagged and blocks checkout for that line.
4. The customer opens Offers, reviews an offer's terms, and applies an eligible offer. The cart total shows the discount. An ineligible or failed application explains why and leaves the total unchanged.
5. The customer proceeds to checkout (Flow 4) or continues shopping.

Flow 4 — Registered Customer completes secure checkout with verified payment (Registered Customer)

1. The Registered Customer opens Checkout with a non-empty cart. If the cart is empty, checkout redirects to Cart with an explanatory message.
2. The customer reviews the order summary panel and provides the required order details; validation errors are shown inline.
3. The customer submits payment to the real payment gateway. The progress indicator moves through the named steps and the order is not reported as placed while payment is pending.
4. If the gateway confirms payment: the order is reported as placed, the customer sees the confirmed order, and the confirmation state reflects the verified gateway confirmation.
5. If payment is declined or confirmation does not arrive: the payment is reported as not successful, the order is not marked paid, and a retry action is offered. The customer retries payment or returns to the Cart to adjust lines. No order is ever created as paid without gateway confirmation.
6. On confirmed success, the customer proceeds to Orders.

Flow 5 — Registered Customer tracks orders and reads notifications (Registered Customer)

1. The Registered Customer opens Orders and sees their own orders with accurate order, payment, and shipment status. If there are no orders yet, the page offers a link to the catalog.
2. The customer opens an order's detail and tracks its progress on the status timeline.
3. The customer opens Notifications and reads notifications about their orders, offers, and support requests. If there are none, a clear message is shown.
4. The customer follows a notification's link to the related order, offer, or support request.
5. If a load fails on either page, an inline error with retry is shown and the customer retries.

Flow 6 — Registered Customer raises a support request (Registered Customer)

1. The Registered Customer opens Support and submits a support request, optionally attaching it to a related order.
2. If submission fails, an inline error is shown and the entered content is preserved so the customer can resubmit.
3. On success, the request appears in the customer's request list with its status.
4. The customer adds follow-up detail and follows the conversation as the Support Agent responds (Flow 7).
5. The customer sees the resolution on Support and in Notifications.

Flow 7 — Support Agent resolves a customer request (Support Agent)

1. The Support Agent verifies on Login and reaches Support Management.
2. The agent reviews the incoming request queue, filters by status, and opens a request's conversation, referencing the related order where relevant.
3. The agent composes and sends a response and updates the request's status. If the response or status change fails, an inline error is shown and the composed text is preserved.
4. On success, the response and status persist and become visible to the customer on Support and in Notifications.
5. The agent continues the conversation or closes the request.

Flow 8 — Store Administrator maintains the platform (Store Administrator)

1. The Store Administrator verifies on Login and reaches Admin Dashboard, where operational summaries render and each management workspace is reachable. If a summary request fails, an inline error with retry is shown while navigation remains usable.
2. In Catalog Management, the administrator creates, edits, or removes product records. Validation or save failure shows a field-level or inline error and does not partially persist; on success, changes are reflected in the storefront.
3. In Inventory Management, the administrator adjusts stock levels. An invalid adjustment or save failure leaves the prior level intact; on success, storefront availability reflects the change.
4. In Seller Management, the administrator creates, edits, or deactivates seller records and reviews their associated products.
5. In Offer Management, the administrator creates, edits, or ends offers with discount and eligibility conditions; active offers appear on the customer Offers page.
6. In Support Management, the administrator reviews and responds to support requests alongside the Support Agent (Flow 7).
7. The administrator provisions Store Administrator, Seller, and Support Agent roles so staff can verify and reach exactly the destinations their role owns.

Flow 9 — Seller maintains listings and stock (Seller)

1. The Seller verifies on Login and reaches Seller Listings, scoped to their own listings.
2. The Seller creates, edits, or withdraws a listing. Validation or save failure shows an inline error without partial persistence; on success, the listing appears in the storefront under the seller's ownership.
3. The Seller opens Seller Inventory and adjusts stock for their own products. An invalid adjustment or save failure leaves the prior level intact; on success, storefront availability reflects the change.
4. The Seller reviews low-stock items and restocks them so their products remain sellable.

6. Visuals Colors and Theme

Muse and headline. Saturated beauty maximalism after Jessica Walsh — colour as material, wit as luxury. The storefront is a hot-pink ground with a teal counter-accent, lavender as soft support, and products staged like art objects with a wink. Premium but never austere: colour is the product.

Colour tokens (light mode).

Contrast rules. Ink on blush-white = 15.8:1. White on pink = 4.6:1 — use only for 18px+ or bold text. Ink on teal = 7.4:1. Ink on lavender = 7.9:1. Never put white body text on lavender or teal.

Typography.

• Headings: Archivo Black at weight 400 (it is already black), tracking -0.02em; uppercase for section labels and category names, sentence case for editorial headlines.
• Accent words inside a headline switch to italic Fraunces for one word only.
• Body: DM Sans.
• Scale: 1.333 modular on a 16px base — 12 / 14 / 16 / 21 / 28 / 38 / 50 / 67 / 89 / 119.
• Display sizes: hero headline clamp(44px, 11vw, 128px) with 0.92 line-height; section headlines clamp(30px, 6vw, 64px); product title 18px → 24px; price 20px → 28px; body 16px with 1.6 line-height; micro-labels 12px uppercase tracked +0.14em.

Shape language. Big radii — 24px cards, 32px hero blocks, 999px pills for all filters and CTAs. Sticker-like overlapping shapes with 2px ink outlines. Colour blocks that collide rather than nest. Diagonal 8° colour bands as section dividers. Capsule "swatch" chips. Shadows are hard and offset (6px 6px 0 ink) rather than soft — a printed-sticker feel. Nothing is transparent; every surface is a flat colour.

Layout. Mobile-first single column at 375px: sticky top bar with wordmark, search pill, and cart count; full-bleed hero colour block; horizontally scrollable category rail (touch-scroll, snap, with a visible "swipe" affordance); 2-up product grid at 375px, 3-up at 768px, 4-up at 1280px, with a max content width of 1280px and 24px gutters. Sections are separated by diagonal colour bands, not whitespace. Every text block sits inside a container with a hard edge — no text ever bleeds off-screen; only decorative shapes, bands, and the marquee cross edges. Product cards are never identical hover-lift tiles: they alternate between white and lavender grounds with a rotated sticker badge.

Imagery. Art-directed product photography and 3D props on flat saturated colour grounds: a lipstick standing on a teal block, a serum bottle half-submerged in pink liquid, a blush compact with a lavender shadow. Props are surreal but clean — floating pearls, ribbon curls, glossy 3D capsules. No stock-model lifestyle shots, no white-background packshots, no gradient blobs. Illustrations are chunky flat vector doodles (sparkles, hearts, stars) used as stickers, never as hero art.

Readable-content rule. Headlines, wordmarks, labels, numbers, item images, cards, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Crops, bleeds, and off-edge placement are for decoration only. Moving and scrollable content (marquees, tickers, carousels, horizontally scrollable rows) may cross the viewport edge by design, judged by whether it actually moves and whether every item becomes fully readable as it passes; under prefers-reduced-motion it stops and shows whole items, wrapping into rows or sitting in a horizontally scrollable row (overflow-x: auto).

Forbidden. Blue or indigo primary/accent anywhere (#0057FF, #2563EB, #6366F1, #7C3AED); Inter, Roboto, Arial, Helvetica, Poppins, Open Sans, Lato, or system-ui for headings or body; gradient-blob heroes, frosted glass panels, or soft blurred drop shadows; a grid of identical hover-lift cards with uniform white surfaces; centred headline + subtext + single button hero composition; white-background packshot photography or stock-model lifestyle imagery; text, prices, buttons, or product images cropped or overlapped at 375px, 768px, or 1280px; decorative motion that does not carry meaning, or any animation that ignores prefers-reduced-motion.

7. Signature Design Concept

"The Beauty Counter" — a hero as two colliding colour blocks.

The public entry (Landing) opens on a full-bleed split colour block, not a centred SaaS hero. The left 60% is hot pink #E5387A; the right 40% is teal #00B3A4; a hard diagonal cut separates them. On mobile the blocks stack, pink first.

The hero headline is set in Archivo Black at clamp(44px, 11vw, 128px), flush-left, breaking across three lines, spanning the full pink field edge to edge, with the word "glow" in italic Fraunces — one accent word only. A single art-directed product still (a lipstick on a pink pedestal with a real cast shadow) sits in the teal half, cropped by the diagonal. The primary CTA is an ink-black pill with white text cut into the pink block; a secondary teal-outlined pill sits beside it. No centred stack, no sub-headline paragraph, no blue button, no gradient.

Below the hero, the signature moves carry the page: the sticker-swatch product cards (flat colour tiles alternating white and lavender, 2px ink border, hard 6px offset shadow, rotated category badge, and an on-card "Add to bag" pill that flips from pink to teal on tap), the 28s offers marquee running edge-to-edge in ink on teal with uppercase 14px tracked labels and · separators, and the category rail as a horizontally scrollable row of capsule chips with real product thumbnails inside, snapping to centre, active chip filled teal and the rest outlined ink on blush.

The concept recomposes only accepted content and controls — brand, featured products, categories, offers, search, cart count, and account entry. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief.

• Focal subject: the split pink/teal colour block with the oversized three-line Archivo Black headline and the single art-directed lipstick still in the teal half, cropped by the hard diagonal.
• Input → transformation → outcome thesis: as the hero enters the viewport, the headline's words reveal in a staggered 60ms sequence and the diagonal cut settles into place, so the visitor's first frame resolves from a colour collision into a legible brand statement and a clear path into the catalog — using only accepted content and controls.
• Motion vocabulary: 180–320ms cubic-bezier(0.22, 1, 0.36, 1) entrances; staggered 60ms word reveals on the hero headline; springy scale(1.04) on tap targets; colour-flip on hover for category chips (pink → teal); a slow 28s marquee for the offers ticker; a scale keyframe pop on the cart count when it increments.
• Composed first frame: the pink and teal blocks already in place with the diagonal cut, the headline's first line fully legible, the lipstick still composed in the teal half, and the ink-black primary pill and teal-outlined secondary pill both fully inside the viewport at 375px.
• Reduced-motion state: all motion collapses to a static state under prefers-reduced-motion; the marquee becomes wrapped rows of whole items; the headline appears fully composed with no stagger; the cart count changes without a pop.

9. Non-Functional Requirements

NFR-1 — Mobile-first responsive design. The platform is designed mobile-first and remains fully usable at 375px, 768px, and 1280px, with the layout rules in Section 6. (explicit)

NFR-2 — Accessibility. The platform implements accessibility: semantic structure, keyboard operability, visible focus, labelled controls, and sufficient contrast per the token rules in Section 6. (explicit)

NFR-3 — Secure authentication. Authentication is secure: credentials are verified server-side, sessions are protected, and protected destinations are unreachable without verified identity. (explicit)

NFR-4 — Role-based access. Access is enforced by role for every protected destination and operation: customers reach only their own state; Store Administrators, Sellers, and Support Agents reach only the workspaces their role owns. (explicit)

NFR-5 — Input validation. All user input is validated, with field-level feedback on forms and server-side enforcement on every API. (explicit)

NFR-6 — Error handling. Failures are surfaced honestly with an actionable recovery path; no failure is masked as success. (explicit)

NFR-7 — Loading states. Every asynchronous surface presents a loading state and prevents duplicate submission while pending. (explicit)

NFR-8 — Empty states. Every collection surface presents a meaningful empty state with a next step. (explicit)

NFR-9 — No mock functionality. No capability is simulated; every feature operates against real data and real services. (explicit)

NFR-10 — Verified payment only. Payment success is reported only after verified payment gateway confirmation; the application never asserts success on its own. (explicit)

NFR-11 — No unfinished or placeholder UI. There are no unfinished pages, broken links, placeholder buttons, or fake checkout flows. (explicit)

NFR-12 — Testing. The application is tested, covering the accepted customer and back-office workflows. (explicit)

NFR-13 — Deployment documentation and environment configuration. Setup and deployment steps are documented, and environment configuration is provided for all required services including the payment gateway. (explicit)

NFR-14 — Deployable full-stack deliverable. The result is a working, tested, deployable full-stack application. (explicit)

10. Tech Stack

• Frontend: React, mobile-first responsive, built to the layout and token rules in Section 6. (Default — not specified by user)
• Backend: Python with FastAPI, providing the backend APIs and authorization enforcement for all durable workflows. (Default — not specified by user)
• Database: A relational database for products, inventory, sellers, offers, accounts, carts, wishlists, orders, payments, notifications, and support requests. (Default — not specified by user)
• Payments: A real external payment gateway integration with server-side confirmation handling; the gateway is the sole authority for payment success. (explicit — real payment gateway integration required)
• Containerization: Docker and docker-compose for local and deployment parity. (Default — not specified by user)
• Orchestration: Kubernetes only if the chosen deployment target requires it. (Default — not specified by user)
• Configuration: Environment configuration for all services, including gateway credentials. (explicit)

11. Assumptions and Constraints

Constraints (binding).

1. Mobile-first design. (explicit)
2. Pink, white, lavender, and teal colour palette. (explicit)
3. Original premium beauty brand; the two uploaded reference screenshots inform layout only and are not copied. (explicit)
4. No mock functionality. (explicit)
5. Payments must not be reported as successful without verified payment gateway confirmation. (explicit)
6. No unfinished pages, broken links, placeholder buttons, or fake checkout flows. (explicit)
7. Secure authentication and role-based access required. (explicit)
8. Input validation, error handling, loading states, and empty states required. (explicit)
9. Responsive design and accessibility required. (explicit)
10. Testing required. (explicit)
11. Deployment documentation and environment configuration required. (explicit)

Assumptions (narrow, labeled).

1. Identity is application-owned: shoppers self-enroll through Sign Up and verify through Login; Store Administrator, Seller, and Support Agent roles are provisioned by an administrator rather than self-selected. (required_inference)
2. The payment gateway is an external provider; the application integrates with it and reflects only its confirmed outcomes. (required_inference)
3. Cart continuity for a signed-in customer is bound to that customer's account; a Shopper may build a cart before enrolling. (required_inference)
4. Product imagery is art-directed to the direction in Section 6; specific photography assets are supplied at implementation time. (Default — not specified by user)
5. The relational database engine, containerization, and any orchestration are implementation defaults and do not alter accepted behavior. (Default — not specified by user)

12. Glossary

• Shopper — an unauthenticated or browsing visitor who explores the catalog, searches, views product details and offers, and can add items to a cart.
• Registered Customer — a Shopper who has enrolled and verified, owning persistent cart, wishlist, orders, notifications, and support state.
• Store Administrator — the platform-wide operator who manages catalog, inventory, sellers, offers, support, and staff role provisioning.
• Seller — a merchant participant, managed through seller management, who maintains their own product listings and stock.
• Support Agent — a staff member who handles customer support requests and communicates resolutions back to customers.
• Payment gateway — the external provider-owned service that authorizes and confirms payments; its confirmation is the sole authority for reporting payment success.
• Verified payment gateway confirmation — the gateway's authoritative confirmation that a payment succeeded; required before any order is reported as placed or paid.
• Offer — a promotion with a discount and eligibility conditions, maintained by the Store Administrator and applied by customers to their cart.
• Wishlist — a Registered Customer's persistent list of saved products.
• Cart — the customer's current set of intended purchases, with lines, quantities, and totals.
• Order — a confirmed purchase, created only after verified payment gateway confirmation, with order, payment, and shipment status.
• Role-based access — enforcement that each role reaches only the destinations and operations it owns.
• Empty state — the designed presentation of a collection surface when it contains no items, with a next step.
• Loading state — the designed presentation of a surface while an asynchronous operation is pending, preventing duplicate submission.