System Requirements Document for receipts-items

1. Introduction

receipts-items is a personal purchase-ledger application. It scans paper receipts, extracts what the shopper bought, and keeps that purchase history in the cloud so the shopper can return later and search it. From that stored history the product does four further things: it lets the shopper re-purchase an item from the same store it was originally bought from, it checks whether the shopper was overcharged, it sorts every scanned item by price, and it presents monthly spend in a budgeting format.

The product intent is archival and forensic rather than promotional. A receipt is a document — columns, line items, totals, tax — and the application treats the shopper's accumulated receipts as a ledger that can be searched, ranked, audited and totalled. The audience is ordinary households and small-business buyers who want their own spending organised with the clarity of a printed statement.

The product name is receipts-items.

2. System Overview

receipts-items is delivered as a first-party web application with its own custom interface and its own application-owned identity. A shopper arrives anonymously at a public entry surface, establishes identity through self-service enrollment, and thereafter signs in to reach their private cloud-stored purchase history. All purchase data — receipts, line items, stores, prices, overcharge findings and monthly totals — belongs to the individual shopper and is only reachable after that shopper has verified their identity.

The current delivery comprises nine surfaces: a public Landing page, two anonymous identity surfaces (Sign Up and Login), and six signed-in working surfaces (Receipt Scan, Purchase Search, Re-purchase, Overcharges, Price Sort, Budget). The signed-in surfaces are protected; the Landing, Sign Up and Login surfaces are reachable without identity.

The single active human actor is the Receipt Scanner / Shopper. There are no secondary human roles, no shared team state, and no differentiated permissions: every signed-in surface shows that shopper their own data and only their own data.

Accepted behavior in the current horizon:

• Scanning a receipt to capture the purchased items it contains.
• Storing scanned purchase data in the cloud so it remains available for later retrieval.
• Searching stored purchases later.
• Re-purchasing an item from the same store it was bought from.
• Detecting and flagging when the shopper was overcharged.
• Sorting all scanned items by price.
• Showing monthly spend in a budgeting format.
• Self-service enrollment for first use, and returning verification for access to previously stored purchase history.

Narrow exclusions: the application does not provide shared or multi-user ledgers, does not provide role-based visibility or permission tiers, does not act as a payment processor or place orders on the shopper's behalf, and does not maintain a separate account-management area beyond establishing and verifying identity.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. receipts-items owns its own interface and its own identity. The shopper's purchase history is private to that shopper, so the application must be able to recognise a returning shopper and bind stored receipts to the correct person. That identity is established by the shopper themselves through self-service enrollment, and re-established on return through verification. The anonymous entry surfaces — Landing, Sign Up, Login — are deliberately reachable without identity, because a shopper cannot be asked to sign in to the page that creates their access in the first place. Every surface that reads or writes stored purchase history requires identity first.

Cloud persistence. Scanned purchase data is held in the cloud rather than on the device, so that search, repurchase lookup, overcharge review, price ranking and monthly budgeting all read from the same durable store across sessions and devices. This persistence is what makes "come back and search for later" a real capability rather than a session artifact.

Current horizon. Everything described in Sections 3 through 5 is current: scanning, cloud storage, search, repurchase from the same store, overcharge flagging, price sorting, monthly budgeting, enrollment and returning verification.

Future horizon. No future-horizon capabilities were accepted in the authoritative thread. Nothing in this document should be read as committing to adjacent money-management features such as bank-account linking, shared household ledgers, price prediction, or automated ordering.

Boundary of the overcharge capability. The application detects and flags when the shopper was overcharged on a scanned purchase and presents that finding for review. It does not file disputes, contact merchants, or issue refunds on the shopper's behalf.

Boundary of the re-purchase capability. The application helps the shopper re-purchase an item from the same store it was originally bought from, using the store identity recorded on the original receipt. It does not process payment or place the order itself.

2c. Page Content and Component Coverage

Landing

