Lantern

Appearance

Wave Integration - Implementation Summary ​

Date: January 7, 2026
Status: ✅ Complete

What Was Done ​

1. Fixed Venue User Tracking Issue ​

Problem: Venue counters showed active lanterns but clicking into venue showed empty list.

Solution: Updated handleSelectVenue() in Dashboard.jsx to call getVenueLanterns() when opening a venue, populating venue.activeLanterns with real Firestore data.

Files Changed:

2. Created Wave Service ​

New File: src/lib/waveService.js

Functions:

  • sendWave(senderUserId, senderLanternId, recipientLanternId) - Send wave to another user
  • acceptWave(waveId, userId) - Accept wave and create connection
  • declineWave(waveId, userId) - Decline wave
  • getIncomingWaves(userId) - Fetch pending waves
  • getActiveConnections(userId) - Fetch active connections
  • subscribeToIncomingWaves(userId, callback) - Real-time wave notifications
  • subscribeToActiveConnections(userId, callback) - Real-time connection updates
  • formatWaveForDisplay(wave) - Format wave for UI display

Data Models:

javascript
// Wave document (waves collection)
{
  senderUserId, senderLanternId,
  recipientUserId, recipientLanternId,
  venueId, venueName,
  status: 'pending' | 'accepted' | 'declined' | 'expired',
  interest, mood,
  sentAt, expiresAt (1 hour),
  matchColor?, connectionId?
}

// Connection document (connections collection)
{
  waveId, user1Id, user2Id,
  venueId, venueName,
  matchColor, interest, mood,
  createdAt, expiresAt (4 hours),
  status: 'active' | 'met' | 'expired'
}

3. Integrated Real Firebase Calls ​

Updated Functions in Dashboard.jsx:

handleSendWave(lanternId) - Now calls sendWave() with Firebase

javascript
await sendWave(currentUser.uid, myLantern.id, lanternId)

handleAcceptWave(waveId) - Calls acceptWave() and opens chat

javascript
const result = await acceptWave(waveId, currentUser.uid)
setActiveChat(result.connection)

handleDeclineWave(waveId) - Calls declineWave()

javascript
await declineWave(waveId, currentUser.uid)

4. Added Real-Time Listeners ​

Updated useEffect hook to subscribe to:

  1. Active lanterns (existing)
  2. Incoming waves (new) - Auto-updates when someone waves at you
  3. Active connections (new) - Auto-updates when wave accepted

All listeners clean up on unmount.

5. Updated Firestore Security Rules ​

Added rules for:

  • waves collection - Users can create, read their own, recipients can update
  • connections collection - Both users can read/update, system creates

File: firestore.rules

6. Created Testing Documentation ​

New File: docs/features/wave/WAVE_TESTING_GUIDE.md

Comprehensive guide for:

  • Setting up test accounts
  • Creating required Firestore indexes
  • Step-by-step testing workflow
  • Troubleshooting common issues
  • Data model reference

How It Works ​

User Flow ​

┌─────────────────────────────────────────────────────────┐
│ 1. Both users light lanterns at same venue              │
│    → Firestore creates lantern documents                │
│    → Venue counter increments                           │
│    → Both see each other in venue view                  │
└─────────────────────────────────────────────────────────┘
                           │
                           v
┌─────────────────────────────────────────────────────────┐
│ 2. User A sends wave to User B's lantern                │
│    → Dashboard calls sendWave()                         │
│    → Firestore creates wave document                    │
│    → Wave status: 'pending'                             │
└─────────────────────────────────────────────────────────┘
                           │
                           v
┌─────────────────────────────────────────────────────────┐
│ 3. User B receives wave notification (real-time)        │
│    → subscribeToIncomingWaves() fires callback          │
│    → WaveManager shows notification at bottom           │
│    → User B can accept or decline                       │
└─────────────────────────────────────────────────────────┘
                           │
                           v
┌─────────────────────────────────────────────────────────┐
│ 4. User B accepts wave                                  │
│    → Dashboard calls acceptWave()                       │
│    → Firestore creates connection document              │
│    → Random color generated (amber/purple/blue/etc)     │
│    → Chat opens automatically                           │
│    → Both users can now chat and beacon                 │
└─────────────────────────────────────────────────────────┘

