invy/QUICKSTART.md

# Quick Start Guide - Multi-Event System

## 5-Minute Setup

### 1. Database Setup

```bash
# Connect to PostgreSQL
psql -U wedding_admin -d wedding_guests

# Run migrations to create new tables
\i backend/migrations.sql

# Verify tables created
\dt
# Should show: users, events, event_members, guests_v2, (and old guests)
```

### 2. Environment Configuration

Copy and update `.env`:
```bash
cp backend/.env.example backend/.env
```

For **local development**, keep defaults. For **WhatsApp messaging**, add:
```env
WHATSAPP_ACCESS_TOKEN=your_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_id_here
```

### 3. Start Backend

```bash
cd backend
pip install -r requirements.txt
python -m uvicorn main:app --reload
# API: http://localhost:8000
# Docs: http://localhost:8000/docs
```

### 4. Start Frontend

```bash
cd frontend
npm install
npm run dev
# App: http://localhost:5173
```

## Key Differences from Old System

### Old Workflow
```
Login → See all guests → Add guest → Manage guests
```

### New Workflow
```
Login → See my events → Create/select event → Manage guests for that event
```

## Basic Usage

### 1. Create an Event
- Click "New Event" button
- Fill: Name (required), Date, Location
- Click Create → Automatically added as admin

### 2. Invite Team Members
- On event page, click "Members"
- Enter email, select role (admin/editor/viewer), click Invite
- Member gets access once they log in

### 3. Add Guests
- Click "Add Guest" button
- Enter: First name, Last name, Phone, Side (optional), Notes
- Status auto-set to "invited"

### 4. Filter Guests
- **Search**: By name or phone
- **Status**: Show invited/confirmed/declined
- **Side**: Group by side (e.g., "groom side")
- **Added by me**: Show only guests you added

### 5. Send WhatsApp Messages (if configured)
- Click guest → "Send WhatsApp"
- Message auto-filled with phone number
- Click Send (requires WhatsApp API credentials)

## API Reference (Most Common)

### Get Your Events
```bash
GET http://localhost:8000/events
# Returns: [
#   { id: "uuid", name: "Wedding", date: "...", location: "..." },
#   { id: "uuid", name: "Party", date: "...", location: "..." }
# ]
```

### Get Guests for Event
```bash
GET http://localhost:8000/events/{event_id}/guests?status=confirmed
# Returns: [
#   { id: "uuid", first_name: "John", last_name: "Doe", phone: "+1...", status: "confirmed" }
# ]
```

### Create Guest
```bash
POST http://localhost:8000/events/{event_id}/guests
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1-555-123-4567",
  "side": "groom side",
  "status": "invited"
}
```

### Bulk Import Guests
```bash
POST http://localhost:8000/events/{event_id}/guests/import
Content-Type: application/json

{
  "guests": [
    { "first_name": "John", "last_name": "Doe", "phone": "+1-555-0001" },
    { "first_name": "Jane", "last_name": "Smith", "phone": "+1-555-0002" }
  ]
}
```

### Send WhatsApp Message
```bash
POST http://localhost:8000/events/{event_id}/guests/{guest_id}/whatsapp
Content-Type: application/json

{
  "message": "Hi! Please confirm your attendance"
}
```

See full API docs at `http://localhost:8000/docs` when running backend.

## Authentication (TODO)

Currently uses `TEST_USER_EMAIL` from `.env` (hardcoded for testing).

**To implement real auth**, edit `main.py`:

```python
def get_current_user_id() -> UUID:
    # Replace this placeholder with real auth
    # Extract from JWT token, session, etc.
    # Return actual user UUID
    pass
```

Examples using FastAPI utilities:
```python
from fastapi import Depends
from fastapi.security import HTTPBearer, HTTPAuthCredentials

security = HTTPBearer()

def get_current_user_id(credentials: HTTPAuthCredentials = Depends(security)) -> UUID:
    # Verify JWT token
    payload = jwt.decode(credentials.credentials, SECRET)
    return UUID(payload["sub"])
```

## File Organization

```
backend/
  main.py          ← All API endpoints
  models.py        ← Database models (must match schema)
  schemas.py       ← Request/response validation
  crud.py          ← Database operations
  authz.py         ← Who can do what
  whatsapp.py      ← WhatsApp messaging
  database.py      ← DB connection
  .env             ← Configuration (copy from .env.example)

frontend/src/
  App.jsx          ← Main navigation (events → guests → actions)
  api/api.js       ← HTTP client (all backend calls)
  components/
    EventList.jsx     ← Show/create events
    EventForm.jsx     ← New event modal
    EventMembers.jsx  ← Invite members
    GuestList.jsx     ← Show/edit guests (needs update)
    ...
```

## Common Tasks

### List All Events
Admin can see events on main dashboard. Filter by:
- Own events (events you created)
- Invited to (events others invited you to)

### Add 100 Guests at Once
Use bulk import:
1. Prepare CSV: first_name, last_name, phone, side
2. Convert to JSON
3. POST to `/events/{id}/guests/import`

### Filter by Confirmation Status
```
GET /events/{id}/guests?status=confirmed
GET /events/{id}/guests?status=declined
GET /events/{id}/guests?status=invited
```

### Get Event Statistics
```
GET /events/{id}/stats
# Returns: {
#   "stats": { "total": 100, "confirmed": 75, "declined": 5, "invited": 20 },
#   "sides": [ { "side": "groom", "count": 50 }, { "side": "bride", "count": 50 } ]
# }
```

### Update Guest Status
```
PATCH /events/{id}/guests/{guest_id}
{
  "status": "confirmed",
  "notes": "Confirmed with dietary restriction"
}
```

### Make Someone Event Admin
```
PATCH /events/{id}/members/{user_id}
{
  "role": "admin"
}
```

## Testing Tips

Use REST client or curl:

```bash
# Create event
curl -X POST http://localhost:8000/events \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Event","date":"2026-03-15T18:00:00"}'

# Get events
curl http://localhost:8000/events

# Add guest
EVENT_ID="..." # from previous response
curl -X POST http://localhost:8000/events/$EVENT_ID/guests \
  -H "Content-Type: application/json" \
  -d '{
    "first_name":"John",
    "last_name":"Doe",
    "phone":"+1-555-0001"
  }'

# Get guests
curl http://localhost:8000/events/$EVENT_ID/guests
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Event not found" | Verify event_id UUID is correct, user is member |
| "Not authorized" | User must be event member to access it |
| "Guest not found" | Guest must belong to specified event_id |
| WhatsApp "Invalid phone" | Phone must be in E.164 format (+countrycode...) |
| CORS error | Check FRONTEND_URL in .env matches your frontend |
| 401 Unauthorized | Remove TEST_USER_EMAIL from .env if implementing real auth |

## Next Steps

1. ✅ Understand the event-first architecture
2. ✅ Test creating events and adding guests
3. ⭐ Implement authentication (replace TEST_USER_EMAIL)
4. ⭐ Configure WhatsApp if sending messages
5. ⭐ Update GuestList component for event scope
6. ⭐ Deploy to production

## Help & Documentation

- **Full API Docs**: `http://localhost:8000/docs` (Swagger UI)
- **Database Schema**: See `backend/migrations.sql`
- **Architecture**: Read `REFACTORING_GUIDE.md`
- **Complete Changes**: See `IMPLEMENTATION_SUMMARY.md`
- **API Reference**: Check docstrings in `main.py`

---

**Questions?** Check the inline code comments in `main.py` and reference the REFACTORING_GUIDE for detailed explanations.