# 🏠 Family Hub

A comprehensive home management system for calendar, chores, menu planning, and shopping lists.

[![Status](https://img.shields.io/badge/status-active-success.svg)]()
[![Phase](https://img.shields.io/badge/phase-3.1-blue.svg)]()

---

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

---

## 📁 Project Structure

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

---

## 🛠️ 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`

---

## 📖 Documentation

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

---

## 🤝 Contributing

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

---

## 📝 License

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