Frens System — Privacy-First Reconnection

Date: January 9, 2026 Status: 🚧 Design Phase

Overview

The Frens system enables users to save connections from in-person meetings and reconnect later while maintaining Lantern's core privacy principles.

Core Philosophy

Saving someone = Broadcasting YOUR lantern to THEM

No tracking other people's locations
No stalking possible
Venue-bound, context-preserved connections
Consent-based visibility at every step

How It Works

The Flow

1. Meet at Coffee House → Wave accepted → Chat
2. Option to "Save Connection" (optional for both)
3. If you save them:
   → They can now see YOUR lantern at Coffee House
   → You cannot see theirs (unless they save you back)
4. If they save you back:
   → 🎉 Mutual connection notification
   → Both can see each other at shared venues
5. Meet again at different venue:
   → Option to add that venue to broadcast list
   → Each venue is an intentional choice

Key Principles

1. Venue-Bound Broadcasting

You don't broadcast everywhere—only at specific venues.

You save "Sapphire Crystal" at Coffee House
→ They see your lantern ONLY at Coffee House
→ Not at The Speakeasy, not at The Bar, nowhere else

Later, you both meet at The Speakeasy:
→ Option to "Also broadcast at The Speakeasy?"
→ Each venue is a separate, intentional choice

Why this matters:

Prevents routine tracking (can't see someone's weekly patterns)
Keeps connections context-specific ("we're Coffee House people")
You control exactly which slices of your social life are visible

2. Asymmetric Visibility

Visibility is reciprocal to the save action, not symmetric.

State	You See Them	They See You
Neither saved	❌	❌
You saved them	❌	✅ (at broadcast venues)
They saved you	✅ (at broadcast venues)	❌
Mutual save	✅ (at shared venues)	✅ (at shared venues)

Why asymmetric?

You're broadcasting TO them, not tracking them
Like saying "if you want to find me again, here's my signal"
No surveillance possible

3. No Persistent Chat

Chat is only available when both users are at venues with lit lanterns.

✅ Chat available when:
   - Both at same venue with lanterns lit
   - Both at any venue (if mutual frens at that venue)
   - 2-hour window after meeting (logistics only)

❌ Chat NOT available:
   - When either person isn't at a venue
   - Outside the 2-hour post-meetup window

Alternative: Beacon Invites

"I'll be at Coffee House Thursday 7pm"
One-way notification, no back-and-forth
Shows intent without creating inbox burden

Data Model

Connection Document

javascript

// Firestore: connections/{connectionId}
{
  connectionId: "abc123",
  user1Id: "user123",
  user2Id: "user456",
  
  // Where each user broadcasts their lantern
  user1Broadcasts: [
    {
      venueId: "coffee-house",
      venueName: "Coffee House",
      addedDate: "2026-01-09T10:30:00Z"
    },
    {
      venueId: "the-speakeasy",
      venueName: "The Speakeasy",
      addedDate: "2026-01-15T19:00:00Z"
    }
  ],
  
  user2Broadcasts: [
    {
      venueId: "coffee-house",
      venueName: "Coffee House",
      addedDate: "2026-01-09T11:00:00Z"
    }
  ],
  
  // Connection metadata
  metAt: "Coffee House",
  metDate: "2026-01-09T10:30:00Z",
  
  // User info (cached from profile)
  user1LanternName: "Amber Beacon",
  user1Interests: ["Jazz", "Coffee", "Art"],
  user2LanternName: "Sapphire Crystal",
  user2Interests: ["Coffee", "Books", "Late Night"],
  
  // Computed fields (set via cloud function)
  mutualVenues: ["coffee-house"], // Venues both broadcast at
  isMutual: true,
  
  // Timestamps
  createdAt: "2026-01-09T10:30:00Z",
  updatedAt: "2026-01-15T19:00:00Z"
}

Querying Frens with Lit Lanterns

javascript

// Get my frens who are currently lit at venues I broadcast to them
const myConnections = await db.collection('connections')
  .where('user1Id', '==', currentUserId)
  .where('user1Broadcasts', 'array-contains-any', myCurrentVenues)
  .get();

// Then cross-reference with active lanterns
const activeFrenIds = myConnections.docs.map(doc => doc.data().user2Id);
const activeLanterns = await db.collection('lanterns')
  .where('userId', 'in', activeFrenIds)
  .where('isLit', '==', true)
  .where('venueId', 'in', broadcastVenueIds) // Only venues they broadcast to me
  .get();

User Flows

Flow 1: Save Someone (One-Way)

