# Family Hub - Project Roadmap & Development Tracker

**Project Start Date:** December 18, 2025  
**Last Updated:** December 18, 2025

---

## 🎯 Project Vision

A comprehensive home management system that centralizes:
- **Calendar Management** (Google Calendar integration)
- **Chore Tracking** (Daily/Weekly/Fortnightly/Ad-hoc tasks)
- **Menu Planning** (Mealie integration)
- **Shopping Lists** (Auto-generated from meal plans + manual)
- **Home Assistant Integration** (Push notifications & dashboards)

**Family Members:** Lou, Jess, William, Xander, Bella  
**Pets:** Chips (Cat), Harper (Dog)

---

## 📋 Development Phases

### ✅ Phase 1: Foundation & Core Setup
**Status:** 🚧 IN PROGRESS  
**Started:** December 18, 2025

- [x] Create Git repository
- [x] Initial README documentation
- [x] Project roadmap document (this file)
- [x] **Backend scaffolding**
  - [x] FastAPI project structure
  - [x] SQLite database setup
  - [x] User authentication system
  - [x] Basic API endpoints
- [x] **Frontend scaffolding**
  - [x] React project with Vite
  - [x] Tailwind CSS configuration
  - [x] Basic routing (React Router)
  - [x] Authentication UI
- [x] **Database Schema**
  - [x] Users table
  - [x] Chores table
  - [x] Chore assignments table
  - [x] Initial seed data (init_db.py)
- [x] Docker configuration
- [x] Environment configuration files

**Definition of Done:** ✅ Can create users, login, and see empty dashboard - **COMPLETE!**

---

### 🔜 Phase 2: Chores System (Priority Module)
**Status:** ⏳ PENDING  
**Target Start:** Next session

#### 2.1 Database & Models ✅
- [x] Chore categories (Bedroom, Bathroom, Kitchen, etc.)
- [x] Chore frequency types (Daily, Weekly, Fortnightly, Ad-hoc)
- [x] Assignment logic (Individual, Shared, Rotating)
- [x] Location-based chores

#### 2.2 Backend API
- [ ] Complete CRUD endpoints for chores
- [ ] Assignment endpoints
- [ ] Recurring schedule engine
- [ ] Completion tracking
- [ ] History & analytics

#### 2.3 Frontend UI
- [ ] Chore creation form
- [ ] Daily task dashboard (per user)
- [ ] Weekly calendar view
- [ ] Quick complete/skip buttons
- [ ] Overdue indicators
- [ ] Chore assignment interface

**Key Chore Locations:**
- Bedrooms: Lou, Jess (Ensuite), William, Xander, Bella (5 total)
- Bathrooms: Shared bathroom + Ensuite
- Kitchen: Dishwasher, hand washing, bins
- Laundry: Washing machine, dryer
- Living Areas: Dining room
- Pet Care: Feeding (Chips, Harper), watering, kitty litter
- Waste: Bins (Wednesday AM), Recycling (fortnightly), Greens (fortnightly)

**Definition of Done:** All family members can be assigned chores, complete them, and view their schedules

---

### 🔜 Phase 3: Calendar Integration
**Status:** ⏳ PENDING  
**Target Start:** TBD

- [ ] Google OAuth2 setup
- [ ] Read calendar events
- [ ] Display events in dashboard
- [ ] Create/edit events from interface
- [ ] Optional: Sync chores as calendar events
- [ ] Multi-calendar view (filter by user)

**Definition of Done:** Can view and modify Google Calendar from Family Hub

---

### 🔜 Phase 4: Menu Planning & Shopping
**Status:** ⏳ PENDING  
**Target Start:** TBD

#### 4.1 Mealie Integration
- [ ] API connection setup
- [ ] Fetch recipes
- [ ] Weekly meal planner UI
- [ ] Sync recipes to shopping lists

#### 4.2 Shopping Lists
- [ ] Manual item add/edit
- [ ] Import from Mealie
- [ ] Category organization
- [ ] Check-off functionality
- [ ] Mobile-optimized view

**Definition of Done:** Can plan weekly meals and generate shopping lists

---

### 🔜 Phase 5: Dashboard & Home View
**Status:** ⏳ PENDING  
**Target Start:** TBD

- [ ] Unified dashboard layout
- [ ] Widget system (draggable priority)
- [ ] Today's chores widget
- [ ] Upcoming events widget
- [ ] This week's meals widget
- [ ] Quick stats display
- [ ] User switching

**Definition of Done:** Beautiful, functional home screen showing all modules

---

### 🔜 Phase 6: Home Assistant Integration
**Status:** ⏳ PENDING  
**Target Start:** TBD

- [ ] REST API endpoints for HA
- [ ] Webhook notifications
- [ ] Push notification setup:
  - [ ] Overdue chores
  - [ ] Bin day reminder (Tuesday night)
  - [ ] Pet care reminders
  - [ ] Meal prep reminders
