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
• PostgreSQL
• 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 initialized from the AGENTS.md build specification. The current focus is establishing the project foundation, backlog, and delivery workflow before implementing the application phases.

Getting Started

The solution scaffolding is planned but may not yet be present in this repository. Once the projects are created, the expected local development flow will be:

1. Install the .NET SDK
2. Install PostgreSQL
3. Configure connection settings via environment variables or user secrets
4. Run EF Core migrations
5. Start the ASP.NET Core MVC app

Example commands that will be used once the solution exists:

dotnet restore
dotnet build
dotnet test
dotnet run --project src/CartWise.Web

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
• Two-week sprints
• 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.