Nostr Review and Media Marketplace Platform Implementation

This project implements a decentralized review platform and digital media marketplace using existing Nostr NIPs with Lightning payment support and comprehensive permission systems.

Implementation Overview

This platform leverages existing Nostr standards with minimal custom event kinds:

• Custom Review System: Using kind 34879 for location-based reviews
• Custom Trip System: Using kind 30025 for travel trips with photos and GPS routes
• NIP-99 (Classified Listings): For digital media marketplace listings using kind 30402
• NIP-52 (Calendar Events): For event management using kinds 31922 and 31923
• NIP-57 (Lightning Zaps): For Lightning payments via Bitcoin
• NIP-04 (Encrypted Direct Messages): For communication between users
• NIP-15 (Nostr Marketplace): Reference implementation for marketplace message types
• Custom Permission System: For managing review and media upload permissions (kinds 31492, 30384)

Visited Countries Tracker (Kind 30078)

Users can track and display the countries they've visited using addressable events:

{
  "kind": 30078,
  "content": "",
  "tags": [
    ["d", "visited-countries"],
    ["country", "US"],
    ["country", "FR"],
    ["country", "JP"],
    ["country", "AU"],
    ["alt", "Visited countries list"]
  ]
}

Visited Countries Features

• Country Selection: Select from a comprehensive list of world countries
• Map Visualization: Visited countries can be highlighted on the world map
• Travel Statistics: Shows total count of visited countries
• Public Profile: Displays visited countries on user's travel profile
• Persistent Storage: Saved to Nostr as a replaceable event
• Integration with Check-ins: Works alongside check-in system for complete travel tracking

Integration with My Map

The "My Map" feature combines:

• Check-ins: All user check-ins displayed as pins on the map
• Current Location: Latest check-in highlighted with green pulsing marker
• Visited Countries: Countries marked as visited can be highlighted (optional)
• Travel Overview: Visual representation of user's travel history

Country Tag Format

Each country is stored as:

• country tag: ISO 3166-1 alpha-2 country code (e.g., "US", "FR", "JP")
• Uses standard 2-letter country codes for consistency

Check-In System (Custom Kind 30026)

Check-ins allow travelers to share their current location (approximate area within 2km) with photos and brief updates. Each check-in is stored as an addressable event:

{
  "kind": 30026,
  "content": "Optional description of current location or experience",
  "tags": [
    ["d", "checkin-unique-id"],
    ["location", "City, Country or Area Name"],
    ["g", "geohash-encoded-location"],
    ["image", "photo1_url"],
    ["image", "photo2_url"],
    ["t", "travel"],
    ["alt", "Check-in at City, Country"]
  ]
}

Check-In Features

• Approximate Location: Location shared within 2km area (using geohash precision)
• Photo Gallery: Multiple photos can be attached to each check-in
• Travel Marker: Check-ins appear as pins on the world map
• Profile Integration: Latest check-in shows on user's My Travels profile
• Location History: Past check-ins remain visible on trips page world map
• Privacy Focused: Exact coordinates not shared, only general area
• Profile Photo Display: User's Nostr profile photo appears on map pin

Check-In Tag Format

Each check-in includes:

• location (required): Human-readable area name (e.g., "Barcelona, Spain")
• g (required): Geohash for approximate location (precision level for ~2km)
• image (optional): Multiple photo URLs
• content (optional): Brief description or update

Display on Maps

• Check-ins appear as pins on the Trips page world map
• Clicking a pin shows: user profile photo, location area, photos (if available), description
• Latest check-in per user is highlighted
• Historical check-ins remain visible with thumbnail or default marker

Trip System (Custom Kind 30025)

Travel trips with multiple photos, GPS coordinates, and route visualization are published using custom kind 30025:

{
  "kind": 30025,
  "content": "Trip description and experience details",
  "tags": [
    ["d", "trip-unique-id"],
    ["title", "Hiking in Yosemite"],
    ["summary", "Amazing day hike through the valley"],
    ["category", "hike"],
    ["image", "photo1_url", "lat1", "lon1", "timestamp1"],
    ["image", "photo2_url", "lat2", "lon2", "timestamp2"],
    ["image", "photo3_url", "lat3", "lon3", "timestamp3"],
    ["distance", "12.5"],
    ["distance_unit", "km"],
    ["gpx", "gpx_file_url"],
    ["alt", "Hiking trip in Yosemite - 12.5km"]
  ]
}

