# 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

Next up: `CW-EPIC-05` Stores, Purchases, and Price Intelligence.

Next up: `CW-EPIC-03` Smart Shopping List.

## 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.
