342 lines
8.8 KiB
Markdown
342 lines
8.8 KiB
Markdown
# 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.**
|