invy/QUICKSTART.md

Quick Start Guide - Multi-Event System

5-Minute Setup

1. Database Setup

# 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:

cp backend/.env.example backend/.env

For local development, keep defaults. For WhatsApp messaging, add:

WHATSAPP_ACCESS_TOKEN=your_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_id_here

3. Start Backend

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

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

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

Get Guests for Event

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

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

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

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:

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:

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:

# 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.