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

Clone the repository

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

Configure environment

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

Start the application
```
docker-compose up -d
```

Initialize database (first run only)

docker-compose exec backend python init_db.py

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!

65c71b3d67

📁 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

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

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

65c71b3d67

📖 Documentation

<<<<<<< HEAD

Phase 3.1 Summary - Complete feature overview
Phase 3.1 Backend Guide - Backend implementation
Phase 3.1 Frontend Guide - Frontend features
Quick Start Testing - Testing guide
API Documentation - API reference
Enhancement Roadmap - 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

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

65c71b3d67

🤝 Contributing

This is a family project, but suggestions and improvements are welcome!

<<<<<<< HEAD

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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.

65c71b3d67

📝 License

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

65c71b3d67

Languages

TypeScript 52.6%

Python 33.4%

Batchfile 11.1%

HTML 1.4%

Makefile 0.7%

Other 0.7%

README.md

🏠 Family Hub

🌟 Features

✅ Chore Management (Phase 3.1 - Current)

📊 Reporting & Analytics

🎨 User Interface

🚀 Tech Stack

Backend

Frontend

🏠 Family Hub - Home Management System

📖 About

✨ Features

✅ Currently Available (Phase 1 - Complete)

🚧 In Development (Phase 2)

🔜 Coming Soon

🚀 Quick Start

Prerequisites

Installation

Default Credentials

📁 Project Structure

🛠️ Installation

Prerequisites

Backend Setup

Frontend Setup

Frontend runs on: http://localhost:5173

🛠️ Tech Stack

Backend

Frontend

DevOps

📖 Documentation

🎯 Roadmap

Phase 3.1 (✅ Complete)

Phase 3.2 (🎨 Planned - Enhancements)

Phase 4 (📅 Future - Calendar Module)

Phase 5 (🍽️ Future - Menu Planning)

👥 Family Members

🐾 Pets

🏡 Home Layout

Shared Spaces

Personal Spaces

📊 Current Statistics

🎯 Development Progress

Completed Phases

Current Phase

Upcoming Phases

🏠 Family Configuration

Household Layout

Pets

Weekly Schedule

🔧 Configuration

Backend Configuration

Future Integrations

💻 Development Commands

🧪 API Endpoints

Authentication

Users

Chores (In Development)

🤝 Contributing

<<<<<<< HEAD

🆘 Troubleshooting

Common Issues

📝 License

🎉 Acknowledgments

🔗 Links

Status: Phase 3.1 Complete - Ready for Enhancements! 🚀

🌟 Project Status

📞 Links

Frontend runs on: `http://localhost:5173`