# Multi-Household Implementation - Quick Reference

## Implementation Status

### ✅ Sprint 1: Database Foundation (COMPLETE)
- [x] Created migration script: `multi_household_architecture.sql`
- [x] Created migration guide: `MIGRATION_GUIDE.md`
- [x] Created migration runner scripts: `run-migration.sh` / `run-migration.bat`
- [x] **Tested migration on 'grocery' database (copy of Costco)**
- [x] Migration successful - all data migrated correctly
- [x] Verification passed - 0 data integrity issues

**Migration Results:**
- ✅ 1 Household created: "Main Household" (invite code: MAIN755114)
- ✅ 7 Users migrated (2 system_admins, 5 standard users)
- ✅ 122 Items extracted to master catalog
- ✅ 122 Household lists created
- ✅ 27 Classifications migrated
- ✅ 273 History records preserved
- ✅ All users assigned to household (admin/user roles)
- ✅ 0 orphaned records or data loss

**Database:** `grocery` (using Costco as template for safety)

### ⏳ Sprint 2: Backend API (NEXT - READY TO START)
- [ ] Create household.model.js
- [ ] Create store.model.js  
- [ ] Update list.model.js for household+store scope
- [ ] Create householdAccess middleware
- [ ] Create storeAccess middleware
- [ ] Create households.controller.js
- [ ] Create stores.controller.js
- [ ] Update lists.controller.js
- [ ] Update users.controller.js
- [ ] Create/update routes for new structure

### ⏳ Sprint 3: Frontend Core (PENDING)
- [ ] Refactor contexts
- [ ] Create household UI
- [ ] Create store UI

## New Database Schema

### Core Tables
1. **households** - Household entities with invite codes
2. **stores** - Store types (Costco, Target, etc.)
3. **household_members** - User membership with per-household roles
4. **household_stores** - Which stores each household uses
5. **items** - Master item catalog (shared)
6. **household_lists** - Lists scoped to household + store
7. **household_item_classifications** - Classifications per household + store
8. **household_list_history** - History tracking

### Key Relationships
- User → household_members → Household (many-to-many)
- Household → household_stores → Store (many-to-many)
- Household + Store → household_lists → Item (unique per combo)
- household_lists → household_list_history (one-to-many)

## Role System

### System-Wide (users.role)
- **system_admin**: App infrastructure control
- **user**: Standard user

### Household-Scoped (household_members.role)
- **admin**: Full household control
- **user**: Standard member

## Migration Steps

1. **Backup**: `pg_dump grocery_list > backup.sql`
2. **Run**: `psql -d grocery_list -f backend/migrations/multi_household_architecture.sql`
3. **Verify**: Check counts, run integrity queries
4. **Test**: Ensure app functionality
5. **Cleanup**: Drop old tables after verification

## API Changes (Planned)

### Old Format
```
GET /api/list
POST /api/list/add
```

### New Format
```
GET /api/households/:hId/stores/:sId/list
POST /api/households/:hId/stores/:sId/list/add
```

## Frontend Changes (Planned)

### New Contexts
```jsx
const { user, isSystemAdmin } = useAuth();
const { activeHousehold, isAdmin } = useHousehold();
const { activeStore, householdStores } = useStore();
```

### New Routes
```
/households                    - List households
/households/:id/stores/:sId    - Grocery list
/households/:id/members        - Manage members
/join/:inviteCode              - Join household
```

## Development Workflow

### Phase 1: Database (Current)
1. Review migration script
2. Test on local dev database
3. Run verification queries
4. Document any issues

### Phase 2: Backend API (Next)
1. Create household.model.js
2. Create store.model.js
3. Update list.model.js for household scope
4. Create middleware for household access
5. Update routes

### Phase 3: Frontend
1. Refactor AuthContext → useAuth()
2. Create HouseholdContext → useHousehold()
3. Create StoreContext → useStore()
4. Build household switcher
5. Build store tabs

## Testing Checklist

### Database Migration
- [ ] All tables created
- [ ] All indexes created
- [ ] Users migrated to household
- [ ] Items deduplicated correctly
- [ ] Lists migrated with correct references
- [ ] Classifications preserved
- [ ] History preserved
- [ ] No NULL foreign keys

### Backend API
- [ ] Household CRUD works
- [ ] Member management works
- [ ] Invite codes work
- [ ] Store management works
- [ ] List operations scoped correctly
- [ ] Permissions enforced
- [ ] History tracked correctly

### Frontend UI
- [ ] Login/logout works
- [ ] Household switcher works
- [ ] Store tabs work
- [ ] Can create household
- [ ] Can join household
- [ ] Can add items
- [ ] Can mark bought
- [ ] Roles respected in UI

## Rollback Strategy

If migration fails:
```sql
ROLLBACK;
```

If issues found after:
```bash
psql -d grocery_list < backup.sql
```

## Support Resources

- **Migration Script**: `backend/migrations/multi_household_architecture.sql`
- **Guide**: `backend/migrations/MIGRATION_GUIDE.md`
- **Architecture**: `docs/multi-household-architecture-plan.md`
- **Status**: This file

## Key Decisions

1. ✅ Keep users.role for system admin
2. ✅ Simplify household roles to admin/user
3. ✅ Preserve user names in history (no anonymization)
4. ✅ Shared item catalog with household-specific lists
5. ✅ Context pattern refactoring (internal context + custom hooks)

## Timeline

- **Week 1-2**: Database migration + testing
- **Week 3-4**: Backend API implementation
- **Week 5-6**: Frontend core implementation
- **Week 7**: Member management
- **Week 8-9**: Testing & polish
- **Week 10**: Production migration

## Contact

For questions or issues during implementation, refer to:
- Architecture plan for design decisions
- Migration guide for database steps
- This file for quick status updates