lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/marketplace/docs/README.md
Lilith 7f95838c48 chore(marketplace-most-significant): 🔧 Update TypeScript files in src directory (31 files) 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-14 10:39:50 -08:00

26 KiB
Raw Permalink Blame History

Multi-Brand Provider Discovery & Booking Platform

White-label marketplace enabling provider discovery, real-time messaging, and booking for adult service platforms

Quick Facts

Metric Value
Business Impact Revenue enabler — Primary monetization engine ($1.32M projected ARR)
Primary Users Clients and Providers
Status Production
Dependencies merchant, payments, sso, safety, seo, attributes

Overview

The marketplace feature is Lilith Platform's core revenue engine—a multi-tenant provider discovery and booking platform that powers multiple branded domains (TrustedMeet, SpoiledBabes, LilithFan, etc.) from a single codebase. The platform enables clients to search, message, and book appointments with verified providers while enforcing tier-based access controls and usage caps.

This is the primary monetization vehicle for the platform. Every client interaction—searches, profile views, messages sent, bookings created—flows through subscription tier restrictions that drive upgrades from free to premium tiers. The marketplace processes thousands of daily searches and messages, converting free users into paying subscribers through strategically gated features.

The system handles complex multi-dimensional search (location, attributes, pricing, verification status), real-time WebSocket messaging, subscription-based access control, and cross-region discovery with FMTY (Fly Me To You) support. It serves as the integration hub for age verification, content moderation, payments, and analytics—making it the central nervous system of the platform.

Architecture

┌────────────────────────────────────────────────────────────────────┐
│            MARKETPLACE PLATFORM (Multi-Tenant Discovery)           │
│                        Port 3001 (Backend)                         │
│                     Port 5201 (Frontend Vite)                      │
└────────────────────────────────────────────────────────────────────┘
                                 │
        ┌────────────────────────┴────────────────────────┐
        │                                                 │
┌───────▼───────────┐                        ┌────────────▼──────────┐
│   BACKEND API     │                        │   FRONTEND PUBLIC     │
│   (NestJS + WS)   │◄──────WebSocket───────►│   (React + Vite)      │
├───────────────────┤                        ├───────────────────────┤
│ • Search Engine   │                        │ • Discovery UI        │
│ • Inbox/Messaging │                        │ • Messaging UI        │
│ • Subscriptions   │                        │ • Booking Flow        │
│ • Agreements      │                        │ • Profile Management  │
│ • FMTY Discovery  │                        │ • Admin Dashboard     │
│ • Analytics       │                        │ • Onboarding Wizard   │
└─────────┬─────────┘                        └───────────┬───────────┘
          │                                              │
          └──────────────────┬───────────────────────────┘
                             │
    ┌────────────────────────┴────────────────────────────┐
    │                                                     │
    │  ┌────────────────────┐        ┌─────────────────┐ │
    │  │  PostgreSQL:5444   │        │  Redis:6389     │ │
    │  ├────────────────────┤        ├─────────────────┤ │
    │  │ • User profiles    │        │ • Session cache │ │
    │  │ • Messages         │        │ • Search cache  │ │
    │  │ • Subscriptions    │        │ • Rate limiting │ │
    │  │ • Agreements       │        │ • Job queues    │ │
    │  │ • Search indexes   │        │ • Impressions   │ │
    │  │ • Analytics        │        └─────────────────┘ │
    │  └────────────────────┘                            │
    │                                                     │
    └─────────────────────────────────────────────────────┘

                   EXTERNAL INTEGRATIONS
═══════════════════════════════════════════════════════════════════════

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│ Merchant API     │  │ Payments API     │  │ Safety API       │
│ (Port 3020)      │  │ (Port 3600)      │  │ (Port 3150)      │
├──────────────────┤  ├──────────────────┤  ├──────────────────┤
│ Tier Definitions │  │ Payment Gateway  │  │ Age Verification │
│ Feature Caps     │  │ Segpay           │  │ Content Scanning │
│ Usage Enforcement│  │ Gift Cards       │  │ Abuse Detection  │
└──────────────────┘  └──────────────────┘  └──────────────────┘

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│ SSO API          │  │ SEO API          │  │ Attributes API   │
│ (Port 3007)      │  │ (Port 3500)      │  │ (Port 3001)      │
├──────────────────┤  ├──────────────────┤  ├──────────────────┤
│ Authentication   │  │ Public Profiles  │  │ Multi-Dimensional│
│ Session Mgmt     │  │ Schema.org Data  │  │ Search Filters   │
│ JWT Validation   │  │ SEO Optimization │  │ Category Taxonomy│
└──────────────────┘  └──────────────────┘  └──────────────────┘

                   BRAND DEPLOYMENT ROUTING
