Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[DEV] - 2026-01-11

Fixed

• Fix Discord notifications to show all commits when multiple commits are pushed at once
  • Previously only showed most recent commit (github.event.head_commit)
  • Now iterates through github.event.commits array to display all commits
  • Each commit shown with its own author, SHA (shortened), and message
  • Notification title shows commit count (e.g., "3 commits")
  • Commits separated by horizontal rules for clarity

Added

• Add on-demand venue refresh strategy based on location staleness

  • New src/lib/venueRefreshService.js tracks refresh metadata per geographic area
  • getNearbyVenues() checks area staleness (30-day and 90-day thresholds) before querying
  • Very stale (>90 days) or new areas: blocks and waits for refresh with friendly loading message
  • Moderately stale (30-90 days): returns cached data immediately + background refresh
  • Fresh areas (<30 days): returns cached data only
  • Firestore venueRefreshMetadata collection tracks lastRefreshedAt by geohash prefix
  • Cloud Function placeholder for production refresh triggers (manual script for now)

• Add OSM venue import script for automated platform seeding

• Add venue details panel in app

  • Show address, hours, phone, website, cuisine, accessibility, dietary options, social links in Venue view
  • Keeps merchant-customized fields intact and surfaces imported details when present

• Add OSM venue import script for automated platform seeding

  • Import script queries Overpass API (OpenStreetMap) for businesses in geographic area in scripts/import-venues-osm.mjs
  • Normalizes OSM data to venue format with geohash, deduplicates by osmId, batch writes to Firestore
  • Updates existing venues with new fields while preserving merchant-customized data
  • Batches duplicate checks in groups of 10 (Firestore in query limit)
  • Add interim consolidation: merge duplicate venue documents by osmId within the imported area, preserve merchant fields, delete redundant docs (--consolidate flag)
  • Captures comprehensive venue details: hours, cuisine, accessibility, social links, dietary options, amenities
  • Supports dry-run mode and configurable center/radius/limit via CLI args
  • Free alternative to Google Places for initial platform population
  • Run via npm run import:venues:osm -- --lat=32.7157 --lng=-117.1611 --radius=5000

• Add location stack and geofencing helpers

  • Store geohash on venue create/update and query via geohash bounds with fallback distance filtering in src/lib/venueService.js
  • Normalize Google Places onboarding payloads and Firestore writes via src/lib/placesService.js
  • Add backfill script for legacy venues and npm script hook in scripts/backfill-geohash.mjs
  • Document stack, fallbacks, and onboarding flow in docs/engineering/architecture/LOCATION_STACK.md and surface in docs/DOCS_INDEX.md

• Add Firestore emulator config (optional; dev database recommended for testing)

  • New firebase.json with local emulator host/port
  • Default project alias in .firebaserc
  • Note: Use dev Firestore (lantern-app-dev) for testing; emulator not required

• Add comprehensive database scaling strategy documentation

  • Document Firestore vs Realtime Database decision rationale
  • Include scale limits, cost projections, and migration triggers
  • Add Google Maps API cost analysis and caching strategies
  • Define geofencing implementation with geohash-based proximity queries
  • Establish GCP migration path for Year 3-5 scaling
  • See DATABASE_SCALING.md

Fixed

• Fix "Nearby Vibes" banner persisting after clicking X to dismiss
  • Added localStorage persistence to remember dismissed state
  • Banner now stays hidden across page refreshes and navigation
  • Uses nearbyVibesBannerDismissed localStorage key

Added

• Add lantern counter to venue offers showing social proof of engagement
  • Display "X lanterns lit since launch" on venue detail offer cards
  • Counter appears below incentive badge where distance would normally be
  • Mock offers generate realistic counts based on offer age (2-5 per day)
  • Fake offers generate counts based on hours since creation (0.5 per hour)
  • Provides social proof and ties offers to core lantern-lighting mechanic
  • Creates FOMO and demonstrates merchant value (foot traffic tracking)
• Add "While supplies last" disclaimer option to merchant offer creation
  • Checkbox in fake ad creation form to enable/disable disclaimer
  • Displays "* While supplies last" text on offer cards when enabled
  • Helps manage user expectations for limited-inventory offers
  • Disclaimer shown in both hero offer cards and inline venue offer pills

Fixed

• Fix preset button hover behavior in calculator components (removed vertical shift that caused buttons to appear to disappear on hover)
  • Updated PilotCalculator, UnitEconomicsCalculator, FundAllocationCalculator, SalaryCalculator Vue components
  • Removed transform: translateY(-2px) in favor of stable box-shadow effect
• Remove broken financial calculator link from documentation index (linking to non-existent CALCULATOR.md)

Fixed

• Rename adService.js to offerService.js to prevent ad blocker interference
  • Ad blockers (uBlock Origin, etc.) were blocking files with "ad" in the filename
  • Updated all imports and function names to use "offer" terminology
  • Functions: getHeroOffer(), getVenueOffer(), getOffersByVenue(), setMerchantFakeOffers()
• Fix fake offers not appearing in dashboard by tying them to actual loaded venues
  • Offer service now accepts venues parameter to match real venue IDs
  • Mock offers use first 3 loaded venues instead of hardcoded IDs
  • Fake offers assigned higher priority (20+) to appear before mock offers

Changed

• Add venue selector to merchant fake offer creation form
  • Merchant dashboard now loads nearby venues on mount (dev only)
  • Dropdown shows all available venues with category labels
  • Form requires venue selection before offer can be created
  • Fake offer display shows associated venue name
  • Ensures offers appear on correct venue cards in user dashboard

