lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/platform-user/docs
History
…
..
README.md

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

# 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:

features.platformUser = {
  frontendDev: 3300
}

Development

Local Setup

# 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

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

Building

# 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:

<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