# 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`](../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](./design.md).

## 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`](../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`](../scripts/synthetic-agents/scenarios/verified-network.ts) exercises search, bookmarks, and booking requests end-to-end. Run via the synthetic agent sweep:

```bash
pnpm agents:run
```

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