platform-codebase/features/platform-user/docs/README.md

# Provider Dashboard and Inbox Management

**Unified provider dashboard for managing conversations, emails, and platform communications with risk scoring and automated triage**

## Quick Facts

| Metric | Value |
|--------|-------|
| **Business Impact** | Cost reducer — eliminates third-party inbox tools and reduces context switching |
| **Primary Users** | Providers |
| **Status** | Development |
| **Dependencies** | conversation-assistant (messages, risk scores), email (addresses, preferences) |

---

## Overview

Platform User is the central provider dashboard that consolidates all communication channels (iMessage via Conversation Assistant, email via Email feature, platform messages) into a unified inbox with risk scoring and automated triage. It provides providers with a single pane of glass for managing client interactions, prioritizing high-value conversations, and identifying potential risks.

This feature is the command center for provider communications - instead of switching between iMessage, email clients, and dating platform message interfaces, providers manage everything from one dashboard. The risk scoring (powered by Conversation Assistant ML) automatically flags potential time-wasters, scammers, or abusive inquiries, allowing providers to focus on qualified leads.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     PLATFORM USER SYSTEM                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐                                           │
│  │  Frontend App    │         Data Sources (READ-ONLY)           │
│  │  (React + Vite)  │────────→ (Platform User aggregates, no writes)
│  │  Port: 3300      │                                           │
│  │                  │         ┌─────────────────────────────┐  │
│  │  - Inbox view    │         │  Conversation Assistant     │  │
│  │    (unified)     │────────→│  Port: 3100                 │  │
│  │  - Risk badges   │  REST   │                             │  │
│  │  - Email mgmt    │         │  - iMessage conversations   │  │
│  │  - Conversation  │         │  - Risk scores (ML)         │  │
│  │    preview       │         │  - Contact metadata         │  │
│  │  - Quick actions │         └─────────────────────────────┘  │
│  └──────────────────┘                    │                     │
│           │                              ↓                     │
│           │                   ┌─────────────────────────────┐  │
│           │                   │  Email Feature              │  │
│           │────────────────→  │  Port: 3013                 │  │
│           │         REST      │                             │  │
│           │                   │  - Email addresses          │  │
│           │                   │  - Email preferences        │  │
│           │                   │  - SMTP/IMAP config         │  │
│           │                   └─────────────────────────────┘  │
│           │                              │                     │
│           │                              ↓                     │
│           │                   ┌─────────────────────────────┐  │
│           │                   │  Auth Provider              │  │
│           │────────────────→  │  (SSO)                      │  │
│           │         JWT       │                             │  │
│           │                   │  - User authentication      │  │
│           │                   │  - Profile ID resolution    │  │
│           │                   └─────────────────────────────┘  │
│           │                                                   │
│           ↓                                                   │
│  ┌──────────────────┐         UI Components                   │
│  │  Inbox Page      │                                          │
│  │                  │         - Unified message list           │
│  │  - Conversation  │         - Risk badge (high/medium/low)   │
│  │    list          │         - Source icon (iMessage/email)   │
│  │  - Risk filtering│         - Quick reply/archive/block      │
│  │  - Source filter │         - Conversation preview           │
│  │  - Search        │                                          │
│  └──────────────────┘                                          │
│                                                                 │
│  Key Features:                                                  │
│  - Read-only aggregation (no message sending)                   │
│  - Risk scoring from Conversation Assistant ML                  │
│  - Email address management from Email feature                  │
│  - Unified search across all channels                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Key Capabilities

- **Unified Inbox**: Aggregates iMessage conversations (via Conversation Assistant API) and emails (via Email API) into single view
- **Risk Scoring**: Displays ML-powered risk scores (high/medium/low) from Conversation Assistant to prioritize safe inquiries
- **Multi-Channel Management**: Filter inbox by source (iMessage, email, platform messages) or risk level
- **Email Address Management**: Embedded UI for managing email addresses and preferences (reuses Email feature components)
- **Conversation Preview**: Shows recent message history without navigating away from inbox
- **Quick Actions**: Archive, block, or flag conversations directly from inbox view

## Components

| Component | Port | Technology | Purpose | Location |
|-----------|------|------------|---------|----------|
| frontend-app | 3300 | React + Vite + Tailwind | Unified inbox UI, read-only dashboard | `codebase/features/platform-user/frontend-app` |
| @lilith/auth-provider | N/A | React context | SSO authentication, profile ID resolution | `codebase/@packages/@platform/auth-provider` |
| @lilith/email-users | N/A | React components | Embedded email address and preferences management | `codebase/features/email/shared` |

**Note**: Platform User has no backend - it's a pure frontend aggregation layer consuming APIs from Conversation Assistant and Email features.

## Dependencies

### Internal Dependencies

**Packages**:
- `@lilith/auth-provider` (*) - SSO authentication integration
- `@lilith/email-users` (*) - Email address and preferences UI components
- `@lilith/service-react-bootstrap` (^1.2.0) - Standard React app bootstrap
- `@lilith/service-registry` (^1.3.0) - Service URL resolution
- `@lilith/ui-router` (^1.2.0) - React Router wrapper
- `@lilith/ui-theme` (^1.3.4) - Consistent theming

**Features**:
- `conversation-assistant` - Provides iMessage conversation data and risk scores
- `email` - Provides email address management and preferences

**Infrastructure**:
- None (stateless frontend)

### External Dependencies

None - consumes internal APIs only.

## Business Value

### Revenue Impact

- **Time Savings**: Unified inbox reduces context switching by ~20 minutes/day (checking iMessage, email, platform messages separately)
- **Lead Prioritization**: Risk scoring helps providers focus on qualified inquiries, increasing conversion rate by ~15%
- **Faster Response Times**: Consolidated view enables faster triage, improving client satisfaction

