Family Tree Management System

A comprehensive digital family tree application that allows users to create, manage, and explore their family connections with advanced features like real-time notifications, AI-powered chatbot assistance, and collaborative family management.

🌟 Features

👥 Family Management

Create & Join Families: Start your own family tree or request to join existing ones
Smart Member Linking: Auto-match by email or manual linking for existing family members
Role-Based Access: Family admin controls with member permissions
Member Profiles: Detailed profiles with photos, relationships, and personal information

🌳 Interactive Family Tree

Visual Tree Representation: Interactive family tree visualization using D3.js
Relationship Mapping: Define complex family relationships (parent, spouse, sibling, etc.)
Tree Navigation: Smooth navigation through large family structures
Export Options: Export family tree as PDF or image

🔔 Real-Time Notifications

Live Updates: Real-time notifications using Socket.IO
Family-Specific: Notifications filtered by user's joined families
Request Management: Join requests, member additions, and family updates
Smart Filtering: Organized notification system with read/unread states

📅 Events & Milestones

Family Events: Create and manage family gatherings, celebrations, and milestones
Event Reminders: Automated notification system for upcoming events
Photo Sharing: Share memories and photos from family events

🏆 Achievements System

Family Achievements: Track and celebrate family milestones
Member Recognition: Individual and collective family achievements
Progress Tracking: Visual progress indicators for various goals

💭 Anonymous Confessions

Safe Space: Anonymous confession system for family members
Community Support: Share thoughts and experiences within the family
Moderated Content: Admin oversight with editing and deletion capabilities

🤖 AI-Powered Assistant

Smart Chatbot: Google Gemini AI integration for family-related assistance
Family Insights: Get answers about family history, relationships, and genealogy
Intelligent Suggestions: AI-powered recommendations for family connections

📱 Modern User Experience

Responsive Design: Mobile-first design with Tailwind CSS
Real-Time Updates: Live synchronization across all connected devices
Intuitive Interface: Clean, modern UI with smooth animations
Dark/Light Mode: User preference-based theme switching

🛠 Tech Stack

Backend

Node.js with Express.js - RESTful API server
TypeScript - Type-safe development
Prisma ORM - Database modeling and queries
PostgreSQL - Primary database (Supabase)
Socket.IO - Real-time communication
JWT - Authentication and authorization
Swagger - API documentation
Google Gemini AI - Chatbot integration
Cloudinary - Image storage and optimization

Frontend

React 18 - Modern UI library
Vite - Fast build tool and dev server
Tailwind CSS - Utility-first styling
D3.js - Family tree visualization
Socket.IO Client - Real-time updates
Axios - HTTP client
React Router - Client-side routing
Framer Motion - Smooth animations

DevOps & Deployment

Docker - Containerization
Render - Cloud deployment platform
Supabase - Database hosting
GitHub Actions - CI/CD pipeline

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18 or higher)
npm or yarn
PostgreSQL database
Git

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/thu2005/family-tree.git
cd family-tree

2. Backend Setup

cd backend
npm install

# Copy environment variables
cp .env.example .env

# Configure your .env file with:
# - Database URL (PostgreSQL)
# - JWT Secret
# - Google Gemini API Key
# - Cloudinary credentials
# - Supabase credentials

# Set up database
npm run db:generate
npm run db:push
npm run db:seed

# Start backend server
npm run dev

3. Frontend Setup

cd ../frontend
npm install

# Copy environment variables
cp .env.example .env

# Configure your .env file with:
# - VITE_API_URL=http://localhost:3001/api
# - Firebase configuration (optional)

# Start frontend development server
npm start

4. Access the Application

Frontend: http://localhost:4028
Backend API: http://localhost:3001
API Documentation: http://localhost:3001/api-docs

🔧 Environment Variables

Backend (.env)

NODE_ENV=development
PORT=3001

# Database (Supabase PostgreSQL)
DATABASE_URL="postgresql://username:password@host:port/database"
DIRECT_URL="postgresql://username:password@host:port/database"

# Supabase
SUPABASE_URL="your-supabase-url"
SUPABASE_ANON_KEY="your-supabase-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# Authentication
JWT_SECRET="your-super-secret-jwt-key"
JWT_EXPIRES_IN="7d"

# Google AI
GEMINI_API_KEY="your-google-gemini-api-key"

# Cloudinary
CLOUDINARY_CLOUD_NAME="your-cloudinary-name"
CLOUDINARY_API_KEY="your-cloudinary-api-key"
CLOUDINARY_API_SECRET="your-cloudinary-api-secret"

# Frontend URL (for CORS)
FRONTEND_URL="http://localhost:4028"

Frontend (.env)

VITE_API_URL="http://localhost:3001/api"
VITE_SOCKET_URL="http://localhost:3001"

# Firebase (optional)
VITE_FIREBASE_API_KEY="your-firebase-api-key"
VITE_FIREBASE_AUTH_DOMAIN="your-project.firebaseapp.com"
VITE_FIREBASE_PROJECT_ID="your-project-id"

🐳 Docker Deployment

Development with Docker Compose