• Information and state. Anonymous public entry. Presents the product proposition: scan receipts, keep purchases in the cloud, search them later, re-purchase from the same store, catch overcharges, sort items by price, and see monthly spend as a budget. No shopper data is shown and no stored state is read.
• Primary actions. Begin enrollment (to Sign Up); go to returning verification (to Login).
• Supporting actions. Read the explanatory sections describing each of the seven accepted capabilities; view the annotated receipt artefact.
• Domain entities. None owned. The page describes Receipt, Line Item, Store, Overcharge Finding, Price Ranking and Monthly Spend conceptually only.
• Component responsibilities. Split hero (oversized flush-left headline, single red underline rule, one line of body copy, red rectangular CTA cut into the headline baseline, photographed receipt stack with mustard ruled overlay and red circled total, full-height hairline vertical divider); numbered wayfinding rail; capability sections, each introduced by a numbered heading block (small all-caps mustard label, large flush-left condensed headline, full-width hairline rule); footer.
• States. Loading: static content, no data fetch, no skeleton required. Empty: not applicable. Success: page renders fully with both entry actions available. Error: if the entry actions cannot be reached, the page still renders its explanatory content and states that enrollment is temporarily unavailable. Recovery: the shopper can retry the entry action or reload.

Sign Up

• Information and state. Anonymous identity surface. Collects the minimum information needed to create the shopper's own account so that scanned receipts can be bound to them. States plainly that purchase history is private to the account.
• Primary actions. Submit enrollment to create the account and enter the signed-in application.
• Supporting actions. Move to Login if the shopper already has an account; return to Landing.
• Domain entities. Shopper Account (created).
• Component responsibilities. Enrollment form with labelled inputs at 4px radius; inline field-level validation messages; submit control in signal red; link to Login; link back to Landing.
• States. Loading: submit control shows an in-progress state and is disabled while the request is in flight. Empty: form presented with no values entered. Success: account created and the shopper is taken into the signed-in application. Error: an already-enrolled identity, an invalid or incomplete field, or a failed request is reported inline against the offending field or at form level, with entered values preserved. Recovery: the shopper corrects the field and resubmits, or follows the Login link.

Login

• Information and state. Anonymous identity surface for returning shoppers. Verifies identity before any stored purchase history is shown.
• Primary actions. Submit verification to reach the signed-in application.
• Supporting actions. Move to Sign Up if the shopper has no account; return to Landing.
• Domain entities. Shopper Account (verified).
• Component responsibilities. Verification form with labelled inputs; inline error region; submit control in signal red; link to Sign Up; link back to Landing.
• States. Loading: submit control shows an in-progress state and is disabled while verification is in flight. Empty: form presented with no values entered. Success: identity verified and the shopper lands on their signed-in working surface. Error: unrecognised credentials or a failed request are reported without revealing whether an account exists, and without clearing the entered identifier. Recovery: the shopper retries, or follows the Sign Up link.

Receipt Scan

• Information and state. Signed-in capture surface. Shows the current capture state — awaiting a receipt, receipt captured, items extracted, or extraction failed — and the extracted line items with store, date, item description, quantity and price.
• Primary actions. Capture a receipt image; confirm the extracted line items into cloud-stored purchase history.
• Supporting actions. Review and correct an extracted line item before confirming; discard a capture and start again; move to Purchase Search, Overcharges, Price Sort or Budget.
• Domain entities. Receipt, Line Item, Store, Purchase Record.
• Component responsibilities. Capture control; single scanning sweep animation on capture; receipt preview as a photographed paper artefact; extracted line-item table with hairline 1px rules at 12% ink opacity and right-aligned tabular price column; per-row correction control; confirm control in signal red; discard control.
• States. Loading: capture in progress shows the scanning sweep; extraction in progress shows a ruled placeholder table. Empty: no receipt captured yet — the surface invites a first capture. Success: line items extracted and listed; on confirmation the receipt and its items are written to cloud-stored purchase history and the surface reports the receipt as recorded. Error: an unreadable or unsupported image, or an extraction that yields no line items, is reported with the capture preserved so the shopper can retry or correct manually. Recovery: retake the image, correct the affected rows, or discard and recapture.

Purchase Search

• Information and state. Signed-in search surface over the shopper's cloud-stored purchase history. Shows the query, the matching line items, and for each match the item description, price, quantity, purchase date and store.
• Primary actions. Enter a query and run a search over stored purchases.
• Supporting actions. Open a matching item to see its full receipt context; move from a match to Re-purchase; clear the query; move to Receipt Scan, Overcharges, Price Sort or Budget.
• Domain entities. Purchase Record, Line Item, Receipt, Store.
• Component responsibilities. Query input at 4px radius; results table with hairline row rules and right-aligned tabular price column; per-row store monogram tile; per-row action to open the item; per-row action to re-purchase; empty-result region.
• States. Loading: results region shows a ruled placeholder while the query runs. Empty: no query entered — the surface invites a search; or a query with no matches — the surface states that nothing matched and offers to clear the query. Success: matching items listed with store, date and price. Error: a failed search request is reported with the query preserved. Recovery: retry the search or clear the query and search again.