Trip Features

• Multiple Photos: Each photo includes GPS coordinates and timestamp
• Route Visualization: Photos are connected on a map showing the trip route
• GPS Extraction: Automatic GPS extraction from HEIC/JPEG EXIF data
• GPX Support: Optional GPX or TCX file upload for precise route tracking
• Distance Calculation: Automatic distance calculation from photo coordinates or GPX
• Trip Categories: Walk, Hike, Cycling

Photo Tag Format

Each photo is stored as an image tag with:

• Photo URL (required)
• Latitude (extracted from EXIF or GPX)
• Longitude (extracted from EXIF or GPX)
• Timestamp (optional, for route ordering)

Route Creation

Routes are created by:

1. Connecting photos in chronological order based on timestamps
2. Using GPX/TCX track data if provided
3. Calculating approximate distance between points

Note: Routes shown are approximate and based on photo locations, not exact paths taken.

Review System (Custom Kind 34879)

Location-based reviews are published using custom kind 34879 with the following structure:

{
  "kind": 34879,
  "content": "Review content and experience details",
  "tags": [
    ["d", "review-unique-id"],
    ["title", "Blue Bottle Coffee"],
    ["rating", "5"],
    ["category", "cafe"],
    ["location", "123 Main St, San Francisco, CA"],
    ["g", "geohash-encoded-location"],
    ["image", "photo_url"],
    ["alt", "Review of Blue Bottle Coffee - 5 stars"]
  ]
}

Digital Media Marketplace (NIP-99)

Digital media assets are published as NIP-99 classified listings (kind 30402) with the following required tags:

{
  "kind": 30402,
  "content": "Digital media description and usage rights",
  "tags": [
    ["d", "media_unique_id"],
    ["title", "Sunset Over Mountains - 4K Photo"],
    ["summary", "High-resolution landscape photography"],
    ["price", "25", "USD"],
    ["t", "photos"],
    ["category", "Landscape"],
    ["status", "active"],
    ["published_at", "unix_timestamp"],
    ["location", "Yosemite National Park"],
    ["continent", "north-america"],
    ["country", "US"],
    ["geo_folder", "north-america/US"],
    ["image", "preview_image_url"]
  ]
}

Supported Media Types

• Photos: High-resolution stock photography, artistic images, portraits
• Videos: Stock footage, animations, motion graphics, promotional videos
• Audio: Music tracks, sound effects, ambient audio, voice recordings
• Graphics: Illustrations, icons, logos, vector graphics
• Templates: Design templates, presentation layouts, document templates
• 3D Models: 3D assets, textures, materials
• Fonts: Typography, custom fonts, font families
• Presets: Photo presets, video LUTs, audio effects

Geographical Organization

All stock media in the marketplace is organized using a hierarchical geographical folder structure: World → Continent → Country. This organization makes it easy to browse and filter media by location.

Required Geographical Tags

Every stock media item requires three geographical tags for organization:

• continent: Continent value (e.g., africa, asia, europe, north-america, south-america, oceania, antarctica)
• country: ISO 3166-1 alpha-2 country code (e.g., US, FR, JP, AU)
• geo_folder: Combined path format continent/country (e.g., north-america/US, europe/FR, asia/JP)

Continent Values

• africa - 🌍 Africa
• asia - 🌏 Asia
• europe - 🇪🇺 Europe
• north-america - 🌎 North America
• south-america - 🌎 South America
• oceania - 🌏 Oceania
• antarctica - 🐧 Antarctica

Country Codes

Countries use standard ISO 3166-1 alpha-2 codes (e.g., US, FR, JP, AU, BR, ZA).

Example: Stock Photo from Paris

{
  "kind": 30402,
  "tags": [
    ["d", "photo_eiffel_tower"],
    ["title", "Eiffel Tower at Sunset"],
    ["continent", "europe"],
    ["country", "FR"],
    ["geo_folder", "europe/FR"],
    ["location", "Paris, France"]
  ]
}

Benefits

• Easy Discovery: Browse media by continent and country
• Efficient Filtering: Query media from specific regions using relay-level tag filtering
• Clean Organization: Hierarchical folder structure keeps the marketplace organized
• Automated Placement: New uploads are automatically placed in the correct geographical folder

