diff --git a/PROJECT_ROADMAP.md b/PROJECT_ROADMAP.md new file mode 100644 index 0000000..bbe8aea --- /dev/null +++ b/PROJECT_ROADMAP.md @@ -0,0 +1,341 @@ +# 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.**