# Build and run all services
docker-compose -f docker-compose.dev.yml up --build

# Run in background
docker-compose -f docker-compose.dev.yml up -d

Production Deployment

# Build and run production containers
docker-compose up --build -d

# View logs
docker-compose logs -f

📚 API Documentation

The API is fully documented with Swagger/OpenAPI. Access the interactive documentation at:

Local: http://localhost:3001/api-docs
Production: https://your-domain.com/api-docs

Key API Endpoints

Authentication

POST /api/auth/register - Register new user
POST /api/auth/login - User login
POST /api/auth/logout - User logout
POST /api/auth/refresh - Refresh access token

Families

GET /api/families - Get user's families
POST /api/families - Create new family
PUT /api/families/:id - Update family details
POST /api/families/:id/join - Request to join family

Members

GET /api/families/:id/members - Get family members
POST /api/families/:id/members - Add new member
PUT /api/members/:id - Update member details
DELETE /api/members/:id - Remove member

Notifications

GET /api/notifications - Get user notifications
PUT /api/notifications/:id/mark-read - Mark as read
PUT /api/notifications/mark-all-read - Mark all as read

🔄 Real-Time Features

The application uses Socket.IO for real-time communication:

Socket Events

notification:new - New notification received
family:member-added - New member joined family
family:request-approved - Join request approved
family:update - Family information updated

Client Implementation

import { io } from 'socket.io-client';

const socket = io('http://localhost:3001', {
  auth: { token: 'your-jwt-token' }
});

// Listen for notifications
socket.on('notification:new', (notification) => {
  console.log('New notification:', notification);
});

🤖 AI Chatbot Integration

The application includes an AI-powered chatbot using Google Gemini:

Features

Family history inquiries
Relationship explanations
Genealogy guidance
General family-related assistance

Usage

// Send message to chatbot
POST /api/chatbot/chat
{
  "message": "How do I add a new family member?",
  "familyId": "family-id-here"
}

🧪 Testing

Backend Tests

cd backend
npm test

# Run with coverage
npm run test:coverage

Frontend Tests

cd frontend
npm test

# Run E2E tests
npm run test:e2e

📖 Database Schema

The application uses a PostgreSQL database with the following main entities:

Users - User accounts and authentication
Families - Family groups and metadata
FamilyMembers - Individual family members and relationships
FamilyJoinRequests - Requests to join families
Events - Family events and celebrations
Achievements - Family and member achievements
Confessions - Anonymous family confessions
Notifications - Real-time notification system

🚀 Deployment

Render.com (Recommended)

Fork this repository to your GitHub account
Create a new Web Service on Render:
- Connect your GitHub repository
- Use the provided render.yaml configuration
Configure Environment Variables in Render dashboard
Deploy - Render will automatically build and deploy your application

Manual Deployment

# Build production assets
cd frontend && npm run build
cd ../backend && npm run build

# Start production server
cd backend && npm start

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Use conventional commit messages
Add tests for new features
Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or need help:

Check the documentation
Search existing issues
Create a new issue with detailed information
Contact the development team

🙏 Acknowledgments

D3.js - For powerful family tree visualization
Prisma - For excellent database tooling
Socket.IO - For seamless real-time communication
Google Gemini - For AI-powered assistance
Tailwind CSS - For beautiful, responsive design
React Community - For continuous inspiration and support

🔮 Roadmap

Upcoming Features

Mobile App - React Native implementation
Advanced Analytics - Family statistics and insights
DNA Integration - Connect with genetic testing services
Multi-language Support - Internationalization
Family Stories - Collaborative storytelling feature
Calendar Integration - Sync with external calendars
Photo Recognition - AI-powered photo tagging
Family Newsletter - Automated family updates

Built with ❤️ for families around the world

Keep your family connections strong and your memories alive.

git clone <repository-url>
cd family-tree

Development mode (with hot reload):

sudo docker compose -f docker-compose.dev.yml up -d

Production mode (no hot reload):
```
sudo docker compose up -d
```
Access the application:
- Backend API: http://localhost:3001
- API Documentation (Swagger): http://localhost:3001/api-docs
- Health Check: http://localhost:3001/health

Stop services:

sudo docker compose down
# or for dev mode
sudo docker compose -f docker-compose.dev.yml down

🐳 Docker Commands

Development workflow (with hot reload):

# Start development mode with auto-reload
sudo docker compose -f docker-compose.dev.yml up -d

# View logs (will show nodemon restarts)
sudo docker compose -f docker-compose.dev.yml logs backend -f

# Stop development mode
sudo docker compose -f docker-compose.dev.yml down

Production workflow:

# Start production mode
sudo docker compose up -d

# View logs
sudo docker compose logs backend        # Backend logs only
sudo docker compose logs -f             # All logs with follow

# Restart services
sudo docker compose restart backend     # Restart backend only
sudo docker compose restart             # Restart all services

# Rebuild and restart (after dependency changes)
sudo docker compose up -d --build

# Stop services
sudo docker compose down

# Check status
sudo docker compose ps

🛠️ Local Development (Without Docker)

