🌳 Family Tree

A full‑stack Family Tree application with modern web technologies, designed for local development and cloud deployment.

Tech Stack:

• Frontend: Next.js (TypeScript) with ESLint and nature‑themed UI
• Backend: FastAPI (Python 3.12.3) with JWT authentication
• Database: Google Firestore
• Development: Pre-commit hooks, syntax validation, automated testing
• Deployment: Docker + GitHub Actions CI/CD to Google Cloud Run

Features

• Authentication: Login, register with invite codes, password reset
• Family Tree: Visual tree with CRUD operations, member relationships
• Profile Pictures: Upload and manage member profile pictures with automatic optimization
• Family Album: Photo sharing with likes, tags, bulk upload/delete, progress tracking, and optional CDN support
• WhatsApp Import: Import photos from WhatsApp chat exports into album with duplicate detection
• Bulk Upload: Import multiple family members from JSON files with automatic de-duplication
• Map Integration: Optional Google Maps integration for member locations
• Quality Assurance: Comprehensive testing, linting, and code formatting
• Development Tools: Pre-commit hooks, syntax validation, and automated checks
• Cloud Ready: Production deployment to Google Cloud Run

Quick Start

Prerequisites: Node 18+, Python 3.12.3, uv (install), Google Cloud project with Firestore

Local Development

# 1. Setup dev tools (pre-commit hooks, linting)
./scripts/setup-dev-tools.sh

# 2. Configure environment
# Create backend/.env with:
#   - GOOGLE_CLOUD_PROJECT=your-project-id
#   - FIRESTORE_DATABASE=family-tree
#   - JWT_SECRET=your-secret-key
#   - GCS_BUCKET_NAME=your-bucket-name  # For profile pictures
#   - ALBUM_BUCKET_NAME=your-album-bucket  # For family album photos
#   - CDN_BASE_URL=  # Optional - CDN URL for album photos (e.g. https://cdn.example.com)
#                    # If not set, uses signed URLs with 7-day expiration
#   - MAX_UPLOAD_SIZE_MB=5  # Optional, defaults to 5MB
# Create frontend/.env.local with:
#   - NEXT_PUBLIC_API_BASE=http://localhost:8080

# 3. Start backend
cd backend && uv venv --python 3.12.3 && uv sync
uv run uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

# 4. Start frontend (in new terminal)
cd frontend && npm install && npm run dev

Or use Docker: docker compose up --build

Access: http://localhost:3000

� Photo Album & CDN Support

The Family Album feature supports optional CDN configuration for optimized photo delivery:

Without CDN (Default):

• Photos served via signed URLs from Google Cloud Storage
• 7-day URL expiration (configurable via SIGNED_URL_EXPIRATION_DAYS)
• Suitable for small-to-medium deployments
• No additional configuration needed

With CDN (Recommended for Production):

• Photos cached at edge locations for faster loading
• Reduced GCS egress costs
• Better performance globally
• Configure via CDN_BASE_URL environment variable

Example CDN setup:

# Enable Google Cloud CDN for your album bucket
CDN_BASE_URL=https://cdn.example.com
SIGNED_URL_EXPIRATION_DAYS=7  # For non-CDN fallback

See FAMILY_ALBUM.md for full configuration details.

�🚀 Deployment

Deploy your own instance: See Forked Deployment Guide

Quick steps: Fork → Configure env vars → Run gcp_bootstrap_family_tree.sh → Initialize Firestore → Create admin → Deploy via GitHub Actions

Key scripts in backend/scripts/:

• gcp_bootstrap_family_tree.sh - GCP infrastructure setup
• initialize_collections.py - Firestore database init
• seed_admin.py - Create admin account
• populate_dummy_data.py - Test data (optional)

Documentation:

• 📖 Forked Deployment Guide - Complete walkthrough
• 🔧 Backend Scripts Reference - Script usage details
• ☁️ Deployment Guide - CI/CD and cloud setup

Testing

# Backend
cd backend && uv run pytest --cov=app

# Frontend
cd frontend && npm test

# All quality checks
pre-commit run --all-files

Documentation

• Architecture Overview - Technical architecture, data flow, and sequence diagrams
• Family Album - Photo sharing feature with likes, tags, and filtering
• WhatsApp Import - Import photos from WhatsApp chat exports
• Screenshots - Application screenshots and UI examples
• Bulk Upload Guide - Instructions for bulk uploading family members from JSON files
• Deployment Guide - CI/CD setup, Docker configuration, and cloud deployment
• Event Notifications - Automated email notifications setup and configuration
• GitHub Actions Notifications - Cloud-based automated notifications setup

Contributing

1. Run ./scripts/setup-dev-tools.sh to install pre-commit hooks
2. Read Contributing Guide for workflow and standards
3. Check Architecture Overview for codebase understanding

License

AGPLv3 (default): Open source use. Network deployment requires sharing source code. See LICENSE.

Commercial license available for proprietary use. Contact: [your-email@example.com]

See COMMERCIAL.md for details.