System Requirements Document for auralab-fragrance

1. Introduction

AURA LAB is a premium fragrance e-commerce application for the Pakistan market. Its brand promise is “A FRAGRANCE THAT LINGERS.” The current product must operate as a real commercial storefront and order-management system, not as a mockup, demo, fake checkout, fake order system, or fake tracking experience.

The application serves customers who browse fragrances, select sizes, place Cash on Delivery orders, receive a real order reference, optionally share an order through WhatsApp, and track delivery progress. It also serves authorized store operators who securely manage the live product catalog and real Firestore-backed orders.

The critical customer lifecycle is:

HOME → SHOP → PRODUCT → SELECT SIZE → ADD TO CART / BUY NOW → CHECKOUT → CONFIRM ORDER → FIRESTORE → REAL ORDER ID → ORDER CONFIRMATION → TRACK ORDER

The corresponding operational lifecycle is:

CUSTOMER ORDER → FIRESTORE → ADMIN DASHBOARD → REAL-TIME ORDER UPDATE → ADMIN STATUS UPDATE → CUSTOMER TRACKING UPDATE

2. System Overview

AURA LAB shall extend the existing deployed application while preserving and reusing the existing architecture and working components wherever practical.

The storefront shall provide anonymous shopping, product browsing, fragrance-size selection, temporary cart support, Cash on Delivery checkout, Firestore-backed order creation, order confirmation, optional WhatsApp sharing, and real order tracking. Customers shall not be required to create an account to place or track an order.

The administrative experience shall provide secure authenticated and authorized access to real Firestore order and product data. Authorized admins shall see new orders in real time, receive non-repeating new-order notifications, update order statuses, and manage the product catalog.

Firestore shall be the authoritative source of truth for persistent commerce data. The required collections are:

• orders
• products
• customers

The application shall remain compatible with the existing Google Cloud Run deployment architecture.

Current Delivery Scope

Current scope includes:

• Real Firestore-backed products, customers, and orders.
• Real customer order creation and retrieval.
• Cash on Delivery as the primary payment method.
• Customer-facing order confirmation and tracking.
• Optional WhatsApp order sharing after successful Firestore persistence.
• Secure admin authentication and authorization.
• Admin order visibility, real-time updates, notifications, status updates, and product management.
• Responsive/mobile-compatible operation.
• Runtime-origin-generated customer URLs.

Narrow Exclusions

The current scope does not include:

• Mock data, sample orders, fake order creation, fake checkout, or fake tracking.
• Public admin registration or self-enrollment.
• Admin passwords, Firebase Admin credentials, server secrets, database credentials, or private API keys exposed in frontend code.
• Dependence on auralab.pk.
• Dependence on auralab.pages.dev.
• Mandatory WhatsApp messaging as a condition of order placement.
• Customer account creation as a prerequisite for shopping, checkout, confirmation, or tracking.

2a. Product Interpretation and Delivery Boundary

AURA LAB is a first-party React and TypeScript commerce application backed by the existing Node.js/server architecture, Firebase Firestore, and Google Cloud Run.

Customers interact with public storefront, checkout, confirmation, and tracking pages. Customer order ownership is established through the submitted order details and secure tracking verification using order number plus phone, or another secure existing verification method. Customer-generated tracking and WhatsApp URLs shall be created from the active runtime origin, preferably window.location.origin, and shall never rely on a hard-coded historic or assumed production domain.

Administrative work is restricted to authorized store operators. Admin credentials are provisioned and authorized out-of-band; there is no public admin self-enrollment. The Admin Login page establishes admin access before restricted /admin, /admin/orders, and /admin/products destinations are available.

Firestore persistence, product availability validation, secure authorization checks, order verification, real-time synchronization, and notification deduplication may be supported by backend services, but their customer and admin outcomes remain visible through the defined application pages.

2c. Page Content and Component Coverage

HOME

