590 lines
16 KiB
Markdown
590 lines
16 KiB
Markdown
<<<<<<< HEAD
|
|
# 🏠 Family Hub
|
|
|
|
A comprehensive home management system for calendar, chores, menu planning, and shopping lists.
|
|
|
|
[]()
|
|
[]()
|
|
|
|
---
|
|
|
|
## 🌟 Features
|
|
|
|
### ✅ Chore Management (Phase 3.1 - Current)
|
|
- **Historical Completion Tracking** - Never lose chore completion data
|
|
- **Weekly Reports** - Visual dashboards with charts and leaderboards
|
|
- **Personal Statistics** - Individual performance tracking
|
|
- **Family Leaderboards** - Top performers with medals
|
|
- **Kiosk Interface** - Tablet-optimized touch interface
|
|
- **Admin Dashboard** - Complete chore management
|
|
- **Avatar Support** - Personalized user profiles
|
|
- **Birthday Recognition** - Auto-skip chores on birthdays
|
|
|
|
### 📊 Reporting & Analytics
|
|
- Weekly completion statistics
|
|
- Top performers tracking
|
|
- Completions by day/chore/user
|
|
- Recent activity timeline
|
|
- Personal stats (all-time, weekly, monthly)
|
|
- Favorite chore calculation
|
|
|
|
### 🎨 User Interface
|
|
- Modern, responsive design
|
|
- Beautiful gradients and colors
|
|
- Avatar integration
|
|
- Mobile/tablet/desktop support
|
|
- Touch-optimized kiosk view
|
|
- Real-time updates
|
|
|
|
---
|
|
|
|
## 🚀 Tech Stack
|
|
|
|
### Backend
|
|
- **FastAPI** - Modern Python web framework
|
|
- **SQLAlchemy** - ORM for database management
|
|
- **SQLite** - Lightweight database
|
|
- **Pydantic** - Data validation
|
|
- **Python 3.11+**
|
|
|
|
### Frontend
|
|
- **React 18** - UI library
|
|
- **TypeScript** - Type-safe JavaScript
|
|
- **Vite** - Build tool
|
|
- **Tailwind CSS** - Utility-first CSS
|
|
- **React Router** - Navigation
|
|
- **Axios** - HTTP client
|
|
- **Heroicons** - Beautiful icons
|
|
=======
|
|
# 🏠 Family Hub - Home Management System
|
|
|
|
> A comprehensive family management system for organizing daily life - calendar, chores, meals, and shopping.
|
|
|
|
[](https://gitea.hideawaygaming.com.au/jessikitty/family-hub)
|
|
[](https://www.python.org/)
|
|
[](https://react.dev/)
|
|
[](PROJECT_ROADMAP.md)
|
|
|
|
---
|
|
|
|
## 📖 About
|
|
|
|
Family Hub is a standalone home management system designed for families to coordinate their daily lives in one place. Think of it as "Skylight on steroids" - but self-hosted and customizable for your family's specific needs.
|
|
|
|
Built for a family of 5 (Lou, Jess, William, Xander, Bella) plus pets (Chips the cat 🐱 and Harper the dog 🐕), this system helps manage:
|
|
|
|
- 📅 **Family Calendar** - Google Calendar integration
|
|
- 🧹 **Chore Tracking** - Daily, weekly, fortnightly, and ad-hoc tasks
|
|
- 🍽️ **Menu Planning** - Mealie integration for meal planning
|
|
- 🛒 **Shopping Lists** - Auto-generated from meals + manual items
|
|
- 🏡 **Home Assistant** - Push notifications and dashboard integration
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
### ✅ Currently Available (Phase 1 - Complete)
|
|
|
|
- **User Management** - 5 family member profiles with roles
|
|
- **Authentication** - Secure JWT-based login system
|
|
- **Database** - SQLite with models for users, chores, and meals
|
|
- **API Backend** - FastAPI with auto-generated documentation
|
|
- **Frontend Foundation** - React 18 with Tailwind CSS
|
|
- **Docker Setup** - Easy deployment with Docker Compose
|
|
|
|
### 🚧 In Development (Phase 2)
|
|
|
|
- **Chore System** - Create, assign, and track household tasks
|
|
- **Recurring Schedules** - Daily, weekly, fortnightly patterns
|
|
- **Assignment Logic** - Individual, shared, and rotating chores
|
|
- **Completion Tracking** - Mark tasks done with history
|
|
|
|
### 🔜 Coming Soon
|
|
|
|
- **Google Calendar Sync** - Two-way calendar integration (Phase 3)
|
|
- **Mealie Integration** - Recipe management and meal planning (Phase 4)
|
|
- **Dashboard** - Unified home view with widgets (Phase 5)
|
|
- **Home Assistant** - Notifications and dashboard cards (Phase 6)
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- **Docker & Docker Compose** (recommended)
|
|
- OR Python 3.11+ and Node.js 18+ for local development
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone https://gitea.hideawaygaming.com.au/jessikitty/family-hub.git
|
|
cd family-hub
|
|
```
|
|
|
|
2. **Configure environment**
|
|
```bash
|
|
cp backend/.env.example backend/.env
|
|
# Edit backend/.env and set a strong SECRET_KEY
|
|
```
|
|
|
|
3. **Start the application**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Initialize database** (first run only)
|
|
```bash
|
|
docker-compose exec backend python init_db.py
|
|
```
|
|
|
|
5. **Access the application**
|
|
- Frontend: http://localhost:5173
|
|
- Backend API: http://localhost:8000
|
|
- API Docs: http://localhost:8000/docs
|
|
|
|
### Default Credentials
|
|
|
|
| User | Username | Password | Role |
|
|
|------|----------|----------|------|
|
|
| Lou | `lou` | `changeme123` | User |
|
|
| **Jess** | `jess` | `changeme123` | **Admin** |
|
|
| William | `william` | `changeme123` | User |
|
|
| Xander | `xander` | `changeme123` | User |
|
|
| Bella | `bella` | `changeme123` | User |
|
|
|
|
⚠️ **Change these passwords immediately after first login!**
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
<<<<<<< HEAD
|
|
familyhub/
|
|
├── backend/
|
|
│ ├── app/
|
|
│ │ ├── api/v1/ # API endpoints
|
|
│ │ ├── models/ # SQLAlchemy models
|
|
│ │ ├── schemas/ # Pydantic schemas
|
|
│ │ └── core/ # Core configuration
|
|
│ ├── migrations/ # Database migrations
|
|
│ └── data/ # SQLite database (gitignored)
|
|
├── frontend/
|
|
│ ├── src/
|
|
│ │ ├── api/ # API service layer
|
|
│ │ ├── components/ # React components
|
|
│ │ ├── pages/ # Page components
|
|
│ │ ├── contexts/ # React contexts
|
|
│ │ └── types/ # TypeScript types
|
|
│ └── public/ # Static assets
|
|
└── docs/ # Documentation
|
|
=======
|
|
family-hub/
|
|
├── PROJECT_ROADMAP.md # Development tracker (CHECK THIS REGULARLY!)
|
|
├── SETUP.md # Detailed setup instructions
|
|
├── README.md # This file
|
|
├── docker-compose.yml # Container orchestration
|
|
│
|
|
├── backend/ # FastAPI Backend
|
|
│ ├── app/
|
|
│ │ ├── api/ # API endpoints (auth, users, chores)
|
|
│ │ ├── core/ # Config, database, security
|
|
│ │ ├── models/ # SQLAlchemy database models
|
|
│ │ └── schemas/ # Pydantic validation schemas
|
|
│ ├── init_db.py # Database initialization
|
|
│ └── requirements.txt # Python dependencies
|
|
│
|
|
└── frontend/ # React Frontend
|
|
├── src/
|
|
│ ├── App.tsx # Main application
|
|
│ └── main.tsx # Entry point
|
|
├── package.json # Node dependencies
|
|
└── vite.config.ts # Build configuration
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|
|
```
|
|
|
|
---
|
|
|
|
<<<<<<< HEAD
|
|
## 🛠️ Installation
|
|
|
|
### Prerequisites
|
|
- Python 3.11+
|
|
- Node.js 18+
|
|
- Git
|
|
|
|
### Backend Setup
|
|
```bash
|
|
cd backend
|
|
python -m venv venv
|
|
venv\Scripts\activate # Windows
|
|
pip install -r requirements.txt
|
|
python run.py
|
|
```
|
|
|
|
Backend runs on: `http://localhost:8000`
|
|
|
|
### Frontend Setup
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend runs on: `http://localhost:5173`
|
|
=======
|
|
## 🛠️ Tech Stack
|
|
|
|
### Backend
|
|
- **FastAPI** - Modern Python web framework
|
|
- **SQLAlchemy** - SQL toolkit and ORM
|
|
- **SQLite** - Lightweight database (PostgreSQL-ready for production)
|
|
- **Pydantic** - Data validation using Python type annotations
|
|
- **JWT** - Secure authentication with JSON Web Tokens
|
|
|
|
### Frontend
|
|
- **React 18** - JavaScript library for building user interfaces
|
|
- **Vite** - Next generation frontend tooling
|
|
- **Tailwind CSS** - Utility-first CSS framework
|
|
- **TypeScript** - Typed JavaScript for better development experience
|
|
|
|
### DevOps
|
|
- **Docker** - Containerization for consistent environments
|
|
- **Docker Compose** - Multi-container orchestration
|
|
- **Uvicorn** - Lightning-fast ASGI server
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
<<<<<<< HEAD
|
|
- [Phase 3.1 Summary](PHASE_3_1_SUMMARY.md) - Complete feature overview
|
|
- [Phase 3.1 Backend Guide](PHASE_3_1_COMPLETE.md) - Backend implementation
|
|
- [Phase 3.1 Frontend Guide](PHASE_3_1_FRONTEND_COMPLETE.md) - Frontend features
|
|
- [Quick Start Testing](QUICK_START_TESTING.md) - Testing guide
|
|
- [API Documentation](TESTING_GUIDE.md) - API reference
|
|
- [Enhancement Roadmap](PHASE_3_1_ENHANCEMENTS_ROADMAP.md) - Future features
|
|
|
|
---
|
|
|
|
## 🎯 Roadmap
|
|
|
|
### Phase 3.1 (✅ Complete)
|
|
- Historical completion tracking
|
|
- Weekly reports and analytics
|
|
- User statistics dashboard
|
|
- Enhanced kiosk interface
|
|
- Verification system
|
|
|
|
### Phase 3.2 (🎨 Planned - Enhancements)
|
|
- Recharts for interactive graphs
|
|
- Custom date range picker
|
|
- Celebration animations
|
|
- Email weekly summaries
|
|
- Discord bot integration
|
|
- Enhanced completion modal with notes
|
|
|
|
### Phase 4 (📅 Future - Calendar Module)
|
|
- Google Calendar integration
|
|
- Event management
|
|
- User tagging in events
|
|
- Grid and list views
|
|
|
|
### Phase 5 (🍽️ Future - Menu Planning)
|
|
- Mealie integration
|
|
- Menu planning
|
|
- Shopping list generation
|
|
- Recipe management
|
|
|
|
---
|
|
|
|
## 👥 Family Members
|
|
|
|
- **Lou** - Parent
|
|
- **Jess** - Parent (Admin)
|
|
- **William** - Child
|
|
- **Xander** - Child
|
|
- **Bella** - Child
|
|
|
|
### 🐾 Pets
|
|
- **Harper** - Dog (Morning & evening feeding)
|
|
- **Chips** - Cat (Daily feeding, litter maintenance)
|
|
|
|
---
|
|
|
|
## 🏡 Home Layout
|
|
|
|
### Shared Spaces
|
|
- Kitchen (with dishwasher)
|
|
- Dining Room
|
|
- Living Area
|
|
- Computer Area
|
|
- Bathroom
|
|
- Toilet
|
|
- Laundry (with washer & dryer)
|
|
|
|
### Personal Spaces
|
|
- 5 Bedrooms (one per family member)
|
|
- Master Ensuite (Jess's room)
|
|
|
|
---
|
|
|
|
## 📊 Current Statistics
|
|
|
|
**Phase 3.1 Implementation:**
|
|
- **Files Created**: 19
|
|
- **Files Modified**: 8
|
|
- **Total Lines**: ~3,500+
|
|
- **Components**: 10+
|
|
- **API Endpoints**: 7
|
|
- **Database Tables**: 1
|
|
=======
|
|
- **[SETUP.md](SETUP.md)** - Complete setup guide with troubleshooting
|
|
- **[PROJECT_ROADMAP.md](PROJECT_ROADMAP.md)** - Development progress tracker (⭐ **CHECK THIS REGULARLY!**)
|
|
- **[SESSION_SUMMARY.md](SESSION_SUMMARY.md)** - Latest development session notes
|
|
- **API Docs** - Auto-generated at http://localhost:8000/docs
|
|
|
|
---
|
|
|
|
## 🎯 Development Progress
|
|
|
|
**Current Status:** Phase 1 Complete ✅ (30% overall progress)
|
|
|
|
See [PROJECT_ROADMAP.md](PROJECT_ROADMAP.md) for detailed progress tracking.
|
|
|
|
### Completed Phases
|
|
- ✅ **Phase 1:** Foundation & Core Setup
|
|
|
|
### Current Phase
|
|
- 🚧 **Phase 2:** Chores System (In Planning)
|
|
|
|
### Upcoming Phases
|
|
- ⏳ Phase 3: Calendar Integration
|
|
- ⏳ Phase 4: Menu Planning & Shopping
|
|
- ⏳ Phase 5: Dashboard & Home View
|
|
- ⏳ Phase 6: Home Assistant Integration
|
|
- ⏳ Phase 7: Polish & Deployment
|
|
|
|
---
|
|
|
|
## 🏠 Family Configuration
|
|
|
|
### Household Layout
|
|
- **5 Bedrooms** - Lou, Jess (with Ensuite), William, Xander, Bella
|
|
- **2 Bathrooms** - Shared bathroom + Master ensuite
|
|
- **Kitchen** - Dishwasher, hand washing area
|
|
- **Laundry** - Washing machine, dryer
|
|
- **Dining Room**
|
|
- **Outdoor Areas**
|
|
|
|
### Pets
|
|
- **Chips (Cat)** 🐱 - Daily feeding, watering, litter maintenance
|
|
- **Harper (Dog)** 🐕 - Daily feeding, watering
|
|
|
|
### Weekly Schedule
|
|
- **Bins** - Wednesday morning pickup
|
|
- **Recycling** - Fortnightly (alternates with greens)
|
|
- **Greens Bin** - Fortnightly (alternates with recycling)
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Backend Configuration
|
|
|
|
Copy `backend/.env.example` to `backend/.env` and customize:
|
|
|
|
```env
|
|
# Application
|
|
APP_NAME=Family Hub
|
|
DEBUG=True
|
|
|
|
# Database
|
|
DATABASE_URL=sqlite:///./family_hub.db
|
|
|
|
# Security (CHANGE THIS!)
|
|
SECRET_KEY=your-super-secret-key-here
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
|
|
# CORS
|
|
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
|
|
```
|
|
|
|
### Future Integrations
|
|
|
|
The system is designed to integrate with:
|
|
|
|
```env
|
|
# Google Calendar (Phase 3)
|
|
GOOGLE_CLIENT_ID=your-client-id
|
|
GOOGLE_CLIENT_SECRET=your-client-secret
|
|
|
|
# Mealie (Phase 4)
|
|
MEALIE_API_URL=http://your-mealie-instance
|
|
MEALIE_API_TOKEN=your-api-token
|
|
|
|
# Home Assistant (Phase 6)
|
|
HOME_ASSISTANT_URL=http://your-ha-instance
|
|
HOME_ASSISTANT_TOKEN=your-long-lived-token
|
|
```
|
|
|
|
---
|
|
|
|
## 💻 Development Commands
|
|
|
|
```bash
|
|
# Start services with Docker
|
|
docker-compose up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f frontend
|
|
|
|
# Stop services
|
|
docker-compose down
|
|
|
|
# Rebuild containers
|
|
docker-compose up -d --build
|
|
|
|
# Run backend tests
|
|
cd backend && pytest
|
|
|
|
# Run frontend tests
|
|
cd frontend && npm test
|
|
|
|
# Access backend shell
|
|
docker-compose exec backend bash
|
|
|
|
# Database operations
|
|
docker-compose exec backend python init_db.py
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 API Endpoints
|
|
|
|
Once running, explore the API at http://localhost:8000/docs
|
|
|
|
### Authentication
|
|
- `POST /api/v1/auth/register` - Register new user
|
|
- `POST /api/v1/auth/login` - Login and get JWT token
|
|
- `POST /api/v1/auth/refresh` - Refresh access token
|
|
|
|
### Users
|
|
- `GET /api/v1/users` - List all users (admin only)
|
|
- `GET /api/v1/users/{id}` - Get user details
|
|
- `PUT /api/v1/users/{id}` - Update user
|
|
- `DELETE /api/v1/users/{id}` - Delete user (admin only)
|
|
|
|
### Chores (In Development)
|
|
- `GET /api/v1/chores` - List all chores
|
|
- `POST /api/v1/chores` - Create new chore
|
|
- `GET /api/v1/chores/{id}` - Get chore details
|
|
- `PUT /api/v1/chores/{id}` - Update chore
|
|
- `DELETE /api/v1/chores/{id}` - Delete chore
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
This is a family project, but suggestions and improvements are welcome!
|
|
|
|
<<<<<<< HEAD
|
|
=======
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
---
|
|
|
|
## 🆘 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Port already in use:**
|
|
```bash
|
|
# Check what's using the port
|
|
sudo lsof -i :8000
|
|
sudo lsof -i :5173
|
|
|
|
# Change ports in docker-compose.yml if needed
|
|
```
|
|
|
|
**Database not initializing:**
|
|
```bash
|
|
docker-compose down -v
|
|
docker-compose up -d --build
|
|
docker-compose exec backend python init_db.py
|
|
```
|
|
|
|
**Frontend not loading:**
|
|
```bash
|
|
# Rebuild frontend container
|
|
docker-compose up -d --build frontend
|
|
```
|
|
|
|
For more help, see [SETUP.md](SETUP.md) or check the API docs at `/docs`.
|
|
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
<<<<<<< HEAD
|
|
Private family project - All rights reserved
|
|
|
|
---
|
|
|
|
## 🎉 Acknowledgments
|
|
|
|
Built with ❤️ by Jess & Claude
|
|
**Version**: Phase 3.1
|
|
**Date**: February 4, 2026
|
|
|
|
---
|
|
|
|
## 🔗 Links
|
|
|
|
- **Repository**: https://gitea.hideawaygaming.com.au/jessikitty/family-hub
|
|
- **Backend API**: http://10.0.0.243:8000
|
|
- **Frontend**: http://10.0.0.243:5173
|
|
- **Kiosk**: http://10.0.0.243:5173/kiosk
|
|
|
|
---
|
|
|
|
**Status**: Phase 3.1 Complete - Ready for Enhancements! 🚀
|
|
=======
|
|
This project is licensed under the MIT License - feel free to use it as inspiration for your own family management system!
|
|
|
|
---
|
|
|
|
## 🌟 Project Status
|
|
|
|
- **Created:** December 18, 2025
|
|
- **Current Version:** 0.1.0
|
|
- **Phase:** 1 of 7 Complete
|
|
- **Status:** 🟢 Active Development
|
|
|
|
---
|
|
|
|
## 📞 Links
|
|
|
|
- **Repository:** https://gitea.hideawaygaming.com.au/jessikitty/family-hub
|
|
- **Development Tracker:** [PROJECT_ROADMAP.md](PROJECT_ROADMAP.md)
|
|
- **Setup Guide:** [SETUP.md](SETUP.md)
|
|
- **API Documentation:** http://localhost:8000/docs (when running)
|
|
|
|
---
|
|
|
|
**Built with ❤️ for family organization**
|
|
|
|
*Making household management easier, one task at a time!*
|
|
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
|