# BLUEPRINT: Stack Spent
# Version: 3.0.0
# URL: https://stackspent.app
# Updated: 2026-07-25

## IDENTITY
name: Stack Spent
description: |
  Done in the moment. Never think about it again.

  Stack Spent is an AI expense tracker built around a single idea: the only moment you will ever actually deal with a receipt is the moment it exists. Snap at the fuel pump, the hardware store, the job site — the AI reads the merchant, amount, date, and taxes automatically. When tax season arrives, everything is already there.

  This is not a simpler QuickBooks. It does not ask you to change your behaviour or dedicate time to bookkeeping. It captures business activity as it naturally happens and gets out of your way.

  Stack Spent is completely standalone — it works on its own with no other apps required. It is also part of the Stack suite (Stack Billing, Stack Slip, Stack Tax, and more). Each suite app is built the same way: one thing, takes seconds, standalone. If a user has multiple Stack apps, they share the same login and data flows automatically between them. No exports. No manual syncing.
category: finance
contact: https://stackspent.app/faq

## SUMMARY
tagline: Snap a receipt and the expense is logged — done in the moment, never thought about again.
audience: Freelancers, tradespeople, and small business owners who need expenses captured without dedicating time to bookkeeping.
capabilities:
  - scan-receipt: Photograph or upload a receipt for AI extraction and automatic expense creation
  - add-manual-expense: Add an expense manually without scanning a receipt
  - view-expenses: View and search all recorded expenses in the Shoebox
  - export-expenses: Export expenses as a CSV file
  - view-insights: View spending totals, tax breakdown, and category summaries

## AUTH
provider: firebase
methods: email-password, oauth-google

## ACCESS
last-resort: ui

## TIMING
# Format: <operation-label>: <observed-range> — use max: <N>s
ai-receipt-scan: 10-30s — use max: 30s
batch-upload-processing: 1-3s per file — use max: 3s (initial submission; longer batches take proportionally more)
dialog-transition: 1-2s — use max: 5s

## SELECTOR NORMALIZATION
description: |
  Some `data-agent-id` values are slugged in the app. Expand placeholders before CLICK/WAIT:
  - **Category** (`button-category-option-*`): lowercase, replace whitespace with `-`, strip characters except a-z, 0-9, hyphen. Empty → `category`.
  - **Project name** (`button-project-option-*`, `button-project-edit-*`, `button-project-delete-*`): same rules as category (lowercase, hyphenate, strip non-alphanumeric).
  - **Currency** (`button-currency-option-*`): ISO 4217 code lowercase (e.g. usd, cad).

## PRODUCT-NOTES
localization: |
  The app shell runs a client-side translation layer (`GlobalTranslation`) so UI copy can follow the user or device language, in addition to the explicit Language control under Settings.

## ROUTES
purpose: |
  Canonical map of client-side routes for discovery, support, and automation. "Admin email" means the signed-in user passes `isAdminEmail` in the client; others are redirected to `/`.

- path: /
  auth: optional
  guest: Marketing landing—positioning, feature grid, StackApps ecosystem links (`button-invoicing-wizard`, `button-packingslip-wizard`, `button-stackapps`), CTAs `button-get-started` / `button-cta-bottom` → `/login`.
  signed_in: Home—`input-camera` / `button-camera`, Manual entry dialog (`button-manual-entry`), Batch upload (`button-batch-upload`), queue badge `text-queue-status`.

- path: /login
  auth: public
  summary: Email/password and Google sign-in; success returns to `/`.

- path: /shoebox
  auth: required
  summary: Expense list, Needs Review, filters, exports, project manager, custom categories, search, delete/review flows. When offline captures are pending or failed, `text-sync-status` with `button-clear-all`, `button-clear-failed`, `button-retry-failed`. Narrow screens use `button-export-mobile` for CSV menus. Manual entry opens with `button-add-expense`; submit the form with `button-submit-manual-entry`. While the dialog is open, header nav is blocked—close with `button-close-dialog` (or Escape) before `link-insights` / `link-shoebox` / etc.

- path: /insights
  auth: required
  summary: Totals, tax rollups, category and project breakdowns (`text-insights-title`).

- path: /settings
  auth: required
  summary: Profile email, Google unlink, theme/language/date format, insurance section, password & email forms, admin card (if eligible), destructive delete account.

- path: /faq
  auth: public
  summary: FAQ accordion (`faq-item-*`, `button-faq-question-*`) and Contact Support dialog (`button-contact-support`).

- path: /how-ai-works
  auth: public
  summary: Explains dual-AI receipt verification (`text-how-ai-title`). Implemented as a dedicated React page (not the Firestore static HTML renderer).

- path: /expense-tracker-for-adhd
  auth: public
  summary: ADHD-focused landing (`text-adhd-landing-title`), FAQ accordion (`adhd-faq-item-*`, `button-adhd-faq-question-*`), CTA `button-adhd-cta-login`.