• Access: Public; no authentication required.
• Information and state: AURA LAB brand presentation, tagline “A FRAGRANCE THAT LINGERS.”, premium fragrance positioning, and a clear entry to browse the live catalog.
• Primary actions: Navigate to SHOP.
• Supporting actions: Access the public tracking route where provided by the storefront navigation.
• Domain entities: Brand content and live product catalog entry points.
• Component responsibilities: Present a luxury, minimal, sophisticated, modern, mysterious, premium, editorial first impression without inventing unsupported brand facts or product claims.
• States: Responsive loading-safe rendering; clear navigation recovery if live catalog data is temporarily unavailable.

SHOP

• Access: Public; no authentication required.
• Information and state: Live products retrieved from the Firestore-backed product catalog.
• Primary actions: Browse available products and open PRODUCT.
• Supporting actions: Continue to tracking from available storefront navigation.
• Domain entities: Products.
• Component responsibilities: Render real product catalog data; distinguish loading, populated, empty, and retrieval-error states.
• States: Loading while products are retrieved; empty state when no products are available; clear error and retry/recovery action if products cannot be loaded.

PRODUCT

• Access: Public; no authentication required.
• Information and state: A selected live product and its available size choices.
• Primary actions: Select size; add the selected product and size to cart; choose Buy Now to proceed to CHECKOUT.
• Supporting actions: Adjust intended quantity where supported by the existing cart experience; return to SHOP.
• Domain entities: Product, product availability, selected size, quantity, temporary cart state.
• Component responsibilities: Retrieve real product details, require a valid size selection before purchase actions, and verify that displayed availability is current enough for checkout validation.
• States: Loading, unavailable/not-found product, unavailable size, selected-size state, add-to-cart success, and error recovery without creating an order.

CHECKOUT

• Access: Public; no authentication required.
• Information and state: Cart contents; customer name, phone, email, address, city, customer notes, subtotal, delivery fee, total, and Cash on Delivery payment method.
• Primary actions: Submit CONFIRM ORDER.
• Supporting actions: Correct checkout fields, return to cart/product context, and retry after a recoverable confirmation failure.
• Domain entities: Cart, customer details, order line items, product availability, delivery fee, order total, Cash on Delivery order.
• Component responsibilities: Validate and sanitize checkout inputs; validate cart contents; validate product availability; prevent duplicate submission; generate a unique customer-friendly order ID; persist and verify the complete Firestore order; block confirmation success until persistence and retrieval are successful.
• States: Field-validation errors, empty/invalid cart, product-unavailable error, submission-in-progress lock, successful verified persistence transition to ORDER CONFIRMATION, and exact persistence error message: “Your order could not be confirmed. Please try again.”

ORDER CONFIRMATION

• Access: Public for the immediately verified completed order context; no customer account required.
• Information and state: ✓ ORDER CONFIRMED, “Thank you for choosing AURA LAB.”, customer-friendly order number in the AURA-XXXXXX format, products, sizes, quantities, prices, subtotal, delivery, total, payment method, delivery address, and current status.
• Primary actions: TRACK MY ORDER and CONTINUE SHOPPING.
• Supporting actions: SEND ORDER TO WHATSAPP, enabled only after successful Firestore save and retrieval verification.
• Domain entities: Persisted order, order items, delivery details, Cash on Delivery payment, tracking URL.
• Component responsibilities: Render only the verified persisted order; generate tracking and WhatsApp links from the current runtime origin; compose the WhatsApp message with required order details.
• States: Confirmed order display; no success rendering if Firestore persistence or retrieval verification failed; optional WhatsApp availability only after confirmation criteria are met.

/track-order

• Access: Public; no authentication required. Secure verification is required before order details are disclosed.
• Information and state: Tracking lookup using order number and phone, including support for /track-order?order=AURA-XXXXXX&phone=03142087801; verified real order details and current Firestore status.
• Primary actions: Submit or use supplied order number and phone verification to retrieve the order.
• Supporting actions: Retry corrected verification details after failure.
• Domain entities: Order ID, customer, products, sizes, quantities, total, payment method, order date, address, current status, status timeline.
• Component responsibilities: Retrieve only real Firestore orders after secure verification; display timeline stages CONFIRMED → PROCESSING → SHIPPED → OUT FOR DELIVERY → DELIVERED; highlight the current status; safely represent CANCELLED as the current status without falsely presenting it as a completed delivery path.
• States: Lookup-ready, retrieval loading, verified result, clear order-not-found/verification-failed error, and retry recovery. No hard-coded sample order may appear.

