# 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