# CartWise Decision Log

## Purpose

This file records product, scope, architecture, and delivery decisions for CartWise so a solo founder + AI workflow does not repeatedly revisit the same unresolved questions.

## How To Use

- Add a new entry when a decision changes backlog scope, technical direction, or release timing
- Keep entries short and explicit
- Reference related backlog stories in `docs/scrum-backlog.md` when helpful
- Update an existing entry only to add a superseding decision or revisit trigger

## Entry Template

```md
### DEC-XXX - Short title
- Date: YYYY-MM-DD
- Status: Proposed | Accepted | Superseded
- Decision: One-sentence summary
- Reason: Why this was chosen
- Impact: What changes in the backlog, implementation, or release plan
- Revisit Trigger: What would cause this to be reconsidered
```

## Decisions

### DEC-001 - MVP target and launch window
- Date: 2026-08-10
- Status: Accepted
- Decision: Target a local MVP completion by September 10, 2026.
- Reason: A one-month deadline forces scope discipline and creates a practical solo-founder release target.
- Impact: Only `MVP` and `P0` backlog work should be treated as launch-critical.
- Revisit Trigger: The MVP cut changes or the launch target date moves.

### DEC-002 - Delivery model
- Date: 2026-08-10
- Status: Accepted
- Decision: Use a solo founder + AI delivery model with the founder acting as product owner, reviewer, and primary QA.
- Reason: AI can accelerate implementation, but final product judgment and local verification remain human responsibilities.
- Impact: Backlog items must stay small, explicit, and easy to verify locally.
- Revisit Trigger: Additional human contributors join active development.

### DEC-003 - Barcode scanning is out of MVP
- Date: 2026-08-10
- Status: Accepted
- Decision: Barcode scanning, camera workflows, and scan-page work are deferred until after MVP.
- Reason: These features add complexity and are not required for the first launchable grocery-memory workflow.
- Impact: `CW-EPIC-04` barcode and scan stories remain `Post-MVP` or `Deferred`.
- Revisit Trigger: Core MVP is stable and there is time to add scan functionality.

### DEC-004 - External product providers are out of MVP
- Date: 2026-08-10
- Status: Accepted
- Decision: Open Food Facts, USDA, and other external provider integrations are deferred until after MVP.
- Reason: Manual and local-only workflows are sufficient for MVP and reduce dependency risk.
- Impact: Provider-related backlog stories remain `Deferred` or `Post-MVP`.
- Revisit Trigger: MVP is complete and product resolution becomes the next highest-value feature.

### DEC-005 - SQLite for MVP development
- Date: 2026-08-10
- Status: Accepted
- Decision: Use SQLite for MVP and local development instead of PostgreSQL.
- Reason: SQLite lowers setup friction and is better suited for a fast local-first development loop.
- Impact: Foundation stories should wire SQLite first while keeping a future PostgreSQL path possible.
- Revisit Trigger: Hosted or multi-user production deployment becomes the priority.
- Implementation Note (2026-08-10, `CW-STORY-01.2`): `CartWiseDbContext` lives in `CartWise.Infrastructure/Data` and is wired to SQLite only through `InfrastructureServiceCollectionExtensions.AddInfrastructure`, via `options.UseSqlite(...)` and the `ConnectionStrings:DefaultConnection` setting in `appsettings.json`. Moving to PostgreSQL later is expected to mean swapping `UseSqlite` for `UseNpgsql` and the connection string in that single extension method — no changes anticipated in `CartWise.Domain` or `CartWise.Application`.

### DEC-006 - Local-first release strategy
- Date: 2026-08-10
- Status: Accepted
- Decision: Build and validate the app locally before any public deployment work.
- Reason: Local-first release reduces operational complexity during MVP delivery.
- Impact: Public hosting, infrastructure, and deployment work are not launch blockers for the current MVP.
- Revisit Trigger: Local MVP is stable and ready for broader testing.

### DEC-007 - Shopping mode may be deferred
- Date: 2026-08-10
- Status: Accepted
- Decision: A dedicated shopping mode page is post-MVP unless the standard list page proves insufficient.
- Reason: A mobile-friendly list can satisfy core purchase flow needs with less implementation overhead.
- Impact: `CW-EPIC-06` is treated as post-MVP for now.
- Revisit Trigger: MVP list flow cannot support practical in-store use.

### DEC-008 - Manual purchase flow is acceptable for MVP
- Date: 2026-08-10
- Status: Accepted
- Decision: Manual purchase entry is acceptable for MVP even if list-to-purchase linkage is simplified at first.
- Reason: Price history and replenishment value can be delivered without sophisticated scan or shopping workflows.
- Impact: Purchase and price stories stay in MVP while more advanced purchase linkage can evolve later.
- Revisit Trigger: Manual purchase entry creates too much friction during testing.

### DEC-009 - One household per user for MVP
- Date: 2026-08-10
- Status: Accepted
- Decision: A user belongs to exactly one household. `CW-STORY-02.2`'s `HouseholdService.CreateHouseholdAsync` rejects creating a second household for a user who already has a membership row anywhere; `GetCurrentHouseholdAsync` resolves "current household" unambiguously from that single membership.
- Reason: AGENTS.md and the backlog use "current household" language without defining cardinality. One-per-user is the smallest working vertical slice — no household-switcher UI, no "which household" ambiguity anywhere downstream (list, purchases, running-low).
- Impact: No schema-level uniqueness constraint was added (`HouseholdMember`'s composite PK is `(HouseholdId, UserId)`, which would technically allow multiple rows for the same user), so this is enforced only at the `HouseholdService` application layer for now. Multi-household support remains possible later without a migration.
- Revisit Trigger: A real need emerges for one person to participate in more than one household (e.g. managing groceries for two homes).

### DEC-010 - Build order reverted to strict epic-numeric sequencing
- Date: 2026-08-10
- Status: Accepted
- Decision: Build remaining epics in strict numeric order (`CW-EPIC-04` → `CW-EPIC-05` → `CW-EPIC-06` → `CW-EPIC-07` → `CW-EPIC-08`) instead of the MVP-first order the backlog recommended (`05` → `07` → MVP-tagged `08` stories, with `04`/`06` deferred to after MVP).
- Reason: Explicit founder direction, given after being asked directly whether to keep the MVP-first order or override it.
- Impact: `CW-EPIC-04` (Product Catalog and Barcode Resolution) and `CW-EPIC-06` (Shopping Mode) are no longer sequenced after MVP — they will be built next, ahead of `CW-EPIC-05`/`07`. `DEC-003` (barcode out of MVP), `DEC-004` (external providers out of MVP), and `DEC-007` (shopping mode may be deferred) remain valid as *scope* decisions — none of that work becomes MVP-required by this change — but their *sequencing* guidance is superseded. Individual stories within `04`/`06` that carry their own explicit Decision Gate (e.g. "confirm whether a product catalog is still needed," "Open Food Facts integration," "camera scan flow") will still be raised with the founder individually as implementation reaches them; this decision only resolves ordering, not each gate's content. Building substantial Post-MVP scope now will likely push completion past the September 10, 2026 MVP target.
- Revisit Trigger: If schedule pressure toward September 10, 2026 becomes acute, reconsider reverting to MVP-first sequencing for whatever remains.