- [ ] Custom HA dashboard card
- [ ] Sensor entities for HA

**Definition of Done:** Can view Family Hub data in Home Assistant and receive notifications

---

### 🔜 Phase 7: Polish & Deployment
**Status:** ⏳ PENDING  
**Target Start:** TBD

- [ ] Mobile responsive design
- [ ] Progressive Web App (PWA) setup
- [ ] Offline capabilities
- [ ] Docker containerization improvements
- [ ] Deployment documentation
- [ ] Backup/restore functionality
- [ ] User onboarding flow

**Definition of Done:** Production-ready, deployable system

---

## 🛠️ Technology Stack

### Backend
- **Framework:** FastAPI (Python 3.11+)
- **Database:** SQLite (development) → PostgreSQL (production ready)
- **Authentication:** JWT tokens with httponly cookies
- **Integrations:**
  - Google Calendar API (OAuth2)
  - Mealie API (self-hosted instance)
  - Home Assistant REST API

### Frontend
- **Framework:** React 18 with Vite
- **Styling:** Tailwind CSS
- **State Management:** React Context API / Zustand
- **Routing:** React Router v6
- **HTTP Client:** Axios
- **PWA:** Vite PWA Plugin

### Development Tools
- **Version Control:** Git (Gitea)
- **Containerization:** Docker & Docker Compose
- **Testing:** pytest (backend), Vitest (frontend)

---

## 📊 Current Sprint

**Sprint Goal:** ✅ Complete Phase 1 - Foundation & Core Setup

**Completed Tasks:**
1. ✅ Repository setup
2. ✅ Backend scaffolding
3. ✅ Frontend scaffolding
4. ✅ Database schema
5. ✅ Basic authentication
6. ✅ Docker configuration
7. ✅ Project documentation

**Next Sprint:** Phase 2 - Chores System Implementation

**Blockers:** None

---

## 📝 Development Notes

### Session 1 - December 18, 2025
- ✅ Created project repository
- ✅ Established development roadmap
- ✅ Defined all project phases and requirements
- ✅ Built complete backend scaffolding with FastAPI
- ✅ Created frontend structure with React + Vite + Tailwind
- ✅ Implemented user authentication system
- ✅ Designed database schema for users, chores, and meals
- ✅ Created Docker configuration for easy deployment
- ✅ Added comprehensive documentation
- **Status:** Phase 1 COMPLETE! Ready to move to Phase 2
- **Next:** Implement chore CRUD operations and frontend UI

---

## 🎨 Design Decisions

### User Experience
- Mobile-first responsive design
- Dark mode support
- Accessibility (WCAG 2.1 AA)
- Fast page loads (<2s)

### Data Architecture
- Local-first approach (fast, offline-capable)
- Sync to cloud for backup
- Privacy-focused (no third-party analytics)

### Chore Assignment Philosophy
- Fair distribution among age-appropriate users
- Visual progress tracking
- Gamification elements (optional rewards/points)
- Flexible scheduling (swap/skip capabilities)

---

## 📚 Resources & References

- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [React Documentation](https://react.dev/)
- [Mealie API Docs](https://docs.mealie.io/)
- [Google Calendar API](https://developers.google.com/calendar)
- [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)

---

## 🚀 Quick Commands

```bash
# Start development servers with Docker
docker-compose up -d

# Start backend only
cd backend && uvicorn app.main:app --reload

# Start frontend only
cd frontend && npm run dev

# Initialize database with family members
cd backend && python init_db.py

# Run tests
cd backend && pytest
cd frontend && npm test

# View API documentation
# Visit: http://localhost:8000/docs
```

---

## 📦 Project Files Overview

### Backend Structure
```
backend/
├── app/
│   ├── api/          # API route handlers
│   │   ├── auth.py   # JWT authentication
│   │   ├── users.py  # User management
│   │   └── chores.py # Chore operations
│   ├── core/         # Core functionality
│   │   ├── config.py    # Settings
│   │   ├── database.py  # DB connection
│   │   └── security.py  # Password hashing, tokens
│   ├── models/       # SQLAlchemy models
│   │   ├── user.py
│   │   ├── chore.py
│   │   └── meal.py
│   └── schemas/      # Pydantic validation schemas
├── init_db.py        # Database initialization
└── requirements.txt  # Python dependencies
```

### Frontend Structure
```
frontend/
├── src/
│   ├── components/   # Reusable components (to be added)
│   ├── pages/        # Page components (to be added)
│   ├── App.tsx       # Main application
│   └── main.tsx      # Entry point
├── package.json
└── vite.config.ts
```

---

**Legend:**
- ✅ Completed
- 🚧 In Progress
- ⏳ Pending
- ❌ Blocked
- 📌 High Priority

---

**🎉 Phase 1 Complete! The foundation is solid and ready for feature development.**