apps/api/src/network/README.md

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:

// 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:

# 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