<<<<<<< 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