How Purchase Compass works

The form asks for the category before the item name on purpose. Picking the food group first (Produce, Whole grains, Seafood, etc.) means the item is scored correctly on the Health dashboard right away — no extra editing needed.

There's also an Organic checkbox right next to the item name. Tick it for organic produce, dairy, or meat and the label "(organic)" is added so the item shows up that way in charts, search, and the health drill-down.

Most trips have more than one item. After you save the first item, the store and date stay locked in at the top of the form and an Add another item to this purchase button appears. Each new item rolls into the same receipt — one trip, one entry, one row in the receipts list.

For example, a Saturday at the farmer's market becomes a single "Farmers Market" receipt with five line items, instead of five separate one-item receipts cluttering up your library.

Type the store however you like — TRADER JOE'S, trader joe's, or Trader Joe's. Purchase Compass normalises store names to Title Case before saving, so the same shop always groups together in the Spend by store chart and the Receipts list.

Your receipt image or PDF is read by the AI to pull out the store, date, line items, and totals. The original file is kept alongside those details — open any receipt in the Receipts list and click View original to pull up the exact image or PDF you uploaded. Delete a receipt and we delete the file with it.

Only you can see your receipts and their originals — they're scoped to your account.

The same image or PDF is also saved straight to your own Google Drive when Sheets storage is active. The spreadsheet keeps a link back to each original file. Purchase Compass only ever sees the files it uploaded for you — nothing else in your Drive.

• Total spend — sum of every receipt total in the current filter.
• Receipts — how many separate receipts are included.
• Items bought — number of distinct line items (weighed produce like 0.45 lb apples counts as 1).
• Avg / receipt — total spend ÷ receipts. A quick read on basket size.

Shows where your money goes across categories like Fruits, Vegetables, Dairy, Meat & Seafood, Bakery, Pantry, Frozen, Beverages, Snacks, Household, Personal Care, and Other.

Click any slice (or any name in the legend) to filter the rest of the dashboard to that category — the Top items chart and the new category detail table below it update to match.

The 10 line items you spent the most money on, summed across every receipt. Same item names are grouped — "Organic Bananas" and "ORGANIC BANANAS" count as one row.

When a category is selected in the donut, this chart shows only the top items inside that category.

Appears only when a category is selected. Lists every purchase in that category — date, item, store, quantity, unit price, and line total — sorted by most recent. Great for answering questions like "how much have I actually spent on snacks this month?"

Tracks unit prices for items you've bought on at least two different dates. Toggle between:

• ▲ Biggest increases — items whose price has risen the most since you first bought them.
• ▼ Biggest drops — items that have gotten cheaper.

Sparse data is normal at first — the chart fills in as you import more receipts containing the same products.

Total spend per day across the current filter. Useful for spotting weekly shopping rhythms or one-off big-shop days. Only appears when you have receipts on two or more distinct dates.

Horizontal bars ranking each store by total spend. Only shown when the Store filter is set to "All stores" and you've shopped at more than one place.

The raw data. Every receipt is collapsed by default — click one to expand and see every line item with its category, quantity, and total. This is the source of truth for everything above.

Two cleanup buttons live in the header: Remove duplicates merges receipts with the same store, date, and total (keeping the most detailed copy), and Clear data wipes everything in the current backend.

For each staple you can pick one of four states. Your choices are saved in your browser and persist between visits.

• On hand — you already have it.
• Need to buy — running low or out.
• Nice to have — not essential, but you'd pick it up.
• Not right now — skip it this trip.

Use the Include toggle bar at the top to show only the statuses you care about (for example, just Need to buy). The counter shows how many items match. Click Download PDF to export a clean, printable shopping list grouped by section and category, with checkboxes ready for the store.

The PDF is generated locally in your browser — nothing leaves your device.

• Cover page — the CompassMark logo, report title, generation date, and a summary of the active filters (store, date range, categories, organic-only toggle, and receipt count).
• One chart per page — each selected chart is captured exactly as it appears on screen, including any category or date filter you've applied.

The file is named purchase-compass-report-YYYY-MM-DD.pdf. Like the shopping list, the PDF is built entirely in your browser.

Above the chart grid you'll find Select all and Clear links to quickly mark every chart, or start from scratch. The download button also shows a live count of how many charts are selected.

The big half-circle at the top is your overall Mediterranean-diet score (0 to 100) for the last 30 days, paired with a letter grade (A through F). The full arc is always shown in light grey so you can see where you are on the scale, with a colour fill from the left up to your current score and a small dot marking the spot.