Supported Currencies

• Lightning: BTC, SATS - Paid via NIP-57 Lightning Zaps
• Fiat: USD, EUR, GBP, CAD, AUD - Paid via Stripe integration

Payment Methods

Lightning Payments (NIP-57)

For digital media priced in BTC or SATS:

1. Buyer creates a zap request (kind 9734) with license details
2. Payment flows through standard Lightning Network via NIP-57
3. Zap receipt (kind 9735) serves as payment confirmation
4. Creator receives notification via Lightning wallet

Fiat Payments (Stripe)

For digital media priced in fiat currencies:

1. Buyer initiates Stripe payment flow
2. Payment processed via Stripe API
3. Confirmation sent to creator via encrypted DM
4. Traditional payment receipt via email

License Communication (NIP-04)

License orders are communicated via encrypted direct messages (kind 4) following NIP-15 message structure:

{
  "type": 0,
  "id": "license_unique_id",
  "name": "buyer_name",
  "message": "licensing_questions",
  "contact": {
    "nostr": "buyer_pubkey",
    "email": "buyer_email"
  },
  "items": [
    {
      "media_id": "media_unique_id",
      "quantity": 1
    }
  ],
  "payment_method": "lightning|stripe",
  "amount": 25,
  "currency": "USD"
}

Security Considerations

• Encryption: All license details encrypted using NIP-44 (preferred) or NIP-04 (fallback)
• Authentication: Buyers and creators authenticated via Nostr key pairs
• Payment Security: Lightning payments are cryptographically secure; Stripe provides traditional payment security
• License Delivery: Digital files delivered via encrypted download links
• Dispute Resolution: Handled through direct Nostr communication between parties

Integration Requirements

Lightning Setup

• Creators need Lightning addresses (lud16 or lud06) in their profiles
• Buyers need Lightning wallets or WebLN extensions

Stripe Setup

• Creators need Stripe accounts for fiat payments
• Environment variable VITE_STRIPE_PUBLISHABLE_KEY required
• Backend API endpoint /api/create-payment-intent needed for production

Advantages of This Approach

1. Standards Compliance: Uses existing, well-tested Nostr NIPs
2. Interoperability: Compatible with other NIP-99 marketplace clients
3. Dual Payment Support: Supports both crypto and fiat payments
4. Decentralized: No central marketplace authority required
5. Instant Delivery: Digital assets delivered immediately after payment
6. Creator Focused: Built specifically for digital media creators
7. Review Integration: Combines location reviews with media marketplace

Community Page Content (Kind 30079)

The Community page content is stored as a replaceable event published by admin:

{
  "kind": 30079,
  "content": "{\"faqs\":[{\"question\":\"What is TravelTelly?\",\"answer\":\"...\"}],\"forumText\":\"...\",\"forumHashtags\":[\"#traveltelly\"],\"usefulLinks\":[{\"title\":\"Lonely Planet\",\"url\":\"https://...\",\"description\":\"...\",\"category\":\"travel\"}]}",
  "tags": [
    ["d", "community-page"],
    ["title", "TravelTelly Community Page Content"],
    ["alt", "Community page configuration for TravelTelly"]
  ]
}

Community Data Structure

The content field contains a JSON object with:

• faqs: Array of FAQ objects with question and answer fields
• forumText: Description text for the forum section
• forumHashtags: Array of hashtags for community discussions
• usefulLinks: Array of link objects with title, url, description, and category (travel/nostr/phoneography)

Admin Management

The admin can edit the community page content through the admin panel "Community" tab, which includes:

• Add/remove FAQ items
• Edit forum description and hashtags
• Manage useful links in three categories
• All changes are published to Nostr as a replaceable event

Newsletter System (Kind 30080)

Newsletter subscribers are stored as addressable events published by admin:

{
  "kind": 30080,
  "content": "",
  "tags": [
    ["d", "subscriber-email@example.com"],
    ["email", "email@example.com"],
    ["name", "Subscriber Name"],
    ["status", "active"],
    ["source", "footer"],
    ["alt", "Newsletter subscriber: email@example.com"]
  ]
}

Subscriber Status

• active: Receives newsletters
• unsubscribed: Removed from mailing list

