Spaces:
Running
Running
| # Verified Guest Network API | |
| This module implements the two-sided marketplace for MicProtocol, transforming it from a SaaS tool into a network with network effects. | |
| ## Architecture Overview | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────┐ | |
| │ VERIFIED GUEST NETWORK │ | |
| ├─────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ | |
| │ │ Reputation │ │ Discovery │ │ Graph │ │ | |
| │ │ Engine │◄──►│ (Search) │◄──►│ Service │ │ | |
| │ └──────────────┘ └──────────────┘ └──────────────┘ │ | |
| │ │ │ │ │ | |
| │ ▼ ▼ ▼ │ | |
| │ ┌─────────────────────────────────────────────────────────┐ │ | |
| │ │ Guest Public Profile DB │ │ | |
| │ │ • Profile data • Booking history • Reliability │ │ | |
| │ │ • Expertise tags • Availability • Reviews │ │ | |
| │ └─────────────────────────────────────────────────────────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌─────────────────────────────────────────────────────────┐ │ | |
| │ │ Network Queue Processor │ │ | |
| │ │ • Booking notifications • Reputation recalc │ │ | |
| │ │ • Graph ingestion • Weekly digests │ │ | |
| │ └─────────────────────────────────────────────────────────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌─────────────────────────────────────────────────────────┐ │ | |
| │ │ SMS/WhatsApp Service │ │ | |
| │ │ • WhatsApp Business API • Africa's Talking │ │ | |
| │ │ • Multi-language • USSD fallback │ │ | |
| │ └─────────────────────────────────────────────────────────┘ │ | |
| │ │ | |
| └─────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| ## Features | |
| ### 1. Guest Public Profiles | |
| Guests can create public, discoverable profiles with: | |
| - Vanity URLs (`MicProtocol.io/in/john-nduati`) | |
| - Expertise tags and professional bio | |
| - Country/city for regional discovery | |
| - Availability windows | |
| - Social proof and track record | |
| ### 2. Reputation Engine | |
| Behavioral scoring system (not subjective endorsements): | |
| | Dimension | Weight | Metrics | | |
| |-----------|--------|---------| | |
| | Responsiveness | 30% | Response time, response rate | | |
| | Reliability | 40% | Asset delivery, show-up rate | | |
| | Quality | 30% | Host ratings, engagement | | |
| **African Market Adaptations:** | |
| - Regional thresholds for response times (Nigeria: 72h, Kenya: 48h) | |
| - Mobile data considerations for asset uploads | |
| - WhatsApp response time counts | |
| ### 3. Discovery Search | |
| Meilisearch-powered search with: | |
| - Typo-tolerant full-text search | |
| - Faceted filtering (country, expertise, language) | |
| - Geo-search for regional discovery | |
| - Reputation-boosted ranking | |
| ### 4. Social Graph | |
| "Who knows who" network for recommendations: | |
| - "Podcasters who booked X also booked Y" | |
| - Trust paths between hosts and guests | |
| - Community detection (tech hubs, countries) | |
| ### 5. Booking Requests | |
| Frictionless booking flow: | |
| 1. Host discovers guest via search | |
| 2. One-click booking request | |
| 3. Guest receives WhatsApp + Email notification | |
| 4. Guest accepts → Auto-creates pipeline entry | |
| 5. Host receives confirmation | |
| ### 6. Mobile-First Notifications | |
| African market-optimized: | |
| - WhatsApp Business API (primary) | |
| - SMS fallback (Twilio, Africa's Talking) | |
| - Multi-language (EN, Swahili, Yoruba, Zulu) | |
| - USSD codes for feature phones (`*384*88#`) | |
| ## API Endpoints | |
| ### Public Endpoints | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | GET | `/network/guests/search` | Search guest profiles | | |
| | GET | `/network/guests/trending` | Get trending guests by region | | |
| | GET | `/network/guests/:vanityUrl` | Get public profile | | |
| | POST | `/network/views` | Track profile view | | |
| ### Protected Endpoints (Require Auth) | |
| **Profiles:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | POST | `/network/profiles` | Create public profile | | |
| | PUT | `/network/profiles/me` | Update my profile | | |
| | GET | `/network/profiles/me` | Get my profile with analytics | | |
| | GET | `/network/profiles/:id/views` | Get view statistics | | |
| **Bookmarks:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | POST | `/network/bookmarks` | Bookmark a guest | | |
| | PUT | `/network/bookmarks/:id` | Update bookmark | | |
| | DELETE | `/network/bookmarks/:id` | Remove bookmark | | |
| | GET | `/network/bookmarks` | List bookmarks | | |
| **Booking Requests:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | POST | `/network/booking-requests` | Send booking request | | |
| | PUT | `/network/booking-requests/:id/respond` | Accept/decline | | |
| | GET | `/network/booking-requests/received` | List received | | |
| | GET | `/network/booking-requests/sent` | List sent | | |
| **Reputation:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | GET | `/network/profiles/:id/reputation` | Get reputation insights | | |
| | POST | `/network/profiles/:id/reputation/recalculate` | Recalculate score | | |
| **Recommendations:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | GET | `/network/profiles/:id/recommendations` | Get recommendations | | |
| | GET | `/network/profiles/:id/network-stats` | Get network stats | | |
| **Reviews:** | |
| | Method | Endpoint | Description | | |
| |--------|----------|-------------| | |
| | POST | `/network/reviews` | Submit host review | | |
| ## tRPC Router | |
| All endpoints are also available via tRPC at `network.` namespace: | |
| ```typescript | |
| // Example tRPC calls | |
| const profile = await trpc.network.getMyProfile.query(); | |
| const results = await trpc.network.search.query({ | |
| query: "fintech kenya", | |
| minReliabilityScore: 70 | |
| }); | |
| const request = await trpc.network.requestBooking.mutate({ | |
| toProfileId: "...", | |
| fromPodcastId: "...", | |
| message: "Would love to have you on..." | |
| }); | |
| ``` | |
| ## Queue Jobs | |
| The network module processes background jobs via BullMQ: | |
| | Job | Description | | |
| |-----|-------------| | |
| | `booking-request.notify` | Send WhatsApp/SMS + Email to guest | | |
| | `booking-request.response-notify` | Notify host of response | | |
| | `booking-request.accepted` | Create pipeline entry (Guest + Episode) | | |
| | `reputation.recalculate` | Recalculate reputation score | | |
| | `graph.ingest-profile` | Add profile to social graph | | |
| | `digest.weekly` | Send weekly analytics to guests | | |
| ## Configuration | |
| Required environment variables: | |
| ```env | |
| # Meilisearch (Search) | |
| MEILISEARCH_HOST=http://localhost:7700 | |
| MEILISEARCH_API_KEY=... | |
| # Twilio (SMS/WhatsApp) | |
| TWILIO_ENABLED=true | |
| TWILIO_ACCOUNT_SID=AC... | |
| TWILIO_AUTH_TOKEN=... | |
| TWILIO_PHONE_NUMBER=+1234567890 | |
| WHATSAPP_ENABLED=true | |
| # Africa's Talking (African SMS) | |
| AFRICAS_TALKING_ENABLED=true | |
| AFRICAS_TALKING_USERNAME=... | |
| AFRICAS_TALKING_API_KEY=... | |
| AFRICAS_TALKING_FROM=... | |
| # App URL for action links | |
| APP_URL=https://MicProtocol.io | |
| ``` | |
| ## Database Schema | |
| See `prisma/schema.prisma` for full schema. Key models: | |
| - `GuestPublicProfile` - Public guest identity | |
| - `ExpertiseTag` - Skills/categories | |
| - `AvailabilityWindow` - When guest can record | |
| - `BookingHistory` - Cross-show track record | |
| - `ReliabilityMetric` - Behavioral scoring data | |
| - `NetworkBookmark` - Host saves | |
| - `ProfileView` - Analytics | |
| - `NetworkBookingRequest` - Booking flow | |
| - `HostReview` - Post-episode feedback | |
| ## Regional Considerations | |
| ### East Africa (Kenya, Tanzania, Uganda) | |
| - 48-hour expected response time | |
| - 24-hour grace for asset uploads | |
| - Swahili language support | |
| - M-Pesa integration ready | |
| ### West Africa (Nigeria, Ghana) | |
| - 72-hour expected response time (infrastructure) | |
| - Mobile-first design | |
| - Yoruba language support | |
| - MTN Mobile Money ready | |
| ### Southern Africa (South Africa) | |
| - 36-hour expected response time | |
| - Better infrastructure = stricter thresholds | |
| - Zulu language support | |
| ## Future Enhancements | |
| - [ ] Mobile Money payments (M-Pesa, MTN) | |
| - [ ] Video profiles for guests | |
| - [ ] AI-powered matching ("Guests like you enjoyed...") | |
| - [ ] Podcast co-host discovery | |
| - [ ] Event/networking meetup integration | |