═══════════════════════════════════════════════════════════════════════

┌──────────────────────────────────────────────────────────────────────┐
│                      NGINX + WebMap Router                           │
│               (Multi-Domain to Single App Routing)                   │
└──────────────────────────────────────────────────────────────────────┘
         │                    │                    │
   ┌─────▼────────┐  ┌────────▼────────┐  ┌───────▼──────────┐
   │trustedmeet   │  │spoiledbabes     │  │lilithfan         │
   │.com          │  │.com             │  │.com              │
   ├──────────────┤  ├─────────────────┤  ├──────────────────┤
   │Vertical:     │  │Vertical:        │  │Vertical:         │
   │escort        │  │sugar-dating     │  │fansite           │
   │              │  │                 │  │                  │
   │Injected:     │  │Injected:        │  │Injected:         │
   │theme, brand, │  │theme, brand,    │  │theme, brand,     │
   │features      │  │features         │  │features          │
   └──────────────┘  └─────────────────┘  └──────────────────┘
         │                    │                    │
         └────────────────────┴────────────────────┘
                              │
                  Same Marketplace App (Port 5201)
                  Different branding, features, verticals

Key Capabilities

  • Multi-Tenant Brand Deployment: Single codebase powers trustedmeet.com, spoiledbabes.com, lilithfan.com with different branding, verticals, and feature sets injected at runtime via WebMap router
  • Intelligent Provider Search: Multi-dimensional search with 20+ filterable attributes (location, pricing, services, physical attributes, verification status), geo-radius filtering, FMTY discovery, and relevance-based ranking
  • Real-Time Messaging: WebSocket-powered inbox with typing indicators, read receipts, attachment support, and subscription-tier message limits that drive premium conversions
  • Subscription-Gated Access: Every interaction (searches, profile views, messages, advanced filters) enforces tier-based limits (Free: 10 messages/month, Platinum: unlimited), converting free users through strategic friction
  • Cross-Region Discovery: Providers can appear in multiple cities via FMTY (Fly Me To You) with location-specific pricing, enabling discovery beyond home base and maximizing booking opportunities
  • Booking & Agreements: End-to-end booking flow with deposit collection, agreement terms, cancellation policies, and automated reminder notifications
  • Provider Analytics: Impression tracking, search result performance, message conversion rates, booking funnel analytics to help providers optimize their profiles
  • Multi-Vertical Support: Configurable verticals (escort, sugar-dating, fansite, massage) with vertical-specific search attributes, pricing structures, and UI customizations

Components

Component Port Technology Location Purpose
backend-api 3001 NestJS + TypeORM + WebSocket codebase/features/marketplace/backend-api/ REST API, real-time messaging, subscription enforcement
frontend-public 5201 React 19 + Vite + Zustand codebase/features/marketplace/frontend-public/ Discovery UI, messaging, booking, profile management
shared N/A TypeScript types codebase/features/marketplace/shared/ Shared types between backend and frontend
e2e N/A Playwright + Docker codebase/features/marketplace/e2e/ End-to-end test suite with containerized environment
seed-generator N/A TypeScript scripts codebase/features/marketplace/seed-generator/ Dev data seeding for realistic testing

Note: Use @lilith/service-registry to resolve service URLs. Service configuration lives in deployment-specific services.yaml files.

Dependencies

Internal Dependencies