Newsletter Content

Newsletters include:

• Latest 3 reviews
• Latest 3 stories
• Latest 3 trips
• Latest 3 stock media items
• Custom text and links

Publishing

Newsletters are:

• Published to Nostr (kind 1) with #newsletter tag
• Shared to Clawstr /c/travel
• Email HTML generated for manual sending

Permission Systems

The platform implements dual permission systems for quality control:

Review Permission System

To maintain quality and prevent spam in reviews:

Permission Request (Kind 31492)

Users request permission to create reviews via addressable events:

{
  "kind": 31492,
  "content": "Reason for requesting review permission",
  "tags": [
    ["d", "review-permission-timestamp"],
    ["request_type", "review_permission"],
    ["experience", "Travel blogger with 3 years experience"],
    ["alt", "Request for review creation permission"]
  ]
}

Media Upload Permission System

To maintain quality and prevent spam in the media marketplace:

Permission Request (Kind 31492)

Users request permission to upload digital media via addressable events:

{
  "kind": 31492,
  "content": "Reason for requesting media upload permission",
  "tags": [
    ["d", "media-permission-timestamp"],
    ["request_type", "stock_media_permission"],
    ["portfolio", "https://photographer-portfolio.com"],
    ["experience", "Professional photographer with 5 years experience"],
    ["alt", "Request for media upload permission"]
  ]
}

Permission Grant (Kind 30384)

Admins grant permissions via replaceable events:

{
  "kind": 30384,
  "content": "Media upload permission granted",
  "tags": [
    ["d", "media-grant-user_pubkey"],
    ["grant_type", "stock_media_permission"],
    ["p", "user_pubkey"],
    ["e", "original_request_id"],
    ["alt", "Media upload permission granted"]
  ]
}

Permission Blocking (Kind 30384)

Admins can block users from uploading media:

{
  "kind": 30384,
  "content": "Reason for blocking",
  "tags": [
    ["d", "media-block-user_pubkey"],
    ["grant_type", "stock_media_permission_blocked"],
    ["p", "user_pubkey"],
    ["e", "original_request_id"],
    ["block_reason", "Inappropriate content"],
    ["alt", "Media upload permission blocked"]
  ]
}

Admin Configuration

The system recognizes a specific admin npub: npub105em547c5m5gdxslr4fp2f29jav54sxml6cpk6gda7xyvxuzmv6s84a642

Only this admin can:

• Grant review creation permissions
• Grant media upload permissions
• Block permission requests
• Revoke existing permissions
• Manage review categories
• Manage all reviews (edit/delete)
• Access the admin panel

Review Category Management System

The application includes a dynamic category management system for review classifications using custom Nostr events.

Category Definition (Kind 37539)

Review categories are stored as addressable events that can be updated by administrators:

{
  "kind": 37539,
  "content": "[{\"value\":\"restaurant\",\"label\":\"🍽️ Restaurant\",\"group\":\"Food & Drink\"},{\"value\":\"hotel\",\"label\":\"🏨 Hotel\",\"group\":\"Places\"}]",
  "tags": [
    ["d", "review-categories"],
    ["title", "Review Categories"],
    ["alt", "Review category definitions for the review system"]
  ]
}

Category Structure

Each category object contains:

• value: Unique identifier (lowercase, hyphens allowed)
• label: Display name with optional emoji
• group: Category grouping for UI organization

Admin Category Management

Administrators can:

• Add new categories via the admin panel
• Remove existing categories
• Organize categories into groups
• Update category labels and emojis

Integration with Reviews

The review system (kind 34879) references categories via the category tag, using the category's value field. The CreateReviewForm dynamically loads available categories and displays them grouped by category group.

Calendar Events System (NIP-52)

The platform implements a comprehensive calendar events system using NIP-52 standard for both date-based and time-based events.

Date-Based Events (Kind 31922)

All-day events that span one or more full days:

{
  "kind": 31922,
  "content": "Annual tech conference featuring the latest innovations",
  "tags": [
    ["d", "tech-conf-2024"],
    ["title", "Tech Innovation Conference 2024"],
    ["summary", "Three-day conference on emerging technologies"],
    ["start", "2024-09-15"],
    ["end", "2024-09-17"],
    ["location", "San Francisco Convention Center"],
    ["image", "https://example.com/conference-banner.jpg"],
    ["t", "technology"],
    ["t", "conference"],
    ["alt", "Tech Innovation Conference 2024 - September 15-17"]
  ]
}