Real-Time Updates ​

All updates happen automatically via Firestore listeners:

  • Waves: When someone waves at you, notification appears instantly
  • Connections: When wave accepted, both users get connection
  • Lanterns: When user lights/extinguishes, venue counts update

No page refresh needed!

Required Setup ​

1. Deploy Firestore Rules ​

bash
npm run deploy:rules

Or manually deploy via Firebase Console.

2. Create Firestore Indexes ​

Firebase will prompt you with direct links when you first run queries. Click the links to create indexes automatically.

Alternatively, create manually in Firebase Console > Firestore > Indexes:

Required Indexes:

  • waves: (recipientUserId, status, sentAt)
  • waves: (senderUserId, recipientUserId, status)
  • connections: (user1Id, status)
  • connections: (user2Id, status)
  • lanterns: (venueId, status, litAt)
  • lanterns: (userId, venueId, status)

See WAVE_TESTING_GUIDE.md for details.

Testing Checklist ​

To verify wave integration works:

  • [ ] Deploy Firestore rules
  • [ ] Create required indexes
  • [ ] Two users light lanterns at same venue
  • [ ] Each user sees other's lantern in venue view
  • [ ] User A sends wave to User B
  • [ ] User B receives wave notification (real-time)
  • [ ] User B accepts wave
  • [ ] Chat opens automatically
  • [ ] Both users can send messages
  • [ ] Both users activate beacon with matching color
  • [ ] Connection persists after closing chat
  • [ ] Declining wave removes notification
  • [ ] Waves expire after 1 hour
  • [ ] Connections expire after 4 hours

What's Still Stubbed ​

The following features use mock data and need backend integration:

Chat Messages ​

  • Currently stored in component state only
  • Messages don't persist or sync between users
  • Next step: Create chatService.js with Firestore messages collection

Scheduled Lanterns ​

  • Form exists but doesn't save to Firestore
  • No scheduled execution
  • Next step: Add scheduledLanterns collection + Cloud Function for auto-lighting

Merchant Offers ​

  • Mock data in MOCK_OFFERS constant
  • Next step: Create offersService.js and offers collection

Files Changed ​

New Files ​

Modified Files ​

  • src/screens/dashboard/Dashboard.jsx
    • Added getVenueLanterns to populate venue users
    • Integrated sendWave, acceptWave, declineWave
    • Added real-time listeners for waves and connections
  • firestore.rules
    • Added waves collection rules
    • Added connections collection rules

Performance Considerations ​

Query Optimization ​

  • All queries use composite indexes for fast lookups
  • Real-time listeners are scoped to current user only
  • Expired waves/connections auto-filtered client-side

Connection Management ​

  • Listeners clean up on component unmount
  • Only active waves/connections loaded (status filtering)
  • Venue lanterns fetched on-demand (not subscribed globally)

Future Optimizations ​

  • Add pagination for large wave/connection lists
  • Implement Cloud Functions to auto-expire old documents
  • Use Firestore TTL (when available) for automatic cleanup

Security ​

Authentication ​

  • All wave operations require auth.uid
  • Can only send waves from own lanterns
  • Can only accept/decline waves sent to you

Authorization ​

  • Firestore rules enforce sender/recipient checks
  • Cannot modify other users' waves
  • Cannot access waves not involving you

Data Privacy ​

  • Lantern interests visible only to users at same venue
  • No user photos or real names exposed
  • Connections are ephemeral (4-hour expiry)

Next Steps ​

  1. Test with two devices - Follow WAVE_TESTING_GUIDE.md
  2. Implement chat persistence - Create chatService.js
  3. Add push notifications - Firebase Cloud Messaging for wave alerts
  4. Implement "Mark as Met" - Update connection status when users meet
  5. Add wave history - Show past waves in activity feed

Questions? ​

See:

Congratulations! 🎉 Waves are now live with real Firebase integration. Users can discover each other, send waves, accept connections, and chat—all in real-time!

Built with VitePress

Copyright © 2026 Lantern