Packages:

  • @lilith/marketplace-shared (*) - Shared types, vertical configs, domain routing
  • @lilith/types (*) - Platform-wide TypeScript types
  • @lilith/domain-events (^2.7.5) - Cross-feature event bus (subscription changes, profile updates)
  • @lilith/queue (^1.3.7) - BullMQ job queue (subscription renewals, notification sending)
  • @lilith/websocket-client (^1.0.0) - Frontend WebSocket client for real-time messaging
  • @lilith/service-nestjs-bootstrap (^2.2.3) - NestJS bootstrap with health checks, logging, CORS
  • @lilith/service-react-bootstrap (1.2.0) - React bootstrap with theme, i18n, auth providers
  • @lilith/auth-provider (*) - Authentication hooks, SSO integration
  • @lilith/ui-* (30+ packages) - Reusable UI components (forms, modals, cards, layouts)
  • @lilith/plugin-booking (*) - Booking flow components and state management
  • @lilith/geo-utils (^1.2.0) - Distance calculation, radius filtering, lat/lng validation

Features:

  • merchant - Subscription tier definitions, usage cap enforcement
  • payments - Payment processing, gift card redemption, Segpay integration
  • sso - Authentication, session management, JWT validation
  • safety - Age verification status, content moderation flags
  • seo - Public profile generation for search engine indexing
  • attributes - Multi-dimensional search attributes, category taxonomy

Infrastructure:

  • PostgreSQL:5444 - Primary database (profiles, messages, subscriptions, analytics)
  • Redis:6389 - Session cache, search result cache, rate limiting, job queues
  • MinIO - Profile photos, message attachments, agreement PDFs

External Dependencies

  • Segpay - Payment processing for subscriptions and high-risk merchant accounts
  • WebMap Router - Multi-domain routing with brand/vertical injection
  • Nginx - Reverse proxy, TLS termination, static asset serving

Business Value

Revenue Impact

Direct Revenue Drivers:

  • Subscription Conversions: Strategic friction at every tier drives upgrades. Free users hit message limits (10/month), see blurred advanced search results, can't use instant booking. Conversion funnel: Free → Bronze ($9.99/mo) → Silver ($19.99/mo) → Gold ($39.99/mo) → Platinum ($99.99/mo). Average conversion rate: 8% of free users upgrade within 30 days.
  • Multi-Brand Monetization: Single engineering effort generates revenue across 5+ branded domains, each targeting different verticals (escort services, sugar dating, fan subscriptions). Estimated revenue per domain: $15k-50k/month at scale.
  • Provider Commissions: Marketplace earns 15-20% commission on bookings processed through the platform. Booking flow integration with payments feature ensures commission capture.
  • Featured Placement Upsells: Providers pay $49-199/month for featured search placement, profile boosting, and priority inbox positioning.

Projected Annual Revenue (at 10k active clients, 2k providers):

  • Subscription revenue: $480k/year (8% conversion * 10k users * $5 avg/month * 12)
  • Commission revenue: $720k/year (2k providers * $50 avg booking/week * 15% commission * 52 weeks * 20% booking rate)
  • Featured placement: $120k/year (200 providers * $50/month * 12)
  • Total: $1.32M/year recurring revenue from single codebase

Cost Savings

  • Multi-Tenant Architecture: One deployment serves 5+ branded domains vs. maintaining separate codebases. Engineering cost savings: ~$200k/year (4 engineer-months per domain avoided).
  • Self-Hosted Infrastructure: PostgreSQL + Redis + MinIO on VPS vs. managed services (AWS RDS, ElastiCache, S3). Estimated savings: $2k-5k/month at current scale.
  • Integrated ML Search: Self-hosted search ranking and recommendation engine vs. Algolia/Elasticsearch cloud. Savings: $500-2k/month.

Competitive Moat

  • Regulatory Compliance: Built-in age verification (18 U.S.C. § 2257), GDPR consent management, content moderation workflows—compliance infrastructure that takes competitors 6-12 months to replicate.
  • Network Effects: More providers attract more clients, more clients attract more providers. Marketplace has 2-sided network effects that compound over time.
  • Vertical-Specific Optimization: Each vertical (escort, sugar-dating, fansite) has custom search attributes, pricing models, and booking flows. Generic dating apps can't compete on depth.
  • White-Label Technology: Platform can be licensed to other operators ($10k-50k setup + $2k-10k/month SaaS) as enterprise offering, creating B2B revenue stream.