Admin Login

• Access: Public anonymous entry for authorized admin authentication.
• Information and state: Secure sign-in state for provisioned store operators.
• Primary actions: Authenticate using the existing secure admin authentication mechanism.
• Supporting actions: Recover from failed authentication and continue only after successful authorization.
• Domain entities: Admin identity and authorized session.
• Component responsibilities: Establish authenticated admin access without exposing passwords, secrets, credentials, or authorization rules in frontend code; redirect authenticated authorized admins to the appropriate restricted admin destination.
• States: Signed-out, sign-in in progress, unauthorized/failed sign-in, and authorized continuation. No public admin account enrollment is provided.

/admin

• Access: Role-restricted to authorized Admin (Store Operator) users.
• Information and state: Real-time dashboard visibility for new and current Firestore orders.
• Primary actions: Open /admin/orders and /admin/products.
• Supporting actions: Review new-order notifications.
• Domain entities: Real orders, order IDs, customer names, totals, notification acknowledgement/deduplication state.
• Component responsibilities: Subscribe to relevant real-time Firestore order updates where appropriate; display 🔔 NEW ORDER notifications containing order ID, customer name, and total formatted as Rs. X,XXX; prevent repeatedly notifying the same order after refresh.
• States: Authorized loading, live order state, new-order notification, no-new-order state, listener/retrieval error with retry/recovery, and unauthorized redirect to Admin Login.

/admin/orders

• Access: Role-restricted to authorized Admin (Store Operator) users.
• Information and state: Real Firestore orders with order ID, customer, phone, email, products, sizes, quantity, subtotal, delivery, total, payment method, date, and status.
• Primary actions: Change an order status to CONFIRMED, PROCESSING, SHIPPED, OUT_FOR_DELIVERY, DELIVERED, or CANCELLED.
• Supporting actions: Review real-time incoming and updated order records.
• Domain entities: Orders, order items, customer delivery data, payment method, timestamps, order status.
• Component responsibilities: Render live persistent data; authorize every status update; persist status and updatedAt; ensure customer tracking reflects the updated Firestore status.
• States: Loading, populated, empty, status-update in progress, successful status update, status-update error with clear retry/recovery, listener error, and unauthorized access handling.

/admin/products

• Access: Role-restricted to authorized Admin (Store Operator) users.
• Information and state: Real Firestore product catalog.
• Primary actions: Manage the product catalog using authorized product-management controls supported by the existing application.
• Supporting actions: Review product availability relevant to customer browsing and checkout.
• Domain entities: Products and product availability.
• Component responsibilities: Retrieve and modify only real Firestore product data through authorized operations; prevent unauthorized product changes; keep storefront availability aligned with catalog data.
• States: Loading, populated, empty catalog, save/update in progress, successful catalog update, retrieval/update error with recovery, and unauthorized access handling.

3. Functional Requirements

FR-01 — Existing Application Preservation

As a project operator, I should have the existing AURA LAB application modified rather than replaced with a mockup, demo, fake checkout, fake orders, or fake tracking so that the deployed product remains a real commercial system.

• Provenance: explicit.
• The implementation shall inspect and understand the existing project architecture before changes are made.
• The implementation shall reuse working components and the existing architecture wherever practical.
• The implementation shall not unnecessarily rewrite working application parts.
• Observable acceptance: Production behavior uses real application integrations and persistent data rather than sample-only or simulated commerce flows.

FR-02 — Live Storefront Browsing

As a Customer (Shopper), I should browse real AURA LAB products from HOME through SHOP and PRODUCT so that I can choose a fragrance to purchase.

• Provenance: explicit.
• HOME shall present AURA LAB and the tagline “A FRAGRANCE THAT LINGERS.”
• SHOP and PRODUCT shall use real Firestore-backed product information.
• The customer shall be able to open a product and select a size before adding to cart or choosing Buy Now.
• Product-loading, empty, unavailable, and retrieval-error states shall be observable and recoverable.
• Continuation: The customer proceeds to temporary cart handling or CHECKOUT.

FR-03 — Temporary Cart and Buy Now

