🏠 Family Hub - Home Management System

A comprehensive family management system for organizing daily life - calendar, chores, meals, and shopping.

---

📖 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

   git clone https://gitea.hideawaygaming.com.au/jessikitty/family-hub.git
   cd family-hub
   

2. Configure environment

   cp backend/.env.example backend/.env
   # Edit backend/.env and set a strong SECRET_KEY
   

3. Start the application

   docker-compose up -d
   

4. Initialize database (first run only)

   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 - Complete setup guide with troubleshooting
• PROJECT_ROADMAP.md - Development progress tracker (⭐ CHECK THIS REGULARLY!)
• 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 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:

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

# 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

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

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

docker-compose down -v
docker-compose up -d --build
docker-compose exec backend python init_db.py

Frontend not loading:

# Rebuild frontend container
docker-compose up -d --build frontend

For more help, see 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
• Setup Guide: SETUP.md
• API Documentation: http://localhost:8000/docs (when running)

---

Built with ❤️ for family organization

Making household management easier, one task at a time!