# 🏠 Family Hub - Home Management System

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

[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://gitea.hideawaygaming.com.au/jessikitty/family-hub)
[![Python](https://img.shields.io/badge/python-3.11+-green.svg)](https://www.python.org/)
[![React](https://img.shields.io/badge/react-18-blue.svg)](https://react.dev/)
[![Status](https://img.shields.io/badge/status-Phase%201%20Complete-success.svg)](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!*