As a Customer (Shopper), I should add a selected product size to a temporary cart or choose Buy Now so that I can proceed to checkout without creating an order prematurely.

• Provenance: explicit.
• A selected size is required before add-to-cart or Buy Now processing.
• Cart/cache information may use localStorage only as temporary cart/cache functionality.
• Orders shall not depend on localStorage.
• Failure/recovery: Invalid or unavailable product/size selections shall prevent checkout progression and permit the customer to select a valid available option.
• Continuation: A valid cart or Buy Now selection proceeds to CHECKOUT.

FR-04 — Checkout Data Collection and Validation

As a Customer (Shopper), I should provide valid delivery and order details at CHECKOUT so that AURA LAB can create a Cash on Delivery order.

• Provenance: explicit.
• CHECKOUT shall collect and validate customerName, phone, email, address, city, and customerNotes.
• The order shall use Cash on Delivery as the primary payment method.
• The checkout shall show cart items, subtotal, delivery fee, and total.
• All customer inputs shall be validated and sanitized.
• The cart shall be validated before confirmation.
• Product availability shall be validated before order persistence.
• Failure/recovery: The customer shall see actionable validation or availability feedback and may correct fields, amend selections, or retry.
• Continuation: Valid checkout data enables CONFIRM ORDER.

FR-05 — Verified Persistent Order Confirmation

As a Customer (Shopper), I should receive an order confirmation only after my complete order is successfully saved and retrievable from Firestore so that I never receive a false confirmation.

• Provenance: explicit.
• On CONFIRM ORDER, the system shall:
  1. Validate all checkout fields.
  2. Validate cart.
  3. Validate product availability.
  4. Prevent duplicate submission.
  5. Generate a unique customer-friendly order ID such as AURA-735462.
  6. Save the complete order to Firestore.
  7. Wait for a successful Firestore response.
  8. Verify that the order can be retrieved.
  9. Set status to CONFIRMED.
  10. Only then show ORDER CONFIRMED.
  11. Only then enable WhatsApp.
• The persisted order shall include orderId, customerName, phone, email, address, city, items, deliveryFee, total, paymentMethod, orderDate, createdAt, updatedAt, status, and customerNotes.
• Each items entry shall include productId, productName, size, quantity, unitPrice, and subtotal.
• Failure/recovery: If Firestore save or verification fails, the system shall never show success and shall show exactly: “Your order could not be confirmed. Please try again.”
• The system shall never silently lose an order.
• Continuation: A verified persisted order proceeds to ORDER CONFIRMATION and becomes visible to authorized admins.

FR-06 — Persistent Order Durability

As a Customer (Shopper), I should have my confirmed order retained in Firestore so that it remains available after I leave the site or change devices.

• Provenance: explicit.
• Firestore is the authoritative source of truth for orders.
• Orders shall survive refresh, browser restart, different browser, different device, customer leaving the site, and admin refresh.
• The orders, products, and customers collections shall exist as authoritative persistent collections. [required_inference]
• Observable result: A successfully confirmed order can be retrieved for secure customer tracking and authorized admin operations.

FR-07 — Order Confirmation Details and Continuation

As a Customer (Shopper), I should see a complete verified order confirmation so that I can review my order and continue to tracking or shopping.

• Provenance: explicit.
• ORDER CONFIRMATION shall display:
  • ✓ ORDER CONFIRMED
  • Thank you for choosing AURA LAB.
  • Order number in the AURA-XXXXXX format
  • Products
  • Sizes
  • Quantities
  • Prices
  • Subtotal
  • Delivery
  • Total
  • Payment method
  • Delivery address
  • Current status
• The page shall provide TRACK MY ORDER and CONTINUE SHOPPING actions.
• Continuation: TRACK MY ORDER opens /track-order using verified order context; CONTINUE SHOPPING returns the customer to SHOP.

FR-08 — Optional WhatsApp Order Sharing

As a Customer (Shopper), I should optionally send my confirmed order to WhatsApp so that I can share my order details without making WhatsApp necessary for order placement.

