System Requirements Document for herbal-soap

1. Introduction

herbal-soap is an online store for herbal soap. The product intent is to build the best possible herbal soap store: a place where a shopper can discover a catalog of herbal soaps, examine an individual soap in detail, and complete a purchase of the soaps they chose; and where the person running the store can keep that catalog current and accurate so the storefront always reflects what is actually for sale.

The audience is twofold. The Shopper is a visitor who wants warmth, provenance, and sensory pleasure from a soap purchase rather than a clinical pharmacy or discount-retail experience. The Store Owner is the small-batch maker or shopkeeper who maintains the soap catalog — adding and updating soap products and their details — so that shoppers can browse and buy them.

The store is delivered as a first-party web application with its own identity, its own catalog and cart state, and its own purchase-order records. It is not a marketplace, not a subscription service, and not a provider-hosted storefront.

2. System Overview

herbal-soap is a custom web application composed of seven pages: a public Landing page, a Login page, a shopper-facing Products catalog, a Product Details page for an individual soap, a Checkout page that owns cart selection and purchase completion, and two Store Owner pages — Catalog for browsing and managing the durable soap catalog, and Product Editor for focused creation and editing of soap products and their details.

Two human actors use the system. The Shopper browses the soap catalog, reviews individual soap product details, selects soaps, and completes an order. The Store Owner maintains the soap catalog by adding and updating soap products and their details.

The application owns its own identity: shoppers establish an account for themselves before protected checkout continuity, returning shoppers and the Store Owner verify themselves on the Login page, and the Store Owner is provisioned or invited before catalog administration. Persistent backend storage and execution hold products, carts, accounts, and purchase orders.

Narrow exclusions. This document does not define shipping-carrier integration, tax engines, payment-provider selection, reviews or ratings, wishlists, loyalty programs, subscriptions, multi-currency pricing, multi-vendor marketplaces, or any analytics or marketing automation. Where a capability is not stated in the authoritative requirements, it is not part of this product.

2a. Product Interpretation and Delivery Boundary

The store is delivered entirely as a first-party application. Every page in the current product is owned and rendered by the application itself; there is no provider-hosted storefront, no external-only destination, and no headless delivery surface in the current scope.

Access is split into two boundaries. The Landing, Login, Products, and Product Details pages are reachable without an established identity — a visitor can read the store's introduction, browse the soap catalog, and examine an individual soap before deciding anything. The Checkout page and the two Store Owner pages (Catalog and Product Editor) are protected: they require an established, verified identity, and the Store Owner pages additionally require the Store Owner's provisioned role. The Login page is itself anonymously reachable, because a protected destination cannot own the interaction that establishes access to itself.

Identity is application-owned. A shopper establishes their own account before protected checkout continuity, and a returning shopper or the Store Owner verifies on Login. The Store Owner's access is established by invitation or provisioning rather than self-service enrollment, because catalog administration is a distinct responsibility from shopping.

Everything described in this document is current. No future-horizon features are defined; anything not listed here is out of scope rather than deferred.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no verified factual inventory is reproduced.

2c. Page Content and Component Coverage

Landing

• Information and state. The public entry to the herbal soap store. Presents the store's purpose — herbal soap made from things that grow — and routes visitors toward the catalog, toward identity, and toward the cart. No identity required; no protected state is exposed.
• Primary actions. Enter the soap catalog; open the Login page; open the cart/checkout path.
• Supporting actions. Read the store's introduction and material story; view the scent-family band as the catalog's primary filter navigation.
• Domain entities. Store introduction content; scent-family categories (floral / woody / citrus / resin) with counts; a small set of featured soap products drawn from the live catalog.
• Component responsibilities. Full-bleed two-room hero (oversized headline field against a full-height soap photograph, joined by a circular cure-date stamp); navigation bar with active-item underline and a cart-count badge; a three-up ingredients strip; a full-width scent-family band of four flat colour blocks with uppercase tracked labels and counts; a featured-soap sequence drawn from the catalog.
• States. Loading: hero and featured sequence render their structural frames while catalog data resolves. Empty: if the catalog has no published soaps, the featured sequence is replaced by a plain statement that the shelf is being restocked, and the scent-family band shows zero counts. Success: hero, ingredients strip, scent-family band, and featured soaps render. Error: if catalog data fails to load, the hero and static content still render and the featured sequence shows a retry affordance. Recovery: retry re-requests catalog data without leaving the page.

Login

