invy/README.md

# 💒 Wedding Guest List App

A full-stack wedding guest list management application built with React + Vite frontend, FastAPI backend, and PostgreSQL database. Easily manage your wedding guests, import contacts from Google, and track RSVPs, meal preferences, and seating arrangements.

## ✨ Features

- **Guest Management**: Add, edit, and delete guest information
- **Contact Import**: Import contacts directly from your Google account
- **Search & Filter**: Find guests by name, email, phone, RSVP status, or meal preference
- **RSVP Tracking**: Track pending, accepted, and declined RSVPs
- **Meal Preferences**: Manage dietary requirements (vegetarian, vegan, gluten-free, kosher, halal)
- **Plus-Ones**: Track guests with plus-ones
- **Table Assignments**: Assign guests to tables
- **Modern UI**: User-friendly interface with a beautiful gradient design
- **Mobile Responsive**: Works seamlessly on all devices

## 🛠️ Tech Stack

### Frontend
- React 18
- Vite
- Axios for API calls
- CSS3 with modern styling

### Backend
- FastAPI
- SQLAlchemy ORM
- PostgreSQL database
- Google People API integration
- Pydantic for data validation

## 📋 Prerequisites

- **Node.js** (v16 or higher)
- **Python** (v3.8 or higher)
- **PostgreSQL** (v12 or higher)
- **Google Cloud Console** account (for contact import feature)

## 🚀 Installation & Setup

### 1. Clone the Repository

```bash
cd c:\Users\dvirl\OneDrive\Desktop\gitea\invy
```

### 2. Database Setup

Install PostgreSQL and create a database:

```sql
CREATE DATABASE wedding_guests;
```

### 3. Backend Setup

```bash
cd backend

# Create virtual environment (optional but recommended)
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
copy .env.example .env
```

Edit the `.env` file with your database credentials:

```env
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/wedding_guests
```

### 4. Frontend Setup

```bash
cd frontend

# Install dependencies
npm install
```

### 5. Google OAuth Setup (Optional - for contact import)

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Google People API**
4. Create OAuth 2.0 credentials:
   - Application type: Web application
   - Authorized JavaScript origins: `http://localhost:5173`
   - Authorized redirect URIs: `http://localhost:5173`
5. Copy the Client ID
6. Update `GOOGLE_CLIENT_ID` in `frontend/src/components/GoogleImport.jsx`

## 🎯 Running the Application

### Start the Backend Server

```bash
cd backend
uvicorn main:app --reload
```

The API will be available at: `http://localhost:8000`

API documentation: `http://localhost:8000/docs`

### Start the Frontend Development Server

```bash
cd frontend
npm run dev
```

The application will be available at: `http://localhost:5173`

## 📖 API Documentation

Once the backend is running, visit `http://localhost:8000/docs` for interactive API documentation powered by Swagger UI.

### Main Endpoints

- `GET /guests/` - Get all guests
- `POST /guests/` - Create a new guest
- `GET /guests/{guest_id}` - Get a specific guest
- `PUT /guests/{guest_id}` - Update a guest
- `DELETE /guests/{guest_id}` - Delete a guest
- `GET /guests/search/` - Search and filter guests
- `POST /import/google` - Import contacts from Google

## 📱 Usage Guide

### Adding Guests Manually

1. Click the **"+ Add Guest"** button
2. Fill in the guest details:
   - First and last name (required)
   - Email and phone number (optional)
   - RSVP status
   - Meal preference
   - Plus-one information
   - Table number
   - Notes
3. Click **"Add Guest"** to save

### Importing from Google Contacts

1. Click the **"Import from Google"** button
2. Sign in with your Google account
3. Grant permission to access your contacts
4. Contacts will be imported automatically

### Searching and Filtering

Use the search bar and filters to find guests:
- Search by name, email, or phone number
- Filter by RSVP status (pending, accepted, declined)
- Filter by meal preference
- Click **"Clear Filters"** to reset

### Editing and Deleting Guests

- Click **"Edit"** on any guest row to modify their information
- Click **"Delete"** to remove a guest (confirmation required)

## 🗂️ Project Structure

```
wedding-guest-list/
├── backend/
│   ├── main.py              # FastAPI application entry point
│   ├── models.py            # SQLAlchemy database models
│   ├── schemas.py           # Pydantic schemas for validation
│   ├── crud.py              # Database operations
│   ├── database.py          # Database configuration
│   ├── google_contacts.py   # Google API integration
│   ├── requirements.txt     # Python dependencies
│   └── .env.example         # Environment variables template
│
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   │   ├── GuestList.jsx
│   │   │   ├── GuestForm.jsx
│   │   │   ├── SearchFilter.jsx
│   │   │   └── GoogleImport.jsx
│   │   ├── api/            # API client
│   │   │   └── api.js
│   │   ├── App.jsx         # Main app component
│   │   └── main.jsx        # Application entry point
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
│
└── README.md
```

## 🔒 Security Notes

- Never commit your `.env` file or Google OAuth credentials
- Use environment variables for sensitive data
- In production, use HTTPS for all communications
- Implement proper authentication and authorization
- Validate all user inputs on both frontend and backend

## 🚀 Deployment

### Backend Deployment

Consider deploying to:
- **Heroku** (with PostgreSQL add-on)
- **Railway**
- **Render**
- **AWS EC2 + RDS**

### Frontend Deployment

Consider deploying to:
- **Vercel**
- **Netlify**
- **GitHub Pages**

Don't forget to update:
- API base URL in `frontend/src/api/api.js`
- CORS settings in `backend/main.py`
- Google OAuth redirect URIs

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest new features
- Submit pull requests

## 📝 License

This project is open source and available under the MIT License.

## 💡 Tips

- Regularly backup your database
- Test the Google import feature with a test account first
- Use the table assignment feature to organize seating
- Export guest data before the wedding day
- Keep track of dietary restrictions for catering

## 🆘 Troubleshooting

### Database Connection Issues
- Verify PostgreSQL is running
- Check database credentials in `.env`
- Ensure the database exists

### Google Import Not Working
- Verify OAuth credentials are correct
- Check that Google People API is enabled
- Ensure redirect URI matches exactly

### Frontend Can't Connect to Backend
- Verify backend is running on port 8000
- Check CORS settings in `backend/main.py`
- Ensure API URL is correct in `frontend/src/api/api.js`

## 📞 Support

For questions or issues, please open an issue on the GitHub repository.

---

Made with ❤️ for your special day!