Added

• Add fake ads creation feature to merchant dashboard (dev and local environments only)
  • Create, view, and delete simulated ad campaigns with realistic metrics
  • Form includes title, description, placement, target audience, and budget fields
  • Auto-generated impressions, clicks, and spend data for testing
  • Purple-themed UI to distinguish from production features
  • Uses same environment detection pattern as simulate wave feature
• Add centralized offer service for managing merchant offers and ad placements
  • New offerService.js provides unified API for hero offers, inline offers, and venue-specific promotions
  • Supports merging mock offers with merchant-created fake offers in dev environments
  • Ad-blocker safe naming convention (uses "offer" instead of "ad")
• Integrate offer placements into user-facing dashboard views
  • Hero offer card displays on main dashboard (highest priority active offer)
  • Inline venue offers show on individual venue detail screens
  • Merchant fake offers automatically sync and appear in user views (dev only)
  • Visual distinction for test offers with purple "TEST" badge
  • Amber-themed gradient cards for offer displays with "Learn more" CTAs
• Mark Frens system scaffolding as complete across documentation (UI and components fully built, backend integration pending)
• Comprehensive Plan of Action for January 2026 cofounder feedback in docs/business/COFOUNDER_FEEDBACK_POA.md
  • Strategic analysis of user profile, privacy model, engagement mechanisms, and growth strategy
  • 60+ actionable items organized by priority and timeline
  • Critical decision framework for primary value proposition and privacy approach
  • Sprint planning recommendations for Q1 2026
  • Risk mitigation strategies for marketplace chicken-egg problem
• Comprehensive financial calculator suite with interactive Vue components and documentation
  • Fund Allocation Calculator - Model budget allocation across Four Pillars, safe spaces, profit sharing at any revenue scale
  • Pilot Revenue Calculator - Project 12-month revenue and profitability based on merchant acquisition, churn, and ARPU
  • Unit Economics Calculator - Analyze per-unit profitability (merchant, user, transaction basis)
  • Salary Range Calculator - Design fair compensation with multiplier bands and verify 3× cap compliance
  • All calculators support slider + direct number input for precise adjustments
  • Preset scenarios (Pilot, Growth, Enterprise) for rapid exploration
  • Real-time insights with contextual warnings and success indicators
  • Organized under /docs/economics/financial-calculators/ with detailed guides for each tool
• TODO item to explore a mascot experiment contingent on user sentiment
• Stress test scenario for user-merchant ratio imbalance to economics documentation
  • Cost analysis for 10K+ users with minimal merchant adoption
  • Margin impact calculations at extreme user:merchant ratios
  • Five mitigation strategies including rate limiting, geographic restrictions, and Firebase optimization
  • Automated alert recommendations for user:merchant ratio >5000:1
• Discord webhook notifications for pushes to main and dev branches via GitHub Actions
  • Displays commit message, author, branch, and direct link to commit
  • Color-coded by branch (blue for main, green for dev)
  • Requires DISCORD_WEBHOOK_URL secret configuration

Changed

• Update POA to incorporate cofounder product feedback:
  • Anonymity-first profile (autogenerated username, optional custom), age verification and phone anti-fraud
  • Frens sharing semantics (venue-level presence, optional reciprocity)
  • Venue-based matching default with opt-in individual matching
  • Web notification permission gating and onboarding copy updates
  • SOS safety mechanics and safe-sites partnerships
  • POS-based offer redemption tracking option for Sponsored Nearby
• Harmonize calculator preset button styles across components
  • Use VitePress theme tokens for hover (var(--vp-button-brand-hover-bg)) and active (var(--vp-button-brand-active-bg)) backgrounds
  • Keep lighter hover via filter: brightness(1.08) and transparent borders to avoid layout shifts
• Mark completed items in POA based on current implementation:
  • Mutual-interest matching and minimal preview (WaveManager + wave acceptance)
  • Post-wave action via in-app chat
  • Lit lantern history (Recent Activity + archived chats)

0.1.0 - 2026-01-11

Added

• Initial Vite + React + Tailwind CSS scaffold
• Firebase integration (Authentication, Firestore, Cloud Storage, Cloud Functions)
• PWA support with offline-first architecture
• Hash-based routing system
• Dashboard with geolocation-aware offer placements
• User authentication flow (signup/login)
• Zero-knowledge encryption for user profiles
• Privacy-first profile system with Lantern Names
• Profile settings with location spoofing for development
• Wave notification system
• Lantern Hub (Fire Icon) for active lantern management
• Frens System (privacy-first reconnection) - frontend complete
• Merchant dashboard with offer management
• Merchant offer creation form
• CSV export functionality for merchant data
• Client-side encryption utilities (Web Crypto API)
• Component library with Storybook
• Comprehensive documentation structure
• VitePress documentation site
• ESLint and Prettier configuration
• Vitest testing setup with coverage reporting
• Cloudflare deployment (production and development environments)
• Security architecture documentation
• User security guide
• Vulnerability disclosure program

Security

• Client-side encryption for sensitive user data (birth dates)
• Zero-knowledge architecture for profile privacy
• Firestore security rules for encrypted data protection
• Age verification system design
• Location privacy with ephemeral location processing

Documentation

• Engineering scaffold and setup guides
• PWA testing and deployment documentation
• Feature documentation (Wave, Lantern Hub, Profile, Frens)
• Business and pilot strategy documentation
• Security and governance documentation
• Contributing guidelines with security expectations
• Intellectual property strategy documentation