Re-purchase

• Information and state. Signed-in surface for re-purchasing a specific item from the same store it was originally bought from. Shows the item, its original price and purchase date, and the store identity recorded on the original receipt.
• Primary actions. Confirm the item and store to re-purchase, and record the re-purchase against the shopper's history.
• Supporting actions. Change which store is used when the item was bought from more than one store; return to Purchase Search to pick a different item; move to Receipt Scan, Overcharges, Price Sort or Budget.
• Domain entities. Line Item, Store, Purchase Record, Re-purchase Record.
• Component responsibilities. Item summary block with tabular price and date; store identity block with monogram tile; store selection when more than one store is available for the item; confirm control in signal red; cancel control; confirmation summary.
• States. Loading: item and store details load with a ruled placeholder. Empty: no item selected — the surface directs the shopper to Purchase Search to choose one. Success: the re-purchase is confirmed and recorded, and the surface shows the item, the store and the date. Error: the item or its store can no longer be resolved, or the confirmation request fails; the surface states which part failed and preserves the selection. Recovery: return to Purchase Search to reselect the item, choose another store, or retry the confirmation.

Overcharges

• Information and state. Signed-in review surface listing the overcharge findings flagged for the shopper's scanned purchases. Each finding shows the item, the price paid, the expected price, the difference, the store and the receipt it came from.
• Primary actions. Review a flagged finding and mark it as reviewed.
• Supporting actions. Open the originating receipt and the exact line on it; move to Purchase Search for the item; move to Receipt Scan, Price Sort or Budget.
• Domain entities. Overcharge Finding, Line Item, Receipt, Store.
• Component responsibilities. Findings list where each row carries a red rule that draws left-to-right over 220ms and a counted-up difference in tabular numerals; receipt thumbnail with a small red circled figure at the exact line; per-row review control; link to the originating receipt.
• States. Loading: findings list loads with a ruled placeholder. Empty: no overcharges flagged — the surface states that no overcharges were found across the scanned receipts. Success: findings listed with item, paid price, expected price, difference, store and receipt reference; a reviewed finding is marked as reviewed. Error: a failed findings request is reported with a retry control. Recovery: retry the request; if a finding cannot be resolved to its receipt, the surface states that and keeps the finding visible.

Price Sort

• Information and state. Signed-in ranked view of all scanned items ordered by price. Each row shows the item, its price, the store and the purchase date, with a mustard proportional bar behind the price so the list reads as a bar chart and a table at once.
• Primary actions. Change the sort direction between ascending and descending price.
• Supporting actions. Open an item's receipt context; move to Purchase Search for the item; move to Re-purchase for the item; move to Receipt Scan, Overcharges or Budget.
• Domain entities. Line Item, Price Ranking, Store, Receipt.
• Component responsibilities. Ranked list with a mustard proportional bar running down the left edge of each row; right-aligned tabular price column; hairline 1px row rules; sort-direction control; instant tabular re-sort with no decorative motion.
• States. Loading: ranked list loads with a ruled placeholder. Empty: no scanned items yet — the surface directs the shopper to Receipt Scan. Success: all scanned items ranked by price with the proportional bar reflecting each price against the highest price in the list. Error: a failed ranking request is reported with a retry control. Recovery: retry the request; the previously loaded ranking remains visible until the retry succeeds.

Budget

• Information and state. Signed-in monthly ledger of spend. Shows the selected month, the shopper's spend for that month, week columns with their subtotals, and a running total rule above the month total. All monetary values are set in tabular Fira Sans.
• Primary actions. Select the month to review.
• Supporting actions. Move between months; open the receipts contributing to a week or to the month; move to Receipt Scan, Purchase Search, Overcharges or Price Sort.
• Domain entities. Monthly Spend, Week Subtotal, Receipt, Line Item, Store.
• Component responsibilities. Month selector; monthly ledger with week columns; running total rule above the month total; mustard data marks for budget and spend; schematic bar and line diagrams drawn in Fira Sans numerals and mustard rules; drill-down from a week or the month to the contributing receipts.
• States. Loading: ledger loads with a ruled placeholder. Empty: no receipts recorded for the selected month — the surface states that and offers to move to Receipt Scan. Success: month, week subtotals and running total displayed with tabular numerals. Error: a failed spend request is reported with a retry control and the month selection preserved. Recovery: retry the request or select a different month.