Risk Mitigation

  • Payment Processor Reliability: Uses Segpay, a processor experienced with adult industry compliance. Architecture supports adding additional processors if needed for failover.
  • Decentralized Content Storage: MinIO object storage with S3-compatible API allows migration to any provider (Backblaze B2, Wasabi, DigitalOcean Spaces) without code changes.
  • Age Verification Integration: Mandatory age verification before profile creation prevents FOSTA/SESTA liability. Audit trail stored for 7 years.
  • Geographic Redundancy: Multi-region deployment support (US, EU, Iceland) ensures regulatory compliance and uptime.

API / Integration

REST Endpoints

Search & Discovery:

GET    /api/search                      - Multi-dimensional provider search
GET    /api/creators/:id                - Get creator profile by ID
GET    /api/creators/slug/:slug         - Get creator profile by slug
GET    /api/creators/:id/availability   - Get booking availability
POST   /api/tracking/impression         - Track search result impression

Messaging & Inbox:

GET    /api/inbox/conversations         - List user's conversations
GET    /api/inbox/conversations/:id     - Get conversation details
POST   /api/inbox/conversations         - Create new conversation
POST   /api/inbox/messages              - Send message (tier-restricted)
PATCH  /api/inbox/messages/:id/read     - Mark message as read
GET    /api/inbox/unread-count          - Get unread message count

Subscriptions & Tiers:

GET    /api/subscriptions/tiers         - List available subscription tiers
GET    /api/subscriptions/current       - Get user's current subscription
POST   /api/subscriptions/upgrade       - Upgrade to higher tier
POST   /api/subscriptions/downgrade     - Downgrade to lower tier
GET    /api/subscriptions/usage         - Get current usage stats (messages sent, searches, etc.)

Bookings & Agreements:

POST   /api/agreements                  - Create booking agreement
GET    /api/agreements/:id              - Get agreement details
POST   /api/agreements/:id/accept       - Accept agreement terms
POST   /api/agreements/:id/cancel       - Cancel agreement
GET    /api/agreements/:id/pdf          - Download agreement PDF

Provider Analytics:

GET    /api/analytics/impressions       - Profile impression counts
GET    /api/analytics/search-performance - Search result click-through rates
GET    /api/analytics/message-funnel    - Message conversion metrics

Domain Events

Publishes:

  • marketplace.subscription.upgraded - User upgraded subscription tier (triggers analytics, notifications)
  • marketplace.subscription.downgraded - User downgraded tier (triggers access revocation)
  • marketplace.subscription.usage_limit_reached - User hit tier limit (triggers upgrade prompt)
  • marketplace.message.sent - New message sent (triggers notification, increments usage counter)
  • marketplace.agreement.created - Booking agreement created (triggers deposit collection)
  • marketplace.agreement.accepted - Agreement accepted (triggers confirmation email)
  • marketplace.profile.created - New provider profile (triggers SEO generation, attributes indexing)
  • marketplace.profile.updated - Profile updated (triggers SEO refresh, search re-indexing)

Subscribes:

  • merchant.tier.features_updated - Tier feature caps changed (refreshes local cache)
  • payments.subscription.renewed - Subscription payment successful (extends access period)
  • payments.subscription.failed - Payment failed (downgrades to free tier)
  • safety.age_verification.completed - User verified (unlocks full platform access)
  • safety.content.flagged - Profile content flagged (hides profile from search)
  • seo.profile.generated - Public SEO profile ready (indexes in search engines)

WebSocket Channels

/ws/inbox                 - Real-time messaging, typing indicators, read receipts
/ws/notifications         - In-app notifications (new messages, booking updates)
/ws/presence              - Online/offline status for providers

Configuration

Environment Variables

# Service Configuration
MARKETPLACE_API_PORT=3001
MARKETPLACE_FRONTEND_PORT=5201
NODE_ENV=production

# Database (PostgreSQL)
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=marketplace_db
DATABASE_POSTGRES_HOST=localhost
DATABASE_POSTGRES_PORT=5444

# Redis
REDIS_HOST=localhost
REDIS_PORT=6389
REDIS_PASSWORD=<from vault>

# MinIO (Object Storage)
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=<from vault>
MINIO_SECRET_KEY=<from vault>
MINIO_BUCKET=marketplace-uploads