• Information and state. The identity access surface for returning shoppers and the Store Owner. Anonymously reachable. Establishes the verified identity that protected destinations require.
• Primary actions. Verify a returning shopper or the Store Owner; establish a new shopper account.
• Supporting actions. Move between the returning-verification and new-account modes; return to the Landing page.
• Domain entities. Account credentials; account identity; the destination the visitor was attempting to reach.
• Component responsibilities. Mode switch between returning verification and new shopper enrollment; credential fields with inline validation; submit control with in-flight state; error region; post-verification routing back to the attempted protected destination.
• States. Loading: submit control shows in-flight state and is disabled against duplicate submission. Empty: fields begin empty with no error text. Success: identity is established and the visitor is routed to the protected destination they attempted, or to the catalog if none was attempted. Error: invalid credentials, an unrecognized account, or a duplicate enrollment attempt each show a specific, non-revealing message and preserve entered values except the credential. Recovery: the visitor can retry, switch modes, or return to the Landing page; a failed attempt never partially establishes identity.

Products

• Information and state. The shopper-facing browseable catalog of herbal soap products. Publicly reachable. Reflects the live published catalog maintained by the Store Owner.
• Primary actions. Browse the soap catalog; filter by scent family; open an individual soap's Product Details page; add a soap to the cart.
• Supporting actions. Read each soap's name, price, and scent-family chip; see the current cart count.
• Domain entities. Soap products (name, price, scent family, imagery, short description); scent-family categories; cart contents and count.
• Component responsibilities. Left rail of scent-family filter chips; three-column shelf with varied tile heights and one tall feature tile per row; per-tile name, price in the primary structural colour, and a categorical scent-family chip; cart-count badge in the navigation.
• States. Loading: shelf renders placeholder tiles in the final layout. Empty: when the catalog has no published soaps, the shelf is replaced by a plain statement that no soaps are currently listed, with the filter rail hidden. Success: shelf renders all matching soaps; the active filter is visibly marked. Error: a failed catalog request shows a retry affordance in place of the shelf while the filter rail remains usable. Recovery: retry re-requests the catalog; changing or clearing the filter re-requests with the new selection.

Product Details

• Information and state. The detail view for one herbal soap selected from the catalog. Publicly reachable. Shows the soap's full description, imagery, price, and ingredient ledger.
• Primary actions. Add the soap to the cart; adjust quantity before adding; return to the catalog.
• Supporting actions. Read the ingredient ledger as ruled label/value rows; read the cure-date stamp; move through the product image stack.
• Domain entities. The selected soap product (name, price, scent family, description, imagery, cure date); ingredient entries with names and percentages; cart contents and count.
• Component responsibilities. Sticky left image stack; right column with product name, price in the primary structural colour, and the ingredient ledger as ruled label/value rows with tabular numerals; scent-family chip; cure-date stamp; add-to-cart control with quantity; fixed bottom add-to-cart bar on narrow viewports.
• States. Loading: image stack and ledger render their structural frames while the product resolves. Empty: if the requested soap is not in the published catalog, the page states that the soap is unavailable and offers a return to the catalog. Success: the soap renders with its ledger; adding to cart shows the added confirmation and increments the cart count. Error: a failed product request shows a retry affordance; a failed add-to-cart shows an inline message and leaves the cart unchanged. Recovery: retry re-requests the product; a failed add can be retried without re-entering quantity.

Checkout

• Information and state. Owns cart selection and completion of a purchase order for chosen herbal soaps. Protected — requires an established, verified shopper identity. Cart state persists for the verified shopper across visits.
• Primary actions. Review and adjust cart line quantities; remove a line; confirm and place the purchase order.
• Supporting actions. Return to the catalog to add more soaps; see the order summary with totals.
• Domain entities. Cart lines (soap, quantity, unit price, line total); cart totals; the shopper's account; the placed purchase order with its line items, totals, and placement timestamp.
• Component responsibilities. Cart line list with quantity controls and remove actions; order-summary panel with line items and totals in tabular numerals; place-order control with in-flight state; confirmation region showing the placed order.
• States. Loading: cart and summary render their structural frames while cart state resolves. Empty: an empty cart shows a plain statement that nothing has been selected yet, with a route back to the catalog and the place-order control disabled. Success: the order is placed, the cart is cleared, and a confirmation shows the order's line items and totals. Error: a failed cart update leaves the previous quantity in place with an inline message; a failed order placement preserves the cart intact and shows a retryable message. Recovery: cart-update failures can be retried per line; a failed placement can be retried without re-entering the cart; an unverified visitor is routed to Login and returned to Checkout after verification with the cart preserved.

