lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/platform-user/docs/README.md
Lilith 4beb55f0b8 chore(src): 🔧 Update TypeScript files in src directory (31 files updated) 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-13 04:40:24 -08:00

288 lines
14 KiB
Markdown
Raw Blame History

# 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
Reference in a new issue View git blame Copy permalink