CartWise/docs/decision-log.md

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

### 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.