Catalog

• Information and state. The Store Owner's view of the durable herbal soap catalog. Protected — requires the Store Owner's provisioned identity. Shows every soap product in the catalog, including unpublished or incomplete entries, with its current state.
• Primary actions. Browse and search the full catalog; open a soap in the Product Editor; create a new soap product.
• Supporting actions. Read each entry's name, price, scent family, and publication state; see counts by scent family.
• Domain entities. All soap products regardless of publication state (name, price, scent family, publication state, last-updated timestamp); scent-family categories.
• Component responsibilities. Dense catalog table with tabular numerals and 8-point spacing; search and scent-family filtering; per-row publication state; create-new control; row action to open the Product Editor.
• States. Loading: table renders its structural frame while the catalog resolves. Empty: a catalog with no products shows a plain statement and a create-new control as the primary action. Success: all products render with their current state; a newly created or edited product appears with its updated values. Error: a failed catalog request shows a retry affordance; a failed create shows an inline message and creates nothing. Recovery: retry re-requests the catalog; a failed create can be retried from the same control.

Product Editor

• Information and state. Focused creation and editing of a single herbal soap product and its details. Protected — requires the Store Owner's provisioned identity. Operates on one product at a time, whether new or existing.
• Primary actions. Create a new soap product; edit an existing soap's name, price, scent family, description, imagery, cure date, and ingredient ledger; save changes; publish or unpublish the product.
• Supporting actions. Add, edit, and remove ingredient ledger rows with names and percentages; return to the Catalog without saving.
• Domain entities. A single soap product and all of its editable fields; ingredient entries with names and percentages; publication state; validation errors per field.
• Component responsibilities. Field group for identity and pricing; scent-family selector; description field; imagery management; cure-date input; ingredient ledger editor with add/remove rows and percentage entry; save and publish controls with in-flight state; per-field validation messaging; unsaved-changes guard on navigation away.
• States. Loading: fields render in a disabled state while an existing product resolves. Empty: a new product begins with empty fields and an empty ingredient ledger, with save disabled until required fields are valid. Success: saving persists the product and returns to the Catalog with the updated values visible; publishing makes the product visible in the shopper-facing catalog. Error: invalid or missing required fields block saving with per-field messages; a failed save preserves all entered values and shows a retryable message; a failed publish leaves the product's previous publication state unchanged. Recovery: correct the flagged fields and save again; retry a failed save or publish without re-entering data; the unsaved-changes guard prevents silent loss when navigating away.

3. Functional Requirements

FR-1 — Browse the soap catalog. As a Shopper, I should browse a catalog of herbal soap products so that I can see what the store sells. (explicit)

• Trigger/input: the Shopper opens the Products page.
• Observable result: the published soap catalog renders with each soap's name, price, and scent-family chip.
• Access state: publicly reachable; no identity required.
• Failure/recovery: if the catalog request fails, a retry affordance replaces the shelf while the filter rail remains usable.
• Continuation: the Shopper opens an individual soap or adds one to the cart.