User A and User B meet at Coffee House
↓
User A accepts wave from User B
↓
After chatting:
┌─────────────────────────────────┐
│ Save Sapphire Crystal?          │
│ ────────────────────────────────│
│ They'll be able to see when you │
│ light your lantern at Coffee    │
│ House                            │
│                                  │
│ [Maybe Later] [Save Fren]        │
└─────────────────────────────────┘
↓
User A taps [Save Fren]
↓
Connection created with:
- user1Id: User A
- user2Id: User B
- user1Broadcasts: [Coffee House]
- user2Broadcasts: [] (empty)
↓
User B sees nothing (no notification)
↓
Next time User A lights lantern at Coffee House:
User B sees "Amber Beacon is at Coffee House"

Result:

User A is broadcasting to User B
User B can see User A's lantern at Coffee House
User A cannot see User B's lantern anywhere
No notification sent to User B

Flow 2: Mutual Save

Same as Flow 1, but User B also saves User A
↓
When User B saves User A:
System detects mutual save
↓
Both users get notification:
┌─────────────────────────────────┐
│ 🎉 Mutual Connection!            │
│ ────────────────────────────────│
│ Sapphire Crystal saved you too!  │
│                                  │
│ You can now see each other when │
│ lanterns are lit at Coffee House │
│                                  │
│ [View Frens]                     │
└─────────────────────────────────┘

Result:

Both broadcasting at Coffee House
Both can see each other's lanterns there
Priority wave option
Still can't see each other at other venues

Flow 3: Expanding to New Venue

User A and User B (mutual frens) both happen to be at The Speakeasy
↓
Both see each other in normal lantern feed (not as frens)
↓
System shows prompt:
┌─────────────────────────────────┐
│ Sapphire Crystal is here!       │
│─────────────────────────────────│
│ You're mutual frens from        │
│ Coffee House                     │
│                                  │
│ Also broadcast at The Speakeasy?│
│ [No thanks] [Add Venue]          │
└─────────────────────────────────┘
↓
If User A taps [Add Venue]:
→ User B can now see User A at The Speakeasy
→ User A still can't see User B there (until they also add venue)
↓
If User B also adds venue:
→ Both can now see each other at Coffee House AND The Speakeasy

UI Components

1. SaveConnectionPrompt

Purpose: Modal shown after chatting to save a connection

Triggers:

After accepting wave and chatting
Manual "Save Connection" button in chat
Post-meetup (2-hour window)

States:

Default: Explain venue-bound broadcasting
Success: Confirmation message
Already saved: "You've already saved this person"

Location: src/components/SaveConnectionPrompt.jsx

2. FrensList

Purpose: Main frens screen showing all connections

Sections:

Header: Total frens count, filter/search
Lit Now: Mutual frens with active lanterns (prioritized)
Broadcasting To: One-way saves (you broadcast to them)
Receiving From: People who broadcast to you (mutual section)
Inactive: Mutual frens not currently lit

Features:

Real-time updates when frens light lanterns
Venue context for each fren
Quick wave action
Badge showing lantern status (lit/not lit)

Location: src/screens/frens/FrensList.jsx

3. FrenProfile

Purpose: Detailed view of a single fren

Shows:

Lantern name and interests
Where you met (original venue)
Shared venues (if mutual)
Current lantern status
Broadcast venues management

Actions:

Wave (if currently lit)
Manage venues
Send beacon invite
Remove connection

Location: src/screens/frens/FrenProfile.jsx

4. ManageVenuesModal

Purpose: Choose which venues you broadcast to for this fren

Features:

List of all venues where you've both been
Checkboxes to enable/disable broadcasting
Add new venues (only after both present there)
Explanation of what broadcasting means

Location: src/components/ManageVenuesModal.jsx

Privacy & Safety Features

✅ What's Protected

No Location Tracking
- Only see lanterns at venues you both broadcast at
- No GPS coordinates ever shared
- Can't build profile of someone's routines
Consent at Every Level
- Save = "I consent to broadcast to you"
- Venue-by-venue opt-in
- Can remove venues or entire connection anytime
No Stalking
- Can't see where someone is unless they broadcast there
- Can't see when they were last active (except at shared venues)
- No "last seen" timestamps outside context
Ephemeral Chat
- Messages only at venues
- No persistent inbox
- Natural boundaries

⚠️ Potential Issues

User Confusion
- "Why can't I see my fren?" → They haven't saved you back
- Solution: Clear onboarding and UI messaging
Asymmetric Expectations
- One person thinks it's mutual, other hasn't saved them
- Solution: Show broadcasting status clearly
Venue Spam
- Users adding every venue "just in case"
- Solution: Prompt only when both actually present
- Encourage intentional venue selection

Implementation Phases

Phase 1: Core UI (Frontend Only) ✅ This PR

SaveConnectionPrompt component
FrensList screen
FrenProfile screen
ManageVenuesModal component
Storybook stories
Mock data integration
Routing setup