Below the gauge you'll see how this month's grade compares to last month's, so improvements (or slips) are obvious at a glance.

The Highlights card pulls out the top healthy food groups you've actually spent money on, plus your healthy spend share — what percentage of your grocery dollars went to items scoring 60 or higher. It's the "what am I doing right?" panel.

A donut chart showing where your food spending is distributed across the 11 Mediterranean food groups (Produce, Whole grains, Legumes & nuts, Seafood, Lean protein, Dairy, Olive oil & healthy fats, Red & processed meat, Sweets & processed, Alcohol, Other).

Click any slice or legend row to open a drill-down panel that lists the actual items behind that group — name, number of purchases, total spend, and item score. Now you can see exactly what's driving your produce number, or which sweets are pulling your score down.

For each food group, the diet has a target share of your weekly food spend (e.g. produce should be a large slice, dairy should be small). The compliance card shows how close you are with a chip next to every group:

• On target (green) — you're hitting the target, or staying within the cap.
• Under target (amber) — you should be buying more of this food group.
• Over cap (red) — you're buying too much of a "less-is-better" group (sweets, red meat, alcohol).

The bar below each row visualises where you sit relative to the target line. The number on the right is your 0–100 compliance score for that group, and the line below shows your actual % of food spend versus the target or cap.

Just like the donut, click any row to open the drill-down and see which items make up that group.

Side-by-side numbers for total spend and healthy-spend share versus the previous 30 days, plus the food groups that moved most (in either direction). Increases in good groups and decreases in less-healthy groups show up in green; the reverse shows up in red.

If you've only been using Purchase Compass for a short while, this card will show a friendly "Not enough history yet" message instead of misleading percentages — comparisons need a real month of prior data first.

The Missing foods card is a simple checklist of Mediterranean staples we couldn't find in your last 90 days of receipts (olive oil, beans & lentils, seafood, nuts & seeds, whole grains, leafy greens). Tick them off your next shopping list to fill the gaps.

The Improvement opportunities card suggests one or two swaps that would likely lift your score the most — for example, swapping a heavily-bought sugary cereal for a whole-grain option. Each suggestion shows the estimated point gain.

At the bottom of the page, the Trend chart plots your weekly health score over time so you can see whether the long-term direction is up or down. The Red flags list calls out specific low-scoring items you're buying repeatedly — useful for spotting a single habit that's dragging your score.

The overall score, letter grade, healthy-spend %, and Highlights card are part of the free experience. The compliance breakdown, drill-down dialog, month-over-month comparison, missing-foods checklist, improvement ideas, weekly trend, and red flags unlock with the Purchase Compass Health add-on.

• Cloud (default) — zero setup. Data is private to your account. Email forwarding works out of the box. Best for most people.
• Google Sheets — data lives in a spreadsheet in your own Google Drive. Purchase Compass never sees it; you can edit, share, or export it freely. Requires a one-time setup in Google Cloud Console.

Before the "Connect Google" button can work, an OAuth Client ID has to exist for Purchase Compass. The Storage card on the home page has an info button with the full checklist; the short version is:

1. In Google Cloud Console, enable the Google Sheets API and Google Drive API.
2. On the OAuth consent screen, add scopes auth/spreadsheets and auth/drive.file.
3. Create an OAuth 2.0 Client ID → Web application and add these Authorized JavaScript origins:
   • https://www.purchasecompass.app
   • https://purchasecompass.app
   • https://purchasecompass.lovable.app
   • http://localhost:5173 (only for local dev)
4. Paste the Client ID into VITE_GOOGLE_OAUTH_CLIENT_ID in .env.

1. On the home page, find the Storage card and switch from Cloud to Google Sheets.
2. Click Connect Google. A Google consent popup opens — sign in and approve Sheets + Drive access.
3. Choose Create new spreadsheet (recommended) or Pick existing via the Google Picker. Purchase Compass writes a header row automatically.
4. The header pill at the top of the app now shows the spreadsheet name, and every upload goes straight into your sheet.

One row per receipt with these columns:

date | store | currency | subtotal | tax | total | items_json | drive_file_id | drive_view_url

items_json holds the line items as a JSON string. Purchase Compass reads it back automatically — don't edit that column by hand unless you keep valid JSON.

The last two columns are populated only when Drive archival is on (see next section). Existing 7-column sheets are upgraded automatically the next time you link them.

