CartWise/README.md

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.

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

• Solution and project setup
• PostgreSQL configuration
• 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-STORY-01.1 Solution skeleton — 4 src projects + 3 test projects, correct dependency direction, nullable enabled
• CW-STORY-01.2 Application startup — MVC shell runs, SQLite wired via CartWiseDbContext, wwwroot structure organized
• CW-STORY-01.3 ASP.NET Core Identity authentication — register, sign in, sign out
• CW-STORY-01.4 Engineering baseline — shared analyzer settings, .editorconfig, tuned logging, smoke tests

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)

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.