jessikitty/family-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 3.1: Add remaining local files

Browse Source
This commit is contained in:
Jess
2026-02-05 16:04:20 +11:00
parent e3cae7bfbb 65c71b3d67
commit c4706f1779
26 changed files with 1780 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
README.md
View File

@@ -1,3 +1,4 @@
<<<<<<< HEAD
# 🏠 Family Hub
A comprehensive home management system for calendar, chores, menu planning, and shopping lists.
@@ -54,12 +55,114 @@ A comprehensive home management system for calendar, chores, menu planning, and
- **React Router** - Navigation
- **Axios** - HTTP client
- **Heroicons** - Beautiful icons
=======
# 🏠 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!**
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
---
## 📁 Project Structure
```
<<<<<<< HEAD
familyhub/
├── backend/
│ ├── app/
@@ -78,10 +181,34 @@ familyhub/
│ │ └── 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
@@ -108,11 +235,33 @@ 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
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
---
## 📖 Documentation
<<<<<<< HEAD
- [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
@@ -193,6 +342,151 @@ Frontend runs on: `http://localhost:5173`
- **Components**: 10+
- **API Endpoints**: 7
- **Database Tables**: 1
=======
- **[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
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
---
@@ -200,10 +494,50 @@ Frontend runs on: `http://localhost:5173`
This is a family project, but suggestions and improvements are welcome!
<<<<<<< HEAD
=======
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`.
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2
---
## 📝 License
<<<<<<< HEAD
Private family project - All rights reserved
---
@@ -226,3 +560,30 @@ Built with ❤️ by Jess & Claude
---
**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](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!*
>>>>>>> 65c71b3d67d462fe9ecc01a1c2aa17e54b626fe2