The inbound email webhook can't reach your browser-held Google token, so forwarded receipts always land in the Cloud backend first. To move them into your sheet, switch the toggle back to Cloud briefly, confirm the receipts are there, then export/sync them across — or just stay on Cloud for inboxes you forward to.

You can toggle the storage backend any time. The choice is per-device (stored in your browser), and disconnecting Google revokes Purchase Compass's access immediately. Your spreadsheet stays in your Drive — Purchase Compass never deletes it.

The same Google connection you use for Sheets already grants the drive.file scope (it's been part of the consent screen from day one). As soon as Sheets is connected, Drive archival turns on — there's nothing new to enable, no extra OAuth prompt.

The drive.file scope is the minimum-privilege option: Purchase Compass can only see and touch files it created. The rest of your Drive is invisible to the app.

On the first upload Purchase Compass creates a top-level Purchase Compass folder and organises receipts by year and month based on the receipt date (falling back to today if the AI couldn't read a date):

Purchase Compass/
├── Purchase Compass Receipts.gsheet
└── Receipts/
    ├── 2026/
    │   ├── 06/
    │   │   ├── 2026-06-12_Whole-Foods_24.81_a1b2.jpg
    │   │   └── 2026-06-12_Shell_52.10_c3d4.pdf
    │   └── 05/
    └── 2025/

Filenames follow YYYY-MM-DD_Store_Total_shortid.ext so the folder is sortable, scannable by eye, and collision-proof even if two receipts share a store and total.

You can rename the Purchase Compass folder if you like — Purchase Compass tracks it by ID, not by name. Move it anywhere in your Drive and the link to each receipt row stays valid.

Every row written to the sheet is stamped with a drive_file_id and a clickable drive_view_url. Open the URL in any browser to view the original receipt in Google Drive — useful for warranty claims, expense reports, or tax time.

If a single PDF contains multiple receipts, the source file is uploaded once and the same Drive ID is stamped on every extracted row, so you can always trace a row back to its source.

Drive archival is best-effort. If the upload fails (offline, quota, revoked token), Purchase Compass still saves the parsed receipt data and shows a non-blocking warning — your spreadsheet stays in sync, just without the Drive link on that row.

Deleting a row from the sheet does not delete the file from Drive. The original stays as a safety net; clean up manually in Drive if you want it gone.

Home Screen installation only works in Safari. Other browsers on iPhone (Chrome, Edge, Firefox) do not support it correctly.

Open Safari and navigate to https://purchasecompass.app/app. Log into your account if prompted and wait until the app finishes loading.

At the bottom of Safari, tap the Share icon — the square with an arrow pointing up (⬆️ inside a square).

In the Share sheet, scroll down until you see Add to Home Screen and tap it.

Safari will suggest Purchase Compass. You can leave it as-is or change it. Then tap Add in the upper-right corner.

A new Purchase Compass icon now appears on your Home Screen. Tap it any time to launch the app — no need to open Safari first.

You can move the icon wherever you like: touch and hold it, choose Edit Home Screen, drag it into place, then tap Done.

• One-tap access from your Home Screen.
• Full-screen experience without Safari's address bar.
• Faster startup and an app-like feel.
• Keeps you signed in.

I don't see "Add to Home Screen"

• Make sure you're using Safari.
• Make sure you're on https://purchasecompass.app/app.
• Wait until the page has completely loaded before opening the Share sheet.

The icon opens Safari

This is normal for websites. If Purchase Compass is configured as a Progressive Web App with a valid web app manifest and service worker, it should launch in its own standalone window without Safari's navigation bars.

I accidentally deleted the icon

Just repeat the steps above. Your Purchase Compass account and data are not affected.

• Capture an image of the whole receipt in one shot, not segment by segment.
• Flatten the paper and avoid shadows across the totals line.
• For PDFs from supermarket apps, the original download is more accurate than a screenshot.
• If a category looks wrong, the AI's guess can be improved by re-uploading a clearer image, or you can ignore it — totals are unaffected.

Usually because it was both forwarded by email and uploaded manually, or captured twice. Click Remove duplicates in the header — Purchase Compass matches on store + date + total and keeps the row with the most line items.

On Cloud: encrypted at rest in Purchase Compass's database, scoped to your user id by row-level security. Only you can read it. On Google Sheets: in a spreadsheet in your Google Drive — Purchase Compass never holds a copy.