# CartWise CartWise is a mobile-first grocery companion web application built with ASP.NET Core MVC. It helps households manage shared grocery lists, remember preferred products, record purchases, and build a trustworthy personal price history. ## Vision CartWise is not a grocery delivery platform and is not tied to a single retailer. Its first job is to become the shopper's grocery memory by helping households: - Maintain shared household grocery lists - Resolve generic grocery concepts like `milk` or `peanut butter` to preferred products - Scan UPC/GTIN barcodes and identify products - Record what was purchased, where, and for how much - Build personal price history over time - Show useful price intelligence such as latest observed, typical, and lowest price - Suggest items that may be running low using deterministic purchase intervals - Support a simple, touch-friendly shopping mode that works well on a phone ## v1 Scope CartWise v1 focuses on the core grocery-memory workflow: 1. Household creation and access control 2. Shared grocery list management 3. Product catalog and barcode resolution 4. Purchase and price history tracking 5. Mobile shopping mode 6. Running-low suggestions based on purchase history The following are explicitly out of scope for v1 unless requirements change: - Grocery delivery - Retailer checkout or payment processing - Coupon clipping - Universal live inventory scraping - Meal planning and recipe generation - AI chatbot features - Social features ## Technology Stack ### Application - ASP.NET Core MVC - C# - Razor Views - HTML5 - CSS3 - jQuery - Vanilla JavaScript - Entity Framework Core - SQLite for MVP and local development - PostgreSQL planned for later hosted production use - ASP.NET Core Identity ### Architecture CartWise is designed as a modular monolith with server-rendered pages first and JavaScript used for progressive enhancement. ```text CartWise.sln src/ CartWise.Web/ CartWise.Application/ CartWise.Domain/ CartWise.Infrastructure/ tests/ CartWise.Domain.Tests/ CartWise.Application.Tests/ CartWise.Web.Tests/ ``` ## Product Principles - Server-rendered first - Mobile-first UX - Retailer independence - Append-only price history where possible - Grocery concepts are distinct from sellable products - UPC/GTIN is an identifier, not the product primary key - Deterministic, explainable price and replenishment logic - AI remains optional rather than required for core workflows ## Core Domain Areas - **Households**: users, memberships, and household-scoped access - **Shopping Lists**: shared lists with unresolved free-text items allowed - **Catalog**: grocery concepts, brands, products, and product identifiers - **Preferences**: household-level product preferences for generic grocery concepts - **Stores and Retailers**: store locations for purchase and price context - **Purchases**: household transaction history - **Price Observations**: append-only record of observed prices - **Replenishment**: deterministic running-low suggestions using purchase intervals ## Planned Features ### Phase 0 - Repository and Baseline (Complete) - Solution and project setup - SQLite configuration for MVP (PostgreSQL remains the planned hosted-production target — see `docs/decision-log.md` DEC-005) - Identity authentication - Build and test baseline ### Phase 1 - Household Foundation - Household creation - Membership management - Household authorization ### Phase 2 - Smart Shopping List - Shared active grocery list - Free-text item entry - Toggle, skip, delete, and concurrency handling ### Phase 3 - Product Catalog and Barcode Resolution - Product and identifier modeling - Product search and details - Local-first barcode lookup - Open Food Facts provider integration - Scan page ### Phase 4 - Stores, Purchases, and Price History - Store and retailer setup - Purchase recording - Price observation history - Price insights and reporting ### Phase 5 - Shopping Mode - Touch-friendly in-store experience - Purchase, skip, unavailable, and substitute actions - Optional price entry during shopping ### Phase 6 - Running-Low Suggestions - Median-interval replenishment calculation - Dashboard and list suggestions - Add suggestion back to list ### Phase 7 - Polish and Release Readiness - Accessibility and responsive review - Security hardening - Logging and diagnostics - Development seed data ## Development Status This repository is being built from the `AGENTS.md` build specification. The current focus is a solo-founder MVP targeted for local completion by **September 10, 2026**. Progress so far (see `docs/scrum-backlog.md` for the authoritative task-level state): `CW-EPIC-01` Platform Foundation is complete: - [x] `CW-STORY-01.1` Solution skeleton — 4 src projects + 3 test projects, correct dependency direction, nullable enabled - [x] `CW-STORY-01.2` Application startup — MVC shell runs, SQLite wired via `CartWiseDbContext`, `wwwroot` structure organized - [x] `CW-STORY-01.3` ASP.NET Core Identity authentication — register, sign in, sign out - [x] `CW-STORY-01.4` Engineering baseline — shared analyzer settings, `.editorconfig`, tuned logging, smoke tests `CW-EPIC-02` Household and Access Control is complete: - [x] `CW-STORY-02.1` Household/HouseholdMember entities, EF configuration, migration, domain tests - [x] `CW-STORY-02.2` `HouseholdService` — create household, resolve current household, membership checks - [x] `CW-STORY-02.3` Household UI — create and overview pages - [x] `CW-STORY-02.4` Reusable `"HouseholdMember"` authorization policy, cross-household isolation verified `CW-EPIC-03` Smart Shopping List is complete: - [x] `CW-STORY-03.1` ShoppingList/ShoppingListItem/GroceryConcept/ProductCategory entities, EF configuration, migration - [x] `CW-STORY-03.2` `ShoppingListService` — get/create the household's one active list - [x] `CW-STORY-03.3` Free-text add-item flow, auto-provisioned default list, verified live end-to-end - [x] `CW-STORY-03.4` Toggle purchased/skip/delete with optimistic concurrency handling and jQuery progressive enhancement - [x] `CW-STORY-03.5` Mobile-first/touch-friendly polish pass (not visually verified in a browser — no browser-automation tool available in this environment; recommend a quick manual check) `CW-EPIC-04` Product Catalog and Barcode Resolution is complete — built ahead of the MVP-tagged epics per `DEC-010` (explicit founder direction to work epics in strict numeric order rather than MVP-first): - [x] `CW-STORY-04.1` Brand/Product/ProductIdentifier/HouseholdProductPreference entities, EF configuration, migration - [x] `CW-STORY-04.2` Local product search and details pages - [x] `CW-STORY-04.3` Local-first barcode lookup flow with provider fallback (`IProductDataProvider`) - [x] `CW-STORY-04.4` Real `OpenFoodFactsProductDataProvider` (typed `HttpClient`, no API key required) - [x] `CW-STORY-04.5` Camera-based scan page (native `BarcodeDetector` API, manual-entry fallback) with add-to-list — verified live against the real Open Food Facts API `CW-EPIC-05` Stores, Purchases, and Price Intelligence is complete: - [x] `CW-STORY-05.1` Retailer/StoreLocation entities, EF configuration, migration (store tracking optional per `DEC-011`) - [x] `CW-STORY-05.2` Purchase/PurchaseItem entities, EF configuration, migration - [x] `CW-STORY-05.3` Append-only PriceObservation entity, EF configuration, migration (cascade-delete protected) - [x] `CW-STORY-05.4` Purchase recording flow — start, add items, complete - [x] `CW-STORY-05.5` `PriceService` derives price observations from completed purchases (latest/average/median/lowest/unit price) - [x] `CW-STORY-05.6` `PriceController` + price views (index, per-product history, manual price logging), real price insight on product details Next up: `CW-EPIC-06` Shopping Mode. ## Project Planning - Delivery guidance and architectural rules live in `AGENTS.md` - Claude-specific working guidance lives in `CLAUDE.md` - The living Scrum backlog lives in `docs/scrum-backlog.md` - Key product and scope decisions live in `docs/decision-log.md` - MVP completion criteria live in `docs/release-mvp-checklist.md` - Update `docs/scrum-backlog.md` as stories and tasks move into active work and when work is completed ## Getting Started 1. Install the .NET SDK (developed against .NET 10) 2. Restore, build, and test the solution 3. Run the web app — it uses SQLite by default (`ConnectionStrings:DefaultConnection` in `src/CartWise.Web/appsettings.json`, pointing at `App_Data/cartwise.db`) ```bash dotnet restore dotnet build dotnet test dotnet run --project src/CartWise.Web ``` `dotnet restore`, `dotnet build`, and `dotnet test` (in that order, against `CartWise.sln`) are the commands a CI pipeline should run — there is no separate CI-only script. `dotnet build` fails the same way locally and in CI since analyzer rules are enforced via `Directory.Build.props` (`EnableNETAnalyzers`, `AnalysisLevel=latest-recommended`) rather than a separate lint step. Registration and sign-in are available at `/Account/Register` and `/Account/Login`. The Identity schema migration applies automatically on startup in the Development environment. Domain entities (household, list, etc.) and their first migration land in `CW-EPIC-02` (Household and Access Control). ## Backlog and Delivery The team plans to manage this project using Scrum with: - Epics aligned to the implementation phases - User stories for each feature slice - Tasks under each story for development, testing, and UI work - A solo weekly planning cadence with one active story at a time - A definition of done that includes tests, authorization, validation, and logging ## Security and Data Principles - Every household-scoped action must enforce membership authorization - State-changing requests must use anti-forgery protection - User-entered data must be server-side validated - External provider secrets must stay out of client-side code - Price history should preserve observation history instead of overwriting past records ## Contributing When contributing: - Follow the architecture and implementation order in `AGENTS.md` - Keep controllers thin - Keep domain logic out of Razor views and controllers - Add tests for business rules and bug fixes - Prefer clear, conventional C# over unnecessary abstraction ## License No license has been defined yet for this repository.