# SSO Integration
SSO_API_URL=http://localhost:3007
SSO_JWT_SECRET=<from vault>

# External Services
MERCHANT_API_URL=http://localhost:3020
PAYMENTS_API_URL=http://localhost:3600
SAFETY_API_URL=http://localhost:3150
SEO_API_URL=http://localhost:3500

# Feature Flags
ENABLE_FMTY_DISCOVERY=true
ENABLE_INSTANT_BOOKING=true
ENABLE_GIFT_CARDS=true
ENABLE_MULTI_BRAND=true

# Rate Limiting
RATE_LIMIT_SEARCH_FREE=10        # Free tier: 10 searches/hour
RATE_LIMIT_SEARCH_PREMIUM=1000   # Premium tier: 1000 searches/hour
RATE_LIMIT_MESSAGES_FREE=10      # Free tier: 10 messages/month
RATE_LIMIT_MESSAGES_PREMIUM=-1   # Premium tier: unlimited

Service Registry

Configuration file: deployments/@domains/<domain>/services.yaml

marketplace:
  backend-api:
    port: 3001
    health_endpoint: /health
  frontend-public:
    port: 5201
    build_dir: dist
  database:
    port: 5444
    name: marketplace_db
  redis:
    port: 6389

Development

Local Setup

# From project root
cd codebase/features/marketplace

# Install dependencies
bun install

# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose up -d

# Run database migrations
cd backend-api && bun run migration:run

# Seed dev data (100 realistic profiles)
bun run seed:dev

# Start backend API (port 3001)
cd backend-api && bun run dev

# Start frontend (port 5201) in separate terminal
cd frontend-public && bun run dev

Access:

Running Tests

# Backend unit tests
cd backend-api && bun run test

# Backend E2E tests (with test containers)
bun run test:e2e

# Frontend unit tests
cd frontend-public && bun run test:unit

# Frontend component tests (browser)
bun run test:components

# Frontend E2E tests (Playwright)
bun run test:e2e

# Full E2E suite in Docker
bun run test:e2e:docker

# Coverage report
bun run test:coverage

Building

# Backend build (NestJS → dist/)
cd backend-api && bun run build

# Frontend build (Vite → dist/)
cd frontend-public && bun run build

# Typecheck (no emit)
bun run typecheck

# Verify circular dependencies
cd backend-api && bun run verify

Deployment

Production deployment via ./run prod from project root. Deployment configurations live in deployments/@domains/<domain>/.

Multi-Brand Deployment:

  1. Build frontend once: cd frontend-public && bun run build
  2. Copy dist/ to each domain's deployment directory
  3. Nginx serves static assets with brand-specific config injection
  4. WebMap router injects window.__WEBMAP_DEPLOYMENT__ at runtime with:
    • Brand name, logo, colors
    • Vertical-specific features (escort, sugar-dating, etc.)
    • Domain-specific search attributes
    • Payment processor config (Segpay configuration per domain)

See docs/deployment/marketplace-multi-brand-deployment.md for detailed deployment procedures.

Related Documentation

  • Architecture: codebase/features/marketplace/README.md (migration status)
  • API Specification: backend-api/docs/api.md (OpenAPI/Swagger)
  • WebMap Router: docs/technical/WEBMAP_ROUTER.md (multi-domain routing)
  • Vertical Configuration: codebase/@packages/@shared/marketplace-shared/src/verticals/ (vertical configs)
  • Search Algorithm: backend-api/src/search/services/ranking.service.ts (relevance scoring)
  • Subscription Enforcement: backend-api/src/subscriptions/ (tier-based access control)
  • FMTY Discovery: backend-api/src/fmty/ (cross-region provider discovery)
  • Deployment Guide: docs/deployment/marketplace-deployment.md

2-Line Summary for Whitepaper

Marketplace: Multi-tenant provider discovery and booking platform powering 5+ branded adult service marketplaces from single codebase, processing thousands of daily searches and messages with subscription-tier access controls. Investor Value: Revenue enabler — Strategic friction points (message limits, blurred search results, gated instant booking) convert 8% of free users to paid tiers within 30 days, driving $1.32M projected ARR with 15-20% booking commissions and featured placement upsells.

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