- path: /privacy | /terms | /cookies
  auth: public
  summary: Legal / policy HTML loaded from Firestore `staticPages` (`static-page-content`). Back control `button-back`.

- path: /admin/feedback
  auth: required + admin email
  summary: Review Firestore feedback (`text-admin-feedback-title`, filters `select-status-filter`, `select-app-filter`, cards `card-feedback-*`, actions `button-admin-feedback-status-*`, `button-admin-feedback-delete-*`).

- path: /admin/taxes
  auth: required + admin email
  summary: Custom tax catalog editor (`text-admin-tax-catalog-title`, `button-add-tax`, rows `tax-row-*`, `button-admin-tax-edit-*`, `button-admin-tax-delete-*`, dialog fields `input-tax-*`, `button-save-tax`).

global_chrome: |
  Header: `link-home`, `button-feedback`, `button-settings` / `button-logout` (signed in) or `button-login` (guest). Desktop nav: `link-nav-home`, `link-shoebox`, `link-insights`. Mobile bottom nav: `nav-home`, `nav-shoebox`, `nav-insights`. Footer: `link-faq`, `link-ai`, `link-privacy`, `link-terms`, `link-cookies`.

## CAPABILITIES
login: https://stackspent.app/blueprints/login.txt | ui
signup: https://stackspent.app/blueprints/signup.txt | ui
google-login: https://stackspent.app/blueprints/google-login.txt | ui
forgot-password: https://stackspent.app/blueprints/forgot-password.txt | ui
logout: https://stackspent.app/blueprints/logout.txt | ui
scan-receipt: https://stackspent.app/blueprints/scan-receipt.txt | ui
review-scanned-receipt: https://stackspent.app/blueprints/review-scanned-receipt.txt | ui
batch-upload: https://stackspent.app/blueprints/batch-upload.txt | ui
add-manual-expense: https://stackspent.app/blueprints/add-manual-expense.txt | ui
add-manual-expense-from-home: https://stackspent.app/blueprints/add-manual-expense-from-home.txt | ui
edit-expense: https://stackspent.app/blueprints/edit-expense.txt | ui
delete-expense: https://stackspent.app/blueprints/delete-expense.txt | ui
view-expenses: https://stackspent.app/blueprints/view-expenses.txt | ui
search-expenses: https://stackspent.app/blueprints/search-expenses.txt | ui
filter-expenses: https://stackspent.app/blueprints/filter-expenses.txt | ui
create-project: https://stackspent.app/blueprints/create-project.txt | ui
add-custom-category: https://stackspent.app/blueprints/add-custom-category.txt | ui
export-expenses: https://stackspent.app/blueprints/export-expenses.txt | ui
export-expenses-mobile-toolbar: https://stackspent.app/blueprints/export-expenses-mobile-toolbar.txt | ui
export-vendor-summary: https://stackspent.app/blueprints/export-vendor-summary.txt | ui
view-insights: https://stackspent.app/blueprints/view-insights.txt | ui
manage-offline-upload-queue: https://stackspent.app/blueprints/manage-offline-upload-queue.txt | ui
change-password: https://stackspent.app/blueprints/change-password.txt | ui
change-email: https://stackspent.app/blueprints/change-email.txt | ui
add-password-google-only-user: https://stackspent.app/blueprints/add-password-google-only-user.txt | ui
unlink-google-provider: https://stackspent.app/blueprints/unlink-google-provider.txt | ui
update-display-preferences: https://stackspent.app/blueprints/update-display-preferences.txt | ui
configure-insurance-settings: https://stackspent.app/blueprints/configure-insurance-settings.txt | ui
delete-user-account: https://stackspent.app/blueprints/delete-user-account.txt | ui
view-marketing-landing: https://stackspent.app/blueprints/view-marketing-landing.txt | ui
open-login-from-header: https://stackspent.app/blueprints/open-login-from-header.txt | ui
navigate-site-footer: https://stackspent.app/blueprints/navigate-site-footer.txt | ui
view-faq: https://stackspent.app/blueprints/view-faq.txt | ui
contact-support-from-faq: https://stackspent.app/blueprints/contact-support-from-faq.txt | ui
view-how-ai-works: https://stackspent.app/blueprints/view-how-ai-works.txt | ui
view-adhd-landing: https://stackspent.app/blueprints/view-adhd-landing.txt | ui
view-privacy-policy: https://stackspent.app/blueprints/view-privacy-policy.txt | ui
view-terms-of-service: https://stackspent.app/blueprints/view-terms-of-service.txt | ui
view-cookie-policy: https://stackspent.app/blueprints/view-cookie-policy.txt | ui
send-in-app-feedback: https://stackspent.app/blueprints/send-in-app-feedback.txt | ui
open-admin-feedback-console: https://stackspent.app/blueprints/open-admin-feedback-console.txt | human-only
open-admin-tax-catalog: https://stackspent.app/blueprints/open-admin-tax-catalog.txt | human-only
populate-static-pages-admin: https://stackspent.app/blueprints/populate-static-pages-admin.txt | human-only