• Provenance: explicit.
• WhatsApp shall be optional and shall not be required to place an order.
• SEND ORDER TO WHATSAPP shall become available only after successful Firestore persistence and retrieval verification.
• The WhatsApp message shall include:
  • AURA LAB
  • Order ID
  • Customer
  • Products
  • Sizes
  • Quantity
  • Total
  • Delivery information
  • Tracking URL
• The tracking URL shall use the current runtime origin.
• Failure/recovery: Failure to open or use WhatsApp shall not invalidate, block, or remove the confirmed Firestore order.
• Continuation: The customer can track the order or continue shopping without using WhatsApp.

FR-09 — Secure Customer Order Tracking

As a Customer (Order Tracker), I should retrieve my real order at /track-order using my order number and phone, or another secure existing verification method, so that I can see its current delivery status.

• Provenance: explicit.
• /track-order shall support /track-order?order=AURA-XXXXXX&phone=03142087801.
• Tracking shall retrieve the real Firestore order and shall not use hard-coded sample orders.
• The default supported verification mechanism shall use order number plus phone unless another secure existing verification mechanism is already available.
• The tracker shall display order ID, customer, products, sizes, quantity, total, payment method, order date, address, and current status.
• The tracker shall display and highlight the current stage in the timeline:
  • CONFIRMED
  • PROCESSING
  • SHIPPED
  • OUT FOR DELIVERY
  • DELIVERED
• CANCELLED shall remain a valid current order status.
• Failure/recovery: If an order does not exist or verification fails, the tracker shall show a clear error and allow corrected details to be submitted.
• Continuation: A verified tracker sees the latest authorized admin-updated Firestore status.

FR-10 — Runtime-Origin Customer URLs

As a Customer (Shopper), I should receive tracking links generated from the active runtime origin so that links work on the actual deployed production host.

• Provenance: explicit.
• Customer-generated URLs, including tracking and WhatsApp links, shall use the current runtime origin, preferably window.location.origin.
• A generated tracking URL shall follow the form ${window.location.origin}/track-order?order=AURA-XXXXXX&phone=XXXXXXXXXXX.
• The application shall never hard-code an old domain.
• The application shall never assume auralab.pk exists.
• auralab.pages.dev shall not be used unless it is actually the active production domain.
• The project shall be searched for auralab.pages.dev, and incorrect references shall be removed from WhatsApp links, order records, redirects, frontend constants, backend constants, environment variables, and confirmation pages.
• Observable acceptance: Generated links resolve against the active deployed runtime origin rather than a fixed historic hostname.

FR-11 — Secure Admin Access

As an Admin (Store Operator), I should securely authenticate before entering restricted admin routes so that only authorized operators can access administrative data and actions.

• Provenance: explicit; admin provisioning is required_inference.
• /admin, /admin/orders, and /admin/products shall require secure authentication and authorization.
• Admin credentials shall be provisioned and authorized out-of-band; no public admin self-enrollment shall exist.
• Admin passwords and secrets shall never be exposed in frontend code.
• Failure/recovery: Unauthorized users shall not access restricted data or controls and shall be returned to Admin Login or a secure access-denied state.
• Continuation: Authorized admins may proceed to the relevant admin destination.

FR-12 — Real-Time Admin Order Visibility and Notifications

As an Admin (Store Operator), I should see real Firestore orders and newly arriving orders in real time so that I can operate the store without manual refresh.

• Provenance: explicit.
• Admins shall see real Firestore orders, not mock or sample orders.
• Firestore real-time listeners shall be used where appropriate so new orders appear without manual refresh.
• New-order notification content shall include:
  • 🔔 NEW ORDER
  • Order: AURA-XXXXXX
  • Customer: customer name
  • Total: Rs. X,XXX
• The system shall not repeatedly notify the same order after refresh.
• Failure/recovery: Listener or retrieval failures shall be surfaced clearly with recovery/retry behavior.
• Continuation: The admin may review details in /admin/orders.

FR-13 — Authorized Order Status Management

As an Admin (Store Operator), I should update the status of real orders so that customers see accurate tracking progress.

• Provenance: explicit.
• /admin/orders shall display order ID, customer, phone, email, products, sizes, quantity, subtotal, delivery, total, payment method, date, and status.
• Authorized admins may set status to:
  • CONFIRMED
  • PROCESSING
  • SHIPPED
  • OUT_FOR_DELIVERY
  • DELIVERED
  • CANCELLED
