Wave-to-Meet Quick Start Guide

Get the Wave-to-Meet feature running locally in 5 minutes.

---

Prerequisites

• Node.js 16+ installed
• Code editor (VS Code recommended)
• Terminal access

---

Setup

1. Install Dependencies

cd /home/mechelle/repos/lantern_app
npm install

2. Start Development Server

npm run dev

Server starts at http://localhost:5173

---

Testing the Feature

Option A: Interactive Demo (Recommended)

1. Open the app in your browser

2. Simulate a wave:

   • Look for the purple "Simulate Wave" button in the top-right corner
   • Click it to trigger an incoming wave notification

3. Accept the wave:

   • Wave notification appears at bottom of screen
   • Click "Accept" button
   • Connection is created

4. Open chat:

   • Click "Open Chat" button on the accepted wave
   • Full-screen chat interface opens
   • Type a message and press Send

5. Activate beacon:

   • Click "Hold Up Lantern to Meet" button
   • Full-screen color beacon activates
   • Color pulses and glows

6. Test different colors:

   • Close beacon (X button)
   • Decline the wave
   • Simulate another wave
   • Accept it (gets random color)
   • Repeat to see all 5 colors

---

Option B: Storybook

npm run storybook

Browse components:

• Components > WaveManager: Wave notification states
• Components > Chat: Chat interface with messages
• Components > LanternBeacon: All 5 color variants

---

File Structure

src/
├── components/
│   ├── WaveManager.jsx         # Wave notifications
│   ├── WaveManager.stories.jsx
│   ├── Chat.jsx                # Anonymous chat
│   ├── Chat.stories.jsx
│   ├── LanternBeacon.jsx       # Color beacon
│   └── LanternBeacon.stories.jsx
│
├── dashboard/
│   └── Dashboard.jsx           # Main app (integrates wave flow)
│
└── App.jsx                     # Root component

docs/
├── features/
│   └── wave/
│       ├── WAVE_TO_MEET.md            # Complete feature docs
│       ├── FEATURE_SUMMARY.md         # Implementation summary
│       ├── BEACON_COLORS.md           # Color reference
│       └── WAVE_QUICK_START.md        # This guide
└── engineering/
   └── API.md                        # Backend endpoints (updated)

---

Key Functions to Know

In Dashboard.jsx

Send a wave:

handleSendWave(lanternId)
// TODO: POST to /api/waves

Accept a wave:

handleAcceptWave(waveId)
// Generates random color
// Creates connection
// TODO: POST to /api/waves/:id/accept

Open chat:

handleOpenChat(connectionId)
// Sets activeChat state
// Renders Chat component

Activate beacon:

handleHoldUpLantern()
// Sets showBeacon to true
// Renders LanternBeacon component

---

Simulating Backend Responses

The feature is currently frontend-only with stubbed data. To connect to a real backend:

1. Update Wave Sending

In Dashboard.jsx, replace:

console.log('Wave sent to lantern:', lanternId)

With:

await fetch('/api/waves', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ targetLanternId: lanternId, senderLanternId: myLantern.id })
})

2. Add WebSocket for Real-time Waves

useEffect(() => {
  const ws = new WebSocket('ws://localhost:3000/ws/waves')
  
  ws.onmessage = (event) => {
    const data = JSON.parse(event.data)
    if (data.type === 'wave_received') {
      setIncomingWaves([...incomingWaves, data.wave])
    }
  }

  return () => ws.close()
}, [])

3. Update Chat Messages

In Chat.jsx, replace the TODO with:

await fetch('/api/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ connectionId: connection.id, text: message, timestamp: new Date() })
})

---

Troubleshooting

Wave button doesn't work

• Check browser console for errors
• Verify onWave prop is passed to VenueView component
• Ensure handleSendWave is defined in Dashboard

Chat doesn't open after accepting wave

• Verify activeChat state is set correctly
• Check that Chat component is rendered conditionally
• Inspect React DevTools for state changes

Beacon doesn't show matching color

• Verify matchColor is in the connection object
• Check that showBeacon state is true
• Try different colors in Storybook to isolate issue

"Simulate Wave" button not appearing

• Only shows in development mode (NODE_ENV === 'development')
• Check that dev server is running (not production build)

---

Next Steps

1. Review Documentation:

   • WAVE_TO_MEET.md - Full feature specs
   • API.md - Backend endpoint requirements
   • BEACON_COLORS.md - Color reference

2. Backend Integration:

   • Implement WebSocket server for real-time notifications
   • Create REST endpoints for waves, connections, messages
   • Add geofencing validation

3. Testing:

   • Write unit tests for wave acceptance logic
   • Test color synchronization across devices
   • Validate rate limiting

4. Deploy:

   • Remove "Simulate Wave" button
   • Build production bundle: npm run build
   • Deploy with your hosting provider

---

Questions?

• GitHub Issues: Open an issue
• Documentation: DOCS_INDEX.md
• Contributing: docs/CONTRIBUTING.md

Happy coding! 🏮