3. Functional Requirements

FR-1 — Scan a receipt to capture purchased items (explicit) As a Receipt Scanner / Shopper I should scan a receipt so that the items I bought are captured from it.

• Trigger/input: the shopper captures a receipt image on Receipt Scan.
• Observable result: the receipt is read and its line items — description, quantity and price — are listed for review, with the store and purchase date taken from the receipt.
• Access state: signed in.
• Failure/recovery: if the image is unreadable or unsupported, or no line items can be extracted, the capture is preserved and the shopper can retake the image, correct rows manually, or discard and recapture.
• Continuation: the shopper confirms the extracted items, which writes the receipt into cloud-stored purchase history.

FR-2 — Store scanned purchase data in the cloud for later retrieval (explicit) As a Receipt Scanner / Shopper I should have my scanned purchases kept in the cloud so that I can come back and retrieve them later.

• Trigger/input: the shopper confirms a scanned receipt.
• Observable result: the receipt, its line items, its store and its purchase date are persisted to cloud storage bound to the shopper's account, and remain available in later sessions and on other devices.
• Access state: signed in; the stored data is private to the shopper who confirmed it.
• Failure/recovery: if persistence fails, the surface reports the failure and keeps the confirmed items available so the shopper can retry the save.
• Continuation: the stored data becomes the source for search, repurchase, overcharge review, price sorting and monthly budgeting.

FR-3 — Search stored purchases later (explicit) As a Receipt Scanner / Shopper I should search my stored purchases so that I can find something I bought before.

• Trigger/input: the shopper enters a query on Purchase Search.
• Observable result: matching line items from cloud-stored purchase history are listed with item description, price, quantity, purchase date and store.
• Access state: signed in.
• Failure/recovery: if the search request fails, the query is preserved and the shopper can retry; if nothing matches, the surface says so and offers to clear the query.
• Continuation: the shopper opens a match for its full receipt context or moves to Re-purchase for that item.

FR-4 — Re-purchase an item from the same store it was bought from (explicit) As a Receipt Scanner / Shopper I should re-purchase an item from the same store I originally bought it from so that I can buy it again without hunting for where it came from.

• Trigger/input: the shopper selects a found item and confirms the re-purchase on Re-purchase.
• Observable result: the item is presented with its original price, purchase date and the store identity recorded on the original receipt; on confirmation the re-purchase is recorded against the shopper's history with the item, the store and the date.
• Access state: signed in.
• Failure/recovery: if the item or its store can no longer be resolved, or the confirmation fails, the surface states which part failed and preserves the selection so the shopper can reselect the item, choose another store, or retry.
• Continuation: the shopper returns to Purchase Search for another item or moves to another working surface.

FR-5 — Detect and flag when the shopper was overcharged (explicit) As a Receipt Scanner / Shopper I should be told when I was overcharged so that I can see where I paid more than I should have.

• Trigger/input: a receipt is scanned and its line items are stored.
• Observable result: overcharge findings are flagged for the shopper's scanned purchases and listed on Overcharges, each showing the item, the price paid, the expected price, the difference, the store and the originating receipt.
• Access state: signed in.
• Failure/recovery: if the findings request fails, the surface reports it with a retry control; if a finding cannot be resolved to its receipt, the surface states that and keeps the finding visible.
• Continuation: the shopper reviews a finding, opens the exact line on the originating receipt, and marks the finding as reviewed.

FR-6 — Sort all scanned items by price (explicit) As a Receipt Scanner / Shopper I should see all my scanned items sorted by price so that I can compare what I paid across everything I bought.

• Trigger/input: the shopper opens Price Sort, or changes the sort direction.
• Observable result: every scanned item is ranked by price with a mustard proportional bar behind each price, and the ranking re-sorts instantly when the direction changes.
• Access state: signed in.
• Failure/recovery: if the ranking request fails, the surface reports it with a retry control and keeps the previously loaded ranking visible.
• Continuation: the shopper opens an item's receipt context, searches for the item, or moves to Re-purchase.

FR-7 — Show monthly spend in a budgeting format (explicit) As a Receipt Scanner / Shopper I should see my monthly spend in a budgeting format so that I can understand what I spent in a month.

