Spaces:
Running
Running
| # 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`. | |