CartWise/CLAUDE.md

CLAUDE.md - CartWise MVP Development Guide

Read First

This repository builds CartWise, a mobile-first grocery companion implemented as a conventional ASP.NET Core MVC application.

Read these files before making substantial changes:

• AGENTS.md for the canonical product and architecture rules
• docs/scrum-backlog.md for the living backlog and current execution plan
• docs/decision-log.md for accepted scope and delivery decisions
• docs/release-mvp-checklist.md for MVP completion criteria

Use docs/scrum-backlog.md as the shared execution tracker. Do not keep meaningful implementation progress only in chat.

---

Current Delivery Context

The current target is a local MVP by September 10, 2026.

This repository is optimized for a solo founder + AI delivery model:

• the founder acts as product owner, reviewer, and primary QA
• AI helps with scaffolding, implementation, refactoring, and documentation
• scope control matters more than feature breadth

When in doubt, choose the smallest working vertical slice that moves MVP forward.

---

MVP Scope

The current MVP must allow a user to:

1. Register and sign in
2. Create a household
3. Maintain one active shared grocery list
4. Add free-text grocery items without requiring product resolution
5. Toggle, skip, edit, or delete list items as needed by the MVP backlog
6. Record purchases manually
7. View basic personal price history
8. See deterministic running-low suggestions
9. Use the main flows on a phone-sized layout

For MVP, CartWise must still be useful with:

• zero retailer API access
• zero barcode scanning
• zero external product providers
• local-first development and verification

---

Explicitly Post-MVP

Unless the user explicitly changes scope, these are not MVP blockers:

• barcode scanning
• camera scan flows
• Open Food Facts integration
• USDA integration
• dedicated shopping mode page
• hosted deployment
• production PostgreSQL setup
• advanced product preference workflows beyond what the backlog marks as MVP

If a request touches one of these areas, check docs/scrum-backlog.md first and keep the work aligned with its Release, Priority, and Decision Gate notes.

---

Core Stack

Use:

• ASP.NET Core MVC
• C#
• Razor Views
• HTML5
• CSS3
• jQuery
• vanilla JavaScript
• EF Core
• SQLite for MVP and local development
• ASP.NET Core Identity

Plan for later, but do not optimize for now:

• PostgreSQL for hosted production
• external product providers
• scan workflows

Do not introduce without explicit approval:

• React
• Vue
• Angular
• Blazor
• .NET MAUI
• Flutter
• SPA architecture
• microservices
• MediatR
• generic repository abstractions added only for pattern compliance

---

Architecture Boundaries

CartWise.Web

Owns:

• MVC controllers
• Razor Views
• ViewModels
• HTML/CSS/JS
• ASP.NET-specific concerns

CartWise.Application

Owns:

• use-case orchestration
• services
• interfaces
• validation
• DTOs and results

CartWise.Domain

Owns:

• entities
• enums
• value objects
• business rules and invariants

Do not place EF Core, Razor, HTTP, or provider SDK concerns here.

CartWise.Infrastructure

Owns:

• DbContext
• EF configurations and migrations
• SQLite persistence for MVP
• future PostgreSQL migration path
• external integrations when they are actually implemented

Keep dependency direction clean.

---

Backlog Workflow

Before implementation work:

1. Read the relevant epic and story in docs/scrum-backlog.md.
2. Confirm the story is still in MVP scope if the work is intended for the current release.
3. Check docs/decision-log.md for any accepted constraints.
4. Refine or add concrete tasks in the backlog if new implementation work is discovered.

While implementing:

1. Keep backlog task wording specific and implementation-oriented.
2. Update docs/scrum-backlog.md if work is split, deferred, blocked, or completed.
3. Keep repository state and backlog state aligned.
4. Do not silently expand scope beyond the current story.

After implementing:

1. Mark completed tasks in docs/scrum-backlog.md.
2. Add a brief note if a story is effectively complete.
3. Update docs/decision-log.md if a meaningful product or architecture decision was made.
4. Check docs/release-mvp-checklist.md when the work affects launch readiness.

---

Solo-Founder Working Rules

Optimize for finishing, not for theoretical completeness.

Prefer:

• one active story at a time
• thin vertical slices
• explicit acceptance criteria
• simple database and hosting assumptions during MVP
• reusable services only when they solve a real current need

Avoid:

• speculative abstractions
• premature generalization
• building post-MVP capabilities during MVP work
• “while I’m here” feature expansion
• large refactors unless they unblock current backlog work

If a story feels larger than a day or two, split it before implementing.

---

Domain Priorities For MVP

Household

Keep household isolation correct from the start.

• do not trust posted household ids alone
• validate membership server-side
• prevent IDOR on household-scoped resources

Shopping List

The list is the center of MVP value.

• free-text entry must work well
• product resolution must not be required
• mobile usability matters
• one active list is enough for MVP

Purchases and Prices

Manual capture is acceptable for MVP.

• a purchase flow does not need scan support
• price history must be trustworthy
• PriceObservation remains append-only
• show latest, average, and lowest where data supports it

Running Low

Keep suggestions deterministic and explainable.

• use purchase dates
• use interval calculations
• prefer median when enough history exists
• never auto-add predicted items to the list

---

Data and Persistence Rules

For MVP:

• use SQLite
• create EF Core migrations for schema changes
• use explicit entity configurations
• avoid lazy loading
• use AsNoTracking() for read-heavy paths where appropriate
• protect historical data from accidental cascade deletion
• treat PriceObservation as append-only history

If a future PostgreSQL move affects a current design choice, note it in docs/decision-log.md rather than overengineering now.

---

Security Rules

Always enforce:

• ASP.NET Core Identity for authentication
• anti-forgery protection on state-changing MVC requests
• server-side validation
• household-scoped authorization checks
• safe handling of secrets and local configuration

Never:

• trust client-supplied household ownership
• expose secrets to client-side JavaScript
• skip authorization because the app is currently local-only

---

UI Rules

Keep UI:

• server-rendered first
• mobile-first
• touch-friendly on phone-sized layouts
• progressively enhanced with jQuery or small vanilla JS modules

Do not turn the app into a client-side SPA.

Use JavaScript to enhance workflows, not replace Razor as the primary application shell.

---

Validation and Testing

Before claiming work complete, prefer to verify:

• valid input succeeds
• invalid input fails clearly
• household isolation holds
• state-changing actions require anti-forgery coverage
• impacted tests pass

When implementing business rules or bug fixes, add or update tests.

When data model changes, verify migrations are included.

Do not claim a feature works if the relevant build or tests were not run when the environment makes them available.

---

Recommended MVP Build Order

Follow this order unless the user explicitly reprioritizes:

1. Foundation

• solution and projects
• SQLite wiring
• Identity
• baseline test harness

2. Household

• household entities
• membership and authorization
• create household flow

3. Grocery List

• grocery concepts and categories as needed for MVP
• list and list items
• add, edit, toggle, skip, delete
• mobile list UI

4. Purchases and Price History

• purchase and purchase item flows
• price observations
• basic price history views

5. Running Low

• deterministic replenishment service
• home and list suggestions

6. MVP Hardening

• authorization review
• anti-forgery review
• mobile usability pass
• local release checklist verification

Post-MVP resumes after that.

---

First End-to-End Slice

When starting implementation, prove the foundation with a small working path:

Register/Login
  -> Create Household
  -> Open /list
  -> Add "Milk"
  -> Persist item
  -> Toggle Purchased
  -> Reload
  -> Verify correct household-scoped state

This gives an early proof of:

• authentication
• household authorization
• EF persistence
• MVC routing
• Razor rendering
• state changes on the core list workflow

---

Definition Of A Good Change

A good CartWise change:

• advances the current MVP backlog
• improves the household grocery-memory workflow
• keeps MVC server-rendered first
• works on a phone-sized layout
• preserves household isolation
• keeps price history trustworthy
• avoids unnecessary architecture expansion
• updates backlog or decision docs when needed

North star:

CartWise remembers what the household needs, what it buys, and what it normally pays.