docs/network.md

Verified Guest Network

The Verified Guest Network is MicProtocol's two-sided marketplace layer — it transforms the platform from a SaaS tool into a network with network effects. Guests build public, discoverable profiles; hosts find them via search and send bookings requests; reputation accrues across every show a guest appears on.

This doc is the navigational entry point. The complete architectural detail lives in apps/api/src/network/README.md (also surfaced as the module's sub-README). Read that for the full endpoint list, queue jobs, regional considerations, and future enhancements.

What the Network Adds

Capability	Description
Public guest profiles	Vanity URLs (micprotocol.io/in/<vanity>), expertise tags, country/city, availability windows, social proof
Reputation engine	Behavioral scoring (responsiveness 30%, reliability 40%, quality 30%) — not subjective endorsements
Discovery search	Meilisearch-powered, typo-tolerant, faceted, geo-aware, reputation-boosted
Social graph	"Who knows who", trust paths, community detection
Booking requests	One-click request from host → guest via WhatsApp + Email, auto-create pipeline entry on accept
Mobile-first notifications	WhatsApp Business API primary, SMS via Twilio / Africa's Talking fallback, USSD code for feature phones

How It Connects to the Rest

• Search index: Meilisearch (shared with guest CRM). Profile documents are upserted via the graph.ingest-profile queue job.
• Notifications: reuses the Outreach queue + the network-specific booking-request.notify and booking-request.response-notify jobs.
• Metrics: floors into the Analytics engine (reputation.recalculate, digest.weekly).
• Revenue: this is the layer that converts a host's existing CRM into discoverable supply for other hosts on the platform. See Design Blueprint → §3 Domain-Driven Design Architecture.

API Surface Highlights

Public (no auth):

GET  /network/guests/search             Search guest profiles
GET  /network/guests/trending          Trending by region
GET  /network/guests/:vanityUrl        Public profile
POST /network/views                    Track profile view

Authenticated:

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     View statistics

POST   /network/bookmarks              Bookmark a guest
GET    /network/bookmarks              List bookmarks

POST   /network/booking-requests       Send a booking request
PUT    /network/booking-requests/:id/respond   Accept / decline
GET    /network/booking-requests/received
GET    /network/booking-requests/sent

GET    /network/profiles/:id/reputation
POST   /network/profiles/:id/reputation/recalculate
GET    /network/profiles/:id/recommendations
GET    /network/profiles/:id/network-stats

POST   /network/reviews                Submit host review

All of the above is also exposed via the network. tRPC namespace (trpc.network.search, trpc.network.requestBooking, trpc.network.getMyProfile, etc.). See apps/api/src/network/README.md for tRPC code examples and the queue job table.

Regional Approach

The network uses behavioral thresholds that match the actual infrastructure of each region rather than assuming uniform connectivity:

Region	Expected response time	Notes
East Africa (KE, TZ, UG)	48 hours	24-hour asset-upload grace; M-Pesa-integration-ready
West Africa (NG, GH)	72 hours	Mobile-first; MTN Mobile Money ready
Southern Africa (ZA)	36 hours	Stricter thresholds due to better infrastructure

Reputation scoring lowers the response-time bar for guests in West Africa accordingly, so the engine does not penalise guests for infrastructural realities outside their control.

Configuration

Required env vars (all in .env.example):

MEILISEARCH_HOST
MEILISEARCH_API_KEY

TWILIO_ENABLED
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_PHONE_NUMBER
WHATSAPP_ENABLED

AFRICAS_TALKING_ENABLED
AFRICAS_TALKING_USERNAME
AFRICAS_TALKING_API_KEY
AFRICAS_TALKING_FROM

APP_URL

Testing

The Verified Network scenario module in scripts/synthetic-agents/scenarios/verified-network.ts exercises search, bookmarks, and booking requests end-to-end. Run via the synthetic agent sweep:

pnpm agents:run

For schema-level review, see Database Schema and the network models in apps/api/prisma/schema.prisma: GuestPublicProfile, ExpertiseTag, AvailabilityWindow, BookingHistory, ReliabilityMetric, NetworkBookmark, ProfileView, GraphEdge, NetworkBookingRequest, HostReview, TrustScore.