Backend Setup:

cd backend
npm install
npm run dev

Frontend Setup:

git clone <repository-url>
cd frontend

Install dependencies:
```
npm install
# or
yarn install
```
Start the development server:
```
npm start
# or
yarn start
```

📚 Backend Development Workflow

For detailed instructions on implementing new backend features, see: Backend Implementation Guide

This guide covers:

Step-by-step workflow for new features
Service → Controller → Route pattern
Testing with Swagger UI
Database operations with Prisma
Best practices and examples

📁 Project Structure

family-tree/
├── backend/            # Node.js + TypeScript + Prisma API
│   ├── src/           # Source code
│   ├── prisma/        # Database schema
│   ├── Dockerfile     # Docker configuration
│   └── package.json   # Dependencies
├── frontend/          # React + Vite application
│   ├── public/        # Static assets
│   ├── src/          
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── styles/        # Global styles and Tailwind configuration
│   │   ├── App.jsx        # Main application component
│   │   ├── Routes.jsx     # Application routes
│   │   └── index.jsx      # Application entry point
│   ├── index.html         # HTML template
│   ├── package.json       # Project dependencies and scripts
│   ├── tailwind.config.js # Tailwind CSS configuration
│   └── vite.config.js     # Vite configuration
└── docker-compose.yml     # Multi-service Docker setup

🧩 Adding Routes

To add new routes to the application, update the Routes.jsx file:

import { useRoutes } from "react-router-dom";
import HomePage from "pages/HomePage";
import AboutPage from "pages/AboutPage";

const ProjectRoutes = () => {
  let element = useRoutes([
    { path: "/", element: <HomePage /> },
    { path: "/about", element: <AboutPage /> },
    // Add more routes as needed
  ]);

  return element;
};

📦 Key Dependencies

Family Tree Visualization

family-chart (v0.9.0) - D3.js-based family tree library
- GitHub: https://github.com/SanichKotikov/react-family-tree
- Documentation: https://sanichkotikov.github.io/react-family-tree/
- Features: Interactive family trees with custom HTML cards, SVG connections, pan/zoom functionality

📦 Deployment

Docker Production Build:

# Build and start production containers
sudo docker compose -f docker-compose.yml up -d --build

# Or build specific service
sudo docker compose build backend

Manual Build:

# Backend
cd backend
npm run build

# Frontend  
cd frontend
npm run build

🔧 Environment Configuration

Backend Environment Variables:

Create /backend/.env.docker for Docker or /backend/.env for local development:

PORT=3001
NODE_ENV=production
DATABASE_URL=your_supabase_connection_string
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
JWT_SECRET=your_jwt_secret
GOOGLE_CLIENT_ID=your_google_client_id
FRONTEND_URL=http://localhost:4028

🚨 Troubleshooting

Docker Issues:

# Check container status
sudo docker compose ps

# View container logs
sudo docker compose logs backend

# Restart services
sudo docker compose restart

# Clean rebuild
sudo docker compose down
sudo docker compose up -d --build

Permission Issues:

If you get permission denied errors, add your user to docker group:

sudo usermod -aG docker $USER
# Then logout and login again

Name		Name	Last commit message	Last commit date
Latest commit History 235 Commits
.github/workflows		.github/workflows
backend		backend
frontend		frontend
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
render.yaml		render.yaml

Folders and files

Latest commit

History

Repository files navigation

Family Tree Management System

🌟 Features

👥 Family Management

🌳 Interactive Family Tree

🔔 Real-Time Notifications

📅 Events & Milestones

🏆 Achievements System

💭 Anonymous Confessions

🤖 AI-Powered Assistant

📱 Modern User Experience

🛠 Tech Stack

Backend

Frontend

DevOps & Deployment

📋 Prerequisites

🚀 Quick Start

1. Clone the Repository

2. Backend Setup

3. Frontend Setup

4. Access the Application

🔧 Environment Variables

Backend (.env)

Frontend (.env)

🐳 Docker Deployment

Development with Docker Compose

Production Deployment

📚 API Documentation

Key API Endpoints

Authentication

Families

Members

Notifications

🔄 Real-Time Features

Socket Events

Client Implementation

🤖 AI Chatbot Integration

Features

Usage

🧪 Testing

Backend Tests

Frontend Tests

📖 Database Schema

🚀 Deployment

Render.com (Recommended)

Manual Deployment

🤝 Contributing

Development Guidelines

📄 License

🆘 Support

🙏 Acknowledgments

🔮 Roadmap

Upcoming Features

🐳 Docker Commands

Development workflow (with hot reload):

Production workflow:

🛠️ Local Development (Without Docker)

🛠️ Local Development (Without Docker)

Backend Setup:

Frontend Setup:

📚 Backend Development Workflow

📁 Project Structure

🧩 Adding Routes

📦 Key Dependencies

Family Tree Visualization

📦 Deployment

Docker Production Build:

Manual Build:

🔧 Environment Configuration

Backend Environment Variables:

🚨 Troubleshooting

Docker Issues:

Permission Issues:

About

Resources

License

Uh oh!

Packages