Phase 2: Firebase Integration

Firestore connection schema
Real-time lantern queries
Cloud Functions for mutual detection
Notification system

Phase 3: Beacon Invites

Invite creation UI
Notification delivery
Calendar integration

Track save rates
Monitor venue expansion patterns
A/B test messaging
User feedback integration

Open Questions

Should we limit number of frens?
- Pro: Keeps connections meaningful
- Con: Arbitrary limit feels restrictive
- Proposal: Soft limit with warning ("You have 50+ frens. Consider quality over quantity")
What if someone never saves you back?
- Current: You can still broadcast to them forever
- Alternative: Auto-expire after 30 days of no mutual save?
- Proposal: Keep forever but show "Not mutual" status clearly
Venue expansion prompts timing?
- Current: Immediate when both at new venue
- Alternative: After 2nd or 3rd co-presence?
- Proposal: Immediate with explanation of intentionality
Can you remove individual venues?
- Current: Yes, manage anytime
- Alternative: Can only remove if not mutually broadcasting?
- Proposal: Full control, but show warning if removing mutual venue

Success Metrics

User Engagement

% of wave acceptances that lead to saves
Average number of frens per user
Average number of shared venues per mutual connection
Reconnection rate (met again after 7+ days)

Privacy Health

% of users with >10 broadcast venues (spam indicator)
Venue expansion rate (how fast people add venues)
Connection removal rate

Feature Adoption

% of users with at least 1 fren
% of users with at least 1 mutual fren
Frens feature DAU/MAU ratio

Technical Notes

Real-Time Updates

Frens list must update in real-time when:

A fren lights their lantern at a broadcast venue
A fren extinguishes their lantern
A mutual save occurs
A venue is added/removed

Use Firestore listeners for efficiency:

javascript

// Listen to connections where I broadcast
db.collection('connections')
  .where('user1Id', '==', currentUserId)
  .onSnapshot(snapshot => {
    // Update frens list
  });

// Listen to active lanterns from my frens
db.collection('lanterns')
  .where('userId', 'in', myFrenIds)
  .where('isLit', '==', true)
  .onSnapshot(snapshot => {
    // Update lit status in real-time
  });

Performance Considerations

Cache lantern names and interests in connection doc (avoid extra reads)
Use compound queries for efficient filtering
Limit real-time listeners to active frens only
Paginate frens list if >50 connections

Next Steps:

Build component scaffolding with mock data
Create Storybook stories for all states
User test with pilot group
Iterate based on feedback
Implement Firebase backend

Frens System — Privacy-First Reconnection ​

Overview ​

Core Philosophy ​

How It Works ​

The Flow ​

Key Principles ​

1. Venue-Bound Broadcasting ​

2. Asymmetric Visibility ​

3. No Persistent Chat ​

Data Model ​

Connection Document ​

Querying Frens with Lit Lanterns ​

User Flows ​

Flow 1: Save Someone (One-Way) ​

Flow 2: Mutual Save ​

Flow 3: Expanding to New Venue ​

UI Components ​

1. SaveConnectionPrompt ​

2. FrensList ​

3. FrenProfile ​

4. ManageVenuesModal ​

Privacy & Safety Features ​

✅ What's Protected ​

⚠️ Potential Issues ​

Implementation Phases ​

Phase 1: Core UI (Frontend Only) ✅ This PR ​

Phase 2: Firebase Integration ​

Phase 3: Beacon Invites ​

Phase 4: Analytics & Refinement ​

Open Questions ​

Success Metrics ​

User Engagement ​

Privacy Health ​

Feature Adoption ​

Related Documentation ​

Technical Notes ​

Real-Time Updates ​

Performance Considerations ​

Frens System — Privacy-First Reconnection

Overview

Core Philosophy

How It Works

The Flow

Key Principles

1. Venue-Bound Broadcasting

2. Asymmetric Visibility

3. No Persistent Chat

Data Model

Connection Document

Querying Frens with Lit Lanterns

User Flows

Flow 1: Save Someone (One-Way)

Flow 2: Mutual Save

Flow 3: Expanding to New Venue

UI Components

1. SaveConnectionPrompt

2. FrensList

3. FrenProfile

4. ManageVenuesModal

Privacy & Safety Features

✅ What's Protected

⚠️ Potential Issues

Implementation Phases

Phase 1: Core UI (Frontend Only) ✅ This PR

Phase 2: Firebase Integration

Phase 3: Beacon Invites

Phase 4: Analytics & Refinement

Open Questions

Success Metrics

User Engagement

Privacy Health

Feature Adoption

Related Documentation

Technical Notes

Real-Time Updates

Performance Considerations