• Trigger/input: the shopper opens Budget and selects a month.
• Observable result: the selected month's spend is shown as a ledger with week columns, their subtotals, and a running total rule above the month total, all in tabular numerals.
• Access state: signed in.
• Failure/recovery: if the spend request fails, the surface reports it with a retry control and preserves the month selection; if the month has no receipts, the surface states that and offers to move to Receipt Scan.
• Continuation: the shopper moves between months or drills into the receipts contributing to a week or to the month.

FR-8 — Self-service enrollment for a shopper's first use (required_inference) As a Receipt Scanner / Shopper I should be able to create my own account so that my scanned receipts can be stored and returned to me.

• Trigger/input: the shopper chooses to begin enrollment from Landing and submits the enrollment form on Sign Up.
• Observable result: an account is created for the shopper and they enter the signed-in application.
• Access state: anonymous — Sign Up is reachable without identity, because a shopper cannot be required to sign in to the surface that creates their access.
• Failure/recovery: an already-enrolled identity, an invalid or incomplete field, or a failed request is reported inline with entered values preserved; the shopper corrects and resubmits, or follows the Login link.
• Continuation: the shopper proceeds to Receipt Scan to capture their first receipt.

FR-9 — Returning verification for access to previously stored purchase history (required_inference) As a Receipt Scanner / Shopper I should be able to verify myself on return so that I can reach the purchase history I stored before.

• Trigger/input: the shopper chooses returning verification from Landing and submits the verification form on Login.
• Observable result: identity is verified and the shopper reaches their signed-in working surface with their own stored purchase history available.
• Access state: anonymous — Login is reachable without identity; the stored purchase history behind it is not.
• Failure/recovery: unrecognised credentials or a failed request are reported without revealing whether an account exists and without clearing the entered identifier; the shopper retries or follows the Sign Up link.
• Continuation: the shopper moves to any signed-in working surface.

FR-10 — Cloud persistence of scanned purchase data so it remains available for later search, repurchase, overcharge review, price sorting and budgeting (required_inference) As a Receipt Scanner / Shopper I should have one durable store of my purchases so that every view of my spending reads from the same record.

• Trigger/input: any confirmed receipt, any recorded re-purchase, and any review action taken on a finding.
• Observable result: search, repurchase lookup, overcharge findings, price ranking and monthly spend all read from the same cloud-stored purchase history bound to the shopper's account, and stay consistent with each other across sessions.
• Access state: signed in; the store is private to the owning shopper.
• Failure/recovery: if the store is unreachable, the affected surface reports the failure with a retry control and preserves the shopper's in-progress input.
• Continuation: the shopper retries, or continues on a surface whose data is already loaded.

4. User Personas

Receipt Scanner / Shopper

Product context. The shopper is an ordinary household or small-business buyer who accumulates paper receipts and wants them to behave like a record rather than like clutter. They scan a receipt shortly after a purchase, and they come back later — days or weeks afterwards — to find out what they bought, what they paid, whether they were charged correctly, and how the month is adding up. They are not an analyst and they are not managing anyone else's spending; the ledger is theirs alone.

Primary goal. To have every receipt they scan turn into a searchable, price-ranked, auditable record of their own spending, and to be able to act on it — find an item, buy it again from the same store, see where they were overcharged, and read the month as a budget.

Distinct accepted responsibilities.

• Capturing receipts and confirming the extracted line items into cloud-stored purchase history (FR-1, FR-2).
• Searching that stored history for something bought before (FR-3).
• Re-purchasing a found item from the same store it originally came from (FR-4).
• Reviewing overcharge findings and marking them reviewed (FR-5).
• Reading all scanned items ranked by price and changing the ranking direction (FR-6).
• Reading monthly spend as a ledger with week subtotals and a running total (FR-7).
• Establishing their own account on first use and verifying themselves on return (FR-8, FR-9).

Relevant inputs and decisions. The shopper supplies receipt images, corrections to extracted line items, search queries, the choice of which item to re-purchase and which store to use when an item came from more than one, the decision to mark a finding reviewed, the sort direction on Price Sort, and the month selected on Budget. The consequential decisions are which item to re-purchase and from which store, and whether a flagged overcharge is accepted as reviewed.

Interactions with other accepted participants. There are none. The shopper is the only active human actor in the product; every surface shows that shopper their own data, and no other person participates in, approves, or receives the outcome of any capability. The only counterparties are the stores recorded on receipts, which are data entities rather than participants, and the cloud store, which is a system responsibility rather than an actor.

Observable success. A scanned receipt appears in search results with its store, date and price; a re-purchase is confirmed and recorded against the item and its original store; an overcharge finding shows the price paid