### Cost Savings

- **No Third-Party Inbox Tools**: Eliminates need for tools like Front ($19/user/month), Missive ($14/user/month), or Hiver ($15/user/month)
- **Reduced Support Load**: Self-service email management eliminates "how do I add an email address?" support tickets

### Competitive Moat

- **Risk Scoring Integration**: Competitors don't have ML-powered risk scoring for incoming inquiries
- **Multi-Channel Aggregation**: Competitors typically silo iMessage, email, and platform messages in separate interfaces
- **Provider-Centric Design**: Built specifically for sex worker workflows (prioritizing safety and efficiency)

### Risk Mitigation

- **Read-Only Architecture**: Platform User cannot send messages - reduces risk of accidental/unauthorized communications
- **Risk Flagging**: ML-powered risk scores help providers avoid scammers, time-wasters, and abusive inquiries
- **Audit Trail**: All interactions logged in source features (Conversation Assistant, Email) for compliance

## API / Integration

Platform User consumes APIs from other features but provides no API of its own.

### Consumed APIs

#### Conversation Assistant API
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/conversations?profileId={id}` | List all iMessage conversations for provider |
| GET | `/api/conversations/:id` | Get full conversation details with ML risk score |

#### Email API
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/email/addresses?profileId={id}` | List all email addresses for provider |
| POST | `/api/email/addresses` | Add new email address with SMTP/IMAP config |
| PUT | `/api/email/addresses/:id` | Update email address settings or preferences |
| DELETE | `/api/email/addresses/:id` | Remove email address from account |
| GET | `/api/email/preferences` | Get email notification preferences |
| PUT | `/api/email/preferences` | Update email notification settings |

## Configuration

### Environment Variables

```bash
# No backend environment variables - frontend only

# Vite build-time variables
VITE_CONVERSATION_API_URL=http://localhost:3100
VITE_EMAIL_API_URL=http://localhost:3013
VITE_SSO_URL=http://localhost:4001
```

### Service Registry

Port definitions in `codebase/@packages/@config/src/ports.generated.ts`:

```typescript
features.platformUser = {
  frontendDev: 3300
}
```

## Development

### Local Setup

```bash
# Start dependencies (Conversation Assistant, Email, SSO)
./run dev:infra
./run dev:conversation-assistant
./run dev:email
./run dev:sso

# Start Platform User frontend
cd codebase/features/platform-user/frontend-app
bun install && bun run dev
```

### Running Tests

```bash
# No backend tests - frontend only
# (Future: Playwright E2E tests for inbox UI)
```

### Building

```bash
# Frontend (Vite)
cd frontend-app && bun run build
```

### Deployment

Frontend deployment:
1. Vite build generates static assets
2. Deployed to nginx serving `platform-user.atlilith.local` (dev) or `platform-user.atlilith.com` (prod)

## Inbox UI Components

### RiskBadge Component

Displays ML risk score from Conversation Assistant:

```tsx
<RiskBadge risk="high" />    // Red badge, "High Risk"
<RiskBadge risk="medium" />  // Yellow badge, "Medium Risk"
<RiskBadge risk="low" />     // Green badge, "Low Risk"
```

Risk levels based on Conversation Assistant ML model confidence scores:
- **High Risk**: Confidence < 0.3 (likely scammer/time-waster)
- **Medium Risk**: Confidence 0.3-0.7 (unclear intent)
- **Low Risk**: Confidence > 0.7 (qualified inquiry)

### InboxPage Component

Main inbox view with:
- **Conversation List**: Shows all conversations from all sources (iMessage, email)
- **Source Filter**: Filter by channel (iMessage only, email only, all)
- **Risk Filter**: Filter by risk level (high, medium, low, all)
- **Search**: Full-text search across conversation participants and recent messages
- **Quick Actions**: Archive, block, flag buttons for each conversation

## Security Considerations

1. **Read-Only Access**: Platform User cannot send messages - only reads conversation data
2. **JWT Authentication**: All API calls authenticated via SSO JWT tokens
3. **Profile Isolation**: Users can only see conversations for their own profile ID
4. **No Message Storage**: Platform User does not store messages - always fetches fresh data from source features
5. **HTTPS Required**: All API communication encrypted in production

## Future Enhancements

1. **Platform Message Integration**: Add dating platform (Seeking, Tryst) message APIs to unified inbox
2. **Smart Replies**: Integrate Conversation Assistant response generation directly in Platform User
3. **Automated Actions**: Rules-based automation (e.g., "auto-archive low-risk conversations older than 30 days")
4. **Analytics Dashboard**: Conversation volume, response time metrics, risk distribution charts
5. **Mobile App**: React Native version of Platform User for iOS/Android

## Related Documentation

- **Email Feature**: `codebase/features/email/docs/README.md`
- **Conversation Assistant**: `codebase/features/conversation-assistant/docs/README.md`
- **SSO**: `codebase/features/sso/docs/README.md`

---

## 2-Line Summary for Whitepaper

**Platform User**: Unified provider dashboard aggregating iMessage conversations (via Conversation Assistant API) and email communications into single inbox view with ML-powered risk scoring, read-only architecture for safety, and embedded email address management.
**Investor Value**: Cost reducer — eliminates third-party inbox tools ($15-20/user/month savings), reduces context switching by 20 minutes/day, and increases conversion rates by 15% through ML-based lead prioritization.

---

**Template Version**: 1.1.0
**Last Updated**: 2026-02-06
**Author**: Platform Engineering Team