370 lines
10 KiB
Markdown
370 lines
10 KiB
Markdown
# 🏠 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!**
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ 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
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
- **[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
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
This is a family project, but suggestions and improvements are welcome!
|
|
|
|
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`.
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
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!*
|