• Every authorized status update shall persist to Firestore and update updatedAt.
• Customer tracking shall show the updated status from Firestore.
• Failure/recovery: Unauthorized status changes shall be prevented; failed updates shall not be represented as successful and shall provide retry/recovery.
• Continuation: The updated order remains visible to the admin and retrievable through customer tracking verification.

FR-14 — Authorized Product Management

As an Admin (Store Operator), I should manage real Firestore product data at /admin/products so that customer browsing and checkout availability use the current catalog.

• Provenance: explicit.
• Product management shall operate on real Firestore product data.
• Product changes shall require admin authorization.
• Unauthorized product changes shall be prevented.
• Product availability used by customer checkout shall be derived from the current product catalog.
• Failure/recovery: Failed or unauthorized product updates shall not be shown as successful and shall support safe recovery.
• Continuation: Authorized changes become available to storefront product browsing and availability validation.

FR-15 — Security and Deployment Integrity

As a project operator, I should have secure, deployable Cloud Run-compatible commerce behavior so that customer and admin operations remain protected and functional in production.

• Provenance: explicit.
• The existing Google Cloud Run deployment architecture shall be retained.
• The production build shall work, the server shall start, routes shall work, Firestore shall work, orders shall persist, admin shall work, tracking shall work, WhatsApp shall work, and mobile shall work.
• Customers may perform only allowed customer operations.
• Admin operations shall require authorization.
• The application shall validate and sanitize all customer inputs.
• The application shall prevent duplicate orders, unauthorized status changes, unauthorized product changes, and unauthorized order access.
• The application shall never expose private API keys, Firebase Admin credentials, server secrets, or database credentials.
• The critical order lifecycle shall be actually tested before completion is claimed.

4. User Personas

Customer (Shopper)

• Provenance: required_inference from the accepted storefront and checkout journey.
• Product context: A public shopper in Pakistan purchasing an AURA LAB premium fragrance using Cash on Delivery.
• Primary goal: Choose a fragrance and size, submit a valid order, and receive a trustworthy order confirmation with a real customer-friendly order ID.
• Responsibilities and decisions: Browse real products, open a product, select a size, add to cart or choose Buy Now, provide validated customer and delivery details, review Cash on Delivery totals, and confirm the order.
• Interaction with other participants: The shopper creates an order that becomes visible to the Admin (Store Operator), who can later update its fulfillment status. WhatsApp may receive an optional customer-initiated message only after the order is verified.
• Observable success: A complete order is persisted and retrievable in Firestore with status CONFIRMED; the shopper sees ORDER CONFIRMATION and can track or optionally share the order.

Customer (Order Tracker)

• Provenance: required_inference from the accepted tracking journey.
• Product context: A returning customer who needs to verify and view the current status of a previously confirmed order without a customer account requirement.
• Primary goal: Securely retrieve a real order using the order number plus phone, or another secure existing verification method, and see the latest fulfillment state.
• Responsibilities and decisions: Provide or use order number and phone verification details; review order, delivery, payment, and current-status information; retry with corrected details if verification fails.
• Interaction with other participants: The tracker receives the observable outcome of status changes made by the Admin (Store Operator).
• Observable success: The tracker sees the real Firestore order and highlighted current status, or receives a clear error if the order cannot be found or verified.

Admin (Store Operator)

• Provenance: required_inference from the accepted admin and operational workflow.
• Product context: A provisioned AURA LAB staff member responsible for overseeing real orders and product catalog data.
• Primary goal: Securely monitor incoming orders, manage current product data, and maintain accurate customer-visible order statuses.
• Responsibilities and decisions: Authenticate through Admin Login; review real-time order activity; respond to new-order notifications; inspect complete customer/order data; change statuses only among accepted values; manage real product records.
• Interaction with other participants: The admin receives orders created by Customer (Shopper) and produces status changes that Customer (Order Tracker) can observe on the tracking page.
• Observable success: The admin sees live Firestore data, receives non-repeating new-order notifications, successfully persists authorized updates, and sees customer tracking