FR-2 — Filter the catalog by scent family. As a Shopper, I should filter the catalog by scent family so that I can narrow the shelf to the kind of soap I want. (required_inference — the scent-family band is the catalog's primary filter navigation)

• Trigger/input: the Shopper selects a scent-family chip in the filter rail or the scent-family band.
• Observable result: the shelf shows only soaps in the selected family and the active filter is visibly marked.
• Access state: publicly reachable.
• Failure/recovery: a failed filtered request shows a retry affordance; clearing the filter restores the full shelf.
• Continuation: the Shopper opens a soap or clears the filter.

FR-3 — View individual soap product details. As a Shopper, I should view an individual herbal soap's details so that I can judge whether it is the soap I want. (explicit)

• Trigger/input: the Shopper selects a soap from the catalog.
• Observable result: the Product Details page renders the soap's name, price, imagery, description, cure-date stamp, and ingredient ledger as ruled label/value rows.
• Access state: publicly reachable.
• Failure/recovery: if the product request fails, a retry affordance is shown; if the soap is not in the published catalog, the page states it is unavailable and offers a return to the catalog.
• Continuation: the Shopper adds the soap to the cart or returns to the catalog.

FR-4 — Add a soap to the cart. As a Shopper, I should add a soap to my cart so that I can assemble the set of soaps I intend to buy. (required_inference — prerequisite for the accepted purchase outcome)

• Trigger/input: the Shopper activates add-to-cart on the Product Details page, optionally after setting a quantity.
• Observable result: the soap is added at the chosen quantity, an added confirmation appears, and the cart-count badge increments.
• Access state: publicly reachable; the cart is held for the session and bound to the shopper's account once identity is established.
• Failure/recovery: a failed add shows an inline message and leaves the cart unchanged; the Shopper can retry without re-entering quantity.
• Continuation: the Shopper continues browsing or proceeds to Checkout.

FR-5 — Establish a shopper account. As a Shopper, I should establish my own account so that my cart and my order remain mine and can be resumed. (required_inference — required for protected checkout continuity)

• Trigger/input: an unverified visitor attempts to reach Checkout, or chooses to establish an account from Login.
• Observable result: a new shopper account is created and the shopper is verified, with any in-progress cart preserved.
• Access state: the entry interaction is anonymous on the Login page; protected state remains unavailable until identity is established.
• Failure/recovery: a duplicate enrollment attempt or invalid input shows a specific, non-revealing message and preserves entered values except the credential; no partial identity is established.
• Continuation: the shopper is routed to the protected destination they attempted, or to the catalog.

FR-6 — Verify a returning identity. As a Shopper or the Store Owner, I should verify my returning identity so that I can reach the protected work that belongs to me. (required_inference — required for protected continuity and catalog administration)

• Trigger/input: the returning Shopper or Store Owner submits credentials on the Login page.
• Observable result: identity is verified and the actor is routed to the protected destination they attempted.
• Access state: the Login page is anonymously reachable; verification is what unlocks protected destinations.
• Failure/recovery: invalid credentials or an unrecognized account show a specific, non-revealing message; the actor can retry, switch modes, or return to the Landing page.
• Continuation: the Shopper reaches Checkout with the cart preserved; the Store Owner reaches Catalog.

FR-7 — Provision the Store Owner. As the Store Owner, I should be invited or provisioned before catalog administration so that catalog control is bound to the correct person. (required_inference — required for protected catalog administration)

• Trigger/input: the Store Owner accepts an invitation or is provisioned, then verifies on Login.
• Observable result: the Store Owner's identity carries the catalog-administration responsibility and the Catalog and Product Editor pages become reachable.
• Access state: provisioning is not self-service enrollment; the Store Owner pages are protected and role-restricted.
• Failure/recovery: an unprovisioned or unverified visitor attempting a Store Owner page is routed to Login and, once verified without the Store Owner responsibility, is returned to the public catalog rather than the protected page.
• Continuation: the Store Owner opens Catalog.

FR-8 — Review and adjust the cart. As a Shopper, I should review and adjust my cart so that the order I place is exactly the set of soaps I want. (required_inference — prerequisite for the accepted purchase outcome)

• Trigger/input: the verified Shopper opens Checkout and changes a line quantity or removes a line.
• Observable result: the cart line list and the order-summary totals update to reflect the change.
• Access state: protected; requires an established, verified shopper identity.
• Failure/recovery: a failed cart update leaves the previous quantity in place with an inline message and can be retried per line.
• Continuation: the Shopper places the order or returns to the catalog to add more soaps.

FR-9 — Complete a purchase. As a Shopper, I should complete a purchase of the herbal soaps I chose so that I receive the soaps I selected. (explicit)

• Trigger/input: the verified Shopper confirms the order on Checkout.
• Observable result: a purchase order is created with its line items, totals, and placement timestamp; the cart is cleared; a confirmation shows the placed order.
• Access state: protected; requires an established, verified shopper identity.
• Failure/recovery: a failed placement preserves the cart intact and shows a retryable message; the Shopper can retry without re-entering the cart.
• Continuation: the Shopper sees the confirmation and can return to the catalog.

FR-10 — Browse and manage the durable catalog. As the Store Owner, I should browse and manage the durable herbal soap catalog so that I can see and control everything the store sells. (explicit)

• Trigger/input: the Store Owner opens Catalog.
• Observable result: every soap product renders with its name, price, scent family, publication state, and last-updated timestamp, including unpublished entries.
• Access state: protected; requires the Store Owner's provisioned identity.
• Failure/recovery: a failed catalog request shows a retry affordance; a failed create shows an inline message and creates nothing.
• Continuation: the Store Owner opens a product in the Product Editor or creates a new one.

FR-11 — Create and edit soap products and their details. As the Store Owner, I should add and update soap products and their details so that shoppers can browse and buy them. (explicit)

• Trigger/input: the Store Owner opens Product Editor for a new or existing soap and edits its name, price, scent family, description, imagery, cure date, or ingredient ledger.
• Observable result: saving persists the product and returns to Catalog with the updated values visible.
• Access state: protected; requires the Store Owner's provisioned identity.
• Failure/recovery: invalid or missing required fields block saving with per-field messages; a failed save preserves all entered values and shows a retryable message; an unsaved-changes guard prevents silent loss on navigation away.
• Continuation: the Store Owner returns to Catalog, where the updated product appears.

FR-12 — Publish or unpublish a soap product. As the Store Owner, I should control whether a soap is published so that the storefront catalog stays accurate. (required_inference — required for the accepted outcome of a current, accurate storefront catalog)

• Trigger/input: the Store Owner sets publication state in the Product Editor.
• Observable result: a published soap appears in the shopper-facing Products catalog; an unpublished soap does not.
• Access state: protected; requires the Store Owner's provisioned identity.
• Failure/recovery: a failed publish leaves the product's previous publication state unchanged and shows a retryable message.
• Continuation: the Store Owner returns to Catalog, where the product's publication state is visible.

FR-13 — Persist products, carts, accounts, and purchase orders. As the system, I should persist products, carts, accounts, and purchase orders so that every accepted journey has durable state. (required_inference — required to make the accepted journeys executable)

• Trigger/input: any catalog read or write, cart change, identity establishment, or order placement.
• Observable result: products, carts, accounts, and purchase orders survive across requests and sessions, and a verified shopper's cart is restored on return.
• Access state: not human-facing; storage is reached only through the application.
• Failure/recovery: a failed persistence operation surfaces as the corresponding page-level error and recovery path above; no partial write is presented as success.
• Continuation: the affected page retries or reports the failure to its actor.

4. User Personas

Shopper

Product context. The Shopper arrives at herbal-soap looking for soap made from things that grow — a material product with a material story. They are not comparison-shopping a clinical pharmacy aisle or a discount retailer; they want warmth, provenance, and sensory pleasure, and they want to understand what is actually in the bar before they buy it.

Primary goal. To find the herbal soaps they want and complete an order for them.

Distinct accepted responsibilities. The Shopper is the only actor who browses the public catalog, filters it by scent family, examines an individual soap's ingredient ledger and cure date, assembles a cart, and places a purchase order. They are also the only actor who establishes their own account, and they do so specifically because checkout continuity must be theirs — the cart and the resulting order have to remain bound to the right person.

Relevant inputs and decisions. Which scent family to filter to; which soap to open; whether the ingredient ledger and cure date match what they want; how many bars to add; whether to keep or remove a cart line; whether to confirm the order.

Interactions with other accepted participants. The Shopper's work is shaped by the Store Owner's catalog: the soaps, prices, scent families, descriptions, imagery, and ingredient ledgers the Shopper reads are exactly what the Store Owner has published. A soap the Store Owner has unpublished simply is not on the shelf. The Shopper never interacts with the Store Owner directly, and never sees unpublished or incomplete catalog entries.

Observable success. The Shopper sees a confirmation showing the line items and totals of the order they placed, and the cart is cleared.

What makes this role different. The Shopper's work is discovery and commitment under no obligation — they can browse, filter, and abandon freely, and nothing they do changes the store's catalog. Their only durable artifact is their own account, cart, and order.

Store Owner

Product context. The Store Owner is the person running the herbal soap store — the small-batch maker or shopkeeper who knows the soaps, their ingredients, their cure dates, and which ones are ready to sell. They are not a developer or an administrator of a platform; they are the person who keeps the shelf honest.

Primary goal. A current, accurate storefront catalog of herbal soaps.

Distinct accepted responsibilities. The Store Owner is the only actor who browses the durable catalog including unpublished entries, creates new soap products, edits existing products' names, prices, scent families, descriptions, imagery, cure dates, and ingredient ledgers, and controls whether each soap is published to the storefront. Their access is established by invitation or provisioning rather than self-service enrollment, because catalog control must be bound to the correct person.

Relevant inputs and decisions. What the soap is called; what it costs; which scent family it belongs to; how to describe it; which imagery represents it; when it was cured; what its ingredient ledger is and in what proportions; whether it is ready to be published.

Interactions with other accepted participants. The Store Owner's work is what the Shopper sees. Every published soap, price, scent-family chip, description, image, cure-date stamp, and ingredient ledger row in the shopper-facing catalog originates from the Store Owner's edits. The Store Owner never sees a Shopper's cart or order, and never interacts with a Shopper directly.

Observable success. The Store Owner returns to Catalog and sees