Time-Based Events (Kind 31923)

Events with specific start and end times:

{
  "kind": 31923,
  "content": "Weekly team standup meeting to discuss project progress",
  "tags": [
    ["d", "team-standup-weekly"],
    ["title", "Weekly Team Standup"],
    ["summary", "Project updates and planning session"],
    ["start", "1726574400"],
    ["end", "1726576200"],
    ["start_tzid", "America/New_York"],
    ["end_tzid", "America/New_York"],
    ["location", "https://meet.google.com/abc-defg-hij"],
    ["t", "meeting"],
    ["t", "work"],
    ["alt", "Weekly Team Standup - recurring meeting"]
  ]
}

Event Features

• Dual Event Types: Support for both all-day (date-based) and timed events
• Rich Metadata: Title, summary, description, location, and images
• Categorization: Hashtag-based event categorization using t tags
• Participants: Support for event participants via p tags
• Time Zones: Timezone support for time-based events
• Search & Filter: Advanced filtering by type, date, and categories
• Admin Controls: Enhanced admin interface for event management

Event Management Interface

The platform provides two interfaces for calendar events:

1. Public Events Page (/events): Browse and create events with basic filtering
2. Admin Events Page (/admin/events): Advanced event management with:
   • Comprehensive search functionality
   • Advanced filtering (all events, my events, by type)
   • Event statistics and analytics
   • Enhanced creation form with validation

Event Validation

All calendar events are validated to ensure NIP-52 compliance:

• Required tags: d, title, start
• Date format validation for date-based events (YYYY-MM-DD)
• Unix timestamp validation for time-based events
• End time must be after start time
• Proper timezone handling for time-based events

Event Status Tracking

The system automatically determines event status:

• Upcoming: Events that haven't started yet
• Active: Events currently happening
• Past: Events that have ended

Integration with Existing Systems

Calendar events integrate seamlessly with the platform's existing features:

• User Authentication: Events require login to create
• Relay Management: Events are published to configured relays
• Theme Support: Full light/dark mode compatibility
• Responsive Design: Mobile-optimized event interfaces

Review Management System

The platform includes comprehensive review management capabilities for administrators to maintain content quality and handle moderation.

Admin Review Management

The admin panel provides a dedicated "Manage Reviews" tab with the following features:

Review Overview Dashboard

• Statistics Cards: Total reviews, average rating, unique authors, categories count
• Real-time Metrics: Live updates of review statistics and trends
• Visual Analytics: Rating distribution and category breakdown

Advanced Search and Filtering

• Full-text Search: Search across review titles, content, and locations
• Category Filtering: Filter by specific review categories
• Rating Filtering: Filter by star ratings (1-5 stars)
• Multi-criteria Sorting: Sort by newest, oldest, or rating

Review Management Actions

• Edit Reviews: Comprehensive edit form with all review fields
• Delete Reviews: Safe deletion using NIP-09 deletion events
• Bulk Operations: Manage multiple reviews efficiently
• Real-time Updates: Automatic refresh after modifications

Review Editing System

Edit Review Form

The edit form preserves all original review metadata while allowing updates:

{
  "kind": 34879,
  "content": "Updated review content",
  "tags": [
    ["d", "original-review-id"], // Preserved for replacement
    ["title", "Updated Business Name"],
    ["rating", "4"],
    ["category", "updated-category"],
    ["location", "Updated Address"],
    ["more_info_url", "https://updated-website.com"],
    ["image", "preserved-image-url"], // Preserved from original
    ["g", "preserved-geohash"], // Preserved from original
    ["t", "updated-hashtag"],
    ["alt", "Updated review description"]
  ]
}

Edit Form Features

• Field Preservation: Maintains existing images and geohash data
• Category Management: Dynamic category selection with grouping
• Hashtag System: Add/remove hashtags with visual management
• Rating Interface: Interactive star rating selector
• Validation: Comprehensive form validation with error handling
• Auto-save: Preserves original metadata while updating content

Review Deletion System

NIP-09 Deletion Events

Reviews are deleted using standard Nostr deletion events:

{
  "kind": 5,
  "content": "Review deleted by admin",
  "tags": [
    ["e", "review-event-id"],
    ["a", "34879:author-pubkey:review-d-tag"]
  ]
}

Deletion Features

• Confirmation Dialog: Prevents accidental deletions
• Audit Trail: Deletion events provide moderation transparency
• Immediate Effect: Reviews are marked for deletion across relays
• Reversible: Deletion events can be countered if needed

Review Display and Management

Enhanced Review Cards

Each review in the admin interface displays:

• Complete Metadata: Title, rating, category, location, timestamps
• Author Information: Profile data with avatar and display name
• Content Preview: Truncated content with full view option
• Action Buttons: Direct edit and delete controls
• Visual Indicators: Rating stars, category emojis, hashtags

Responsive Grid Layout

• Adaptive Columns: 1-3 columns based on screen size
• Loading States: Skeleton loading for better UX
• Empty States: Helpful messages with relay selector
• Error Handling: Graceful error display with retry options

Security and Permissions

Admin-Only Access

• Authentication Required: Must be logged in as admin
• Permission Verification: Double-checks admin status
• Secure Operations: All edit/delete operations require admin privileges
• Audit Logging: All admin actions are recorded on Nostr

Data Integrity

• Validation: All edits validated before publishing
• Preservation: Critical metadata (images, geohash) preserved
• Replacement Logic: Uses addressable event replacement (same d-tag)
• Error Recovery: Graceful handling of failed operations

Integration with Existing Systems

The review management system integrates with:

• Permission System: Respects existing review permissions
• Category Management: Uses dynamic category system
• User Management: Integrates with user profiles and authentication
• Relay Management: Works with configured relay settings
• Theme System: Full light/dark mode support

Unified Search System

The platform features a comprehensive search system that allows users to search across all content types from a single interface on the homepage.

Search Functionality

Unified Search Bar

Located prominently on the homepage above the world map, the search bar provides:

• Cross-Content Search: Searches reviews, stories, and stock media simultaneously
• Tag-Based Search: Primary focus on searching hashtags (t tags) across all content
• Multi-field Search: Searches titles, content, locations, and categories
• Real-time Results: Live search results as you type
• Keyboard Navigation: Full keyboard support with arrow keys and enter

Search Scope

The search system covers three main content types:

Reviews (Kind 34879)

• Searches: title, content, hashtags, category, location
• Filters: Only authorized reviewers' content
• Results: Shows rating, category, location, author info

Stories (Kind 30023)

• Searches: title, content, hashtags
• Filters: Only admin-published stories
• Results: Shows summary, publication date, author info

Stock Media (Kind 30402)

• Searches: title, description, hashtags, location
• Filters: Only authorized uploaders' content, excludes deleted items
• Results: Shows price, currency, location, preview images

Search Interface Features

Smart Search Results

• Type Indicators: Visual icons distinguish between reviews, stories, and media
• Rich Previews: Shows relevant metadata for each content type
• Author Information: Profile pictures and display names
• Relevance Ranking: Prioritizes exact matches, then tag matches, then recency
• Fully Clickable Items: Entire search result area is clickable to navigate to content
• Clickable Tags: Individual tags in results are clickable for refined searches
• Interactive Results: Hover effects, chevron indicators, and visual feedback for better UX
• Visual Cues: Helpful hints and indicators show users what's clickable

Search Suggestions

• Popular Tags: Shows trending hashtags when search is empty
• Clickable Suggestions: One-click search by clicking any suggested tag
• Auto-complete: Suggests tags as you type
• Tag Discovery: Helps users discover content categories
• Show More/Less: Expandable suggestion list for extensive tag collections

Responsive Design

• Mobile Optimized: Works seamlessly on all screen sizes
• Keyboard Shortcuts: Full keyboard navigation support
• Loading States: Skeleton loading for better perceived performance
• Error Handling: Graceful handling of search failures
• Visual Feedback: Hover effects, tooltips, chevron indicators, and transition animations
• Accessibility: Proper ARIA labels and keyboard navigation
• Touch Friendly: Large click areas and touch-optimized interactions

Technical Implementation

Search Hook (useUnifiedSearch)

// Searches across all content types
const { data: searchResults, isLoading } = useUnifiedSearch(query);

// Returns unified SearchResult interface
interface SearchResult {
  id: string;
  type: 'review' | 'story' | 'media';
  title: string;
  content: string;
  tags: string[];
  author: string;
  createdAt: number;
  event: NostrEvent;
  // Type-specific fields
  rating?: number;
  category?: string;
  location?: string;
  price?: string;
  currency?: string;
  images?: string[];
}

Search Suggestions Hook (useSearchSuggestions)

// Provides popular tags for auto-complete
const { data: suggestions } = useSearchSuggestions();
// Returns array of popular hashtags across all content

Search Performance

• Efficient Queries: Separate queries for each content type with appropriate filters
• Caching: 30-second stale time for search results
• Debouncing: Only searches when query is 2+ characters
• Timeout Protection: 5-second timeout for all search queries

Search Result Navigation

Smart Navigation

When users select search results, they're taken to the appropriate page:

• Reviews: Direct link to review detail page using naddr identifier
• Stories: Navigate to stories page where they can find the specific story
• Media: Navigate to marketplace where they can find the specific item

Search-to-Action Flow

1. User types search query on homepage
2. Real-time results appear with rich previews
3. User selects result or presses enter
4. Navigates to appropriate content page
5. Content is highlighted or filtered based on search context

Search Integration Points

Homepage Integration

• Prominent Placement: Featured section above the world map
• Clear Call-to-Action: "Search Everything" heading with descriptive text
• Visual Hierarchy: Properly integrated with existing homepage sections
• Interactive Onboarding: Helpful tips and visual cues for first-time users

Cross-Platform Consistency

• Unified Interface: Same search experience across all devices
• Theme Support: Full light/dark mode compatibility
• Accessibility: Screen reader friendly with proper ARIA labels

Enhanced Search Interaction

Full-Item Clickability

The search results are designed for maximum usability:

• Entire Result Clickable: Users can click anywhere on a search result to navigate to that content
• Visual Indicators: Chevron arrows appear on hover to indicate clickability
• Hover Effects: Subtle background changes and shadows provide visual feedback
• Touch Optimization: Large click areas work well on mobile devices

Dual-Action Interface

Each search result supports two types of interactions:

1. Main Click: Click anywhere on the result to view the full content
2. Tag Click: Click specific hashtags to search for related content

User Experience Enhancements

• Visual Hints: "Click any result to view • Click tags to search" guidance
• Smooth Animations: 200ms transitions for all hover effects
• Keyboard Navigation: Arrow keys work seamlessly with mouse interactions
• Event Handling: Proper event propagation prevents conflicts between main and tag clicks

Search Analytics and Insights

The search system provides insights into:

• Popular Search Terms: Most frequently searched hashtags
• Content Discovery: Which content types are most searched
• User Behavior: Search patterns and result selection rates
• Tag Popularity: Trending hashtags across all content types

Future Enhancements

• Multi-signature Escrow: Using Bitcoin multi-sig for high-value licenses
• Reputation System: Using NIP-58 badges for creator/buyer ratings
• Advanced Licensing: Extended usage rights and commercial licenses
• AI Tagging: Automatic content tagging and categorization
• Royalty Tracking: Revenue sharing for collaborative works
• Portfolio Analytics: Advanced creator dashboard with sales insights
• Decentralized Moderation: Community-based content moderation system
• Category Permissions: Allow specific users to manage certain category groups
• Category Analytics: Track usage statistics for different categories
• Event RSVPs: Implement NIP-52 RSVP system (kind 31925)
• Event Calendars: Support for calendar collections (kind 31924)
• Recurring Events: Client-side recurring event management
• Event Notifications: Push notifications for upcoming events
• Event Integration: Link events with reviews and marketplace listings
• Review Analytics: Advanced analytics dashboard for review trends
• Automated Moderation: AI-powered content moderation assistance
• Review Versioning: Track edit history for reviews
• Bulk Review Operations: Mass edit/delete capabilities
• Review Export: Export review data for analysis
• Advanced Search: Elasticsearch integration for complex queries
• Search Analytics: Detailed search metrics and popular query tracking
• Search Filters: Advanced filtering options within search results
• Search History: Personal search history and saved searches
• Global Search: Search across multiple relays simultaneously
• Semantic Search: AI-powered semantic search capabilities