# 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: ```text 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.**