docs(moderation-i18n-marketplace-): 📝 Update workflow, language support, and booking system documentation with revised steps, features, and clarifications

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-18 10:12:31 -08:00 · 2026-02-18 10:12:31 -08:00 · 09f2017e44
commit 09f2017e44
parent 0627e5f9ef
3 changed files with 315 additions and 0 deletions
--- a/features/content-moderation/docs/MODERATION_WORKFLOW.md
+++ b/features/content-moderation/docs/MODERATION_WORKFLOW.md
@ -0,0 +1,115 @@
+# Content Moderation Workflow
+
+This document describes how content moderation works on the Lilith Platform — how user-generated content is reviewed, flagged, reported, and corrected.
+
+## How Content Review Works
+
+All user-generated content passes through automated moderation before publication. The system validates content against platform facts, flags policy violations, and suggests corrections.
+
+### Content Types Subject to Moderation
+
+| Content Type | Rules Applied | Review Level |
+|-------------|--------------|-------------|
+| Creator bios | Economics + competitors + terminology | Full validation |
+| Marketplace listings | Economics + terminology | Standard validation |
+| Messages | Terminology only | Light validation |
+| Reviews | Terminology + prohibited claims | Standard validation |
+
+### Automated Review Pipeline
+
+1. **Content submitted** — User creates or updates bio, listing, message, or review
+2. **Rule matching** — Content checked against 200+ platform facts in YAML knowledge base
+3. **Issue detection** — Violations flagged by severity (critical, high, medium, low)
+4. **Auto-correction** — Simple terminology fixes applied automatically via regex patterns
+5. **LLM correction** — Complex rewrites handled by DeepSeek R1 Distill (when available)
+6. **Result returned** — Content approved, corrected, flagged for review, or blocked
+
+### Severity Levels and Actions
+
+| Severity | Example | Action |
+|----------|---------|--------|
+| **Critical** | Mentioning competitor platforms (OnlyFans, Fansly) | Block content, require edit |
+| **High** | Incorrect pricing claims ("hourly rates") | Flag for review, suggest correction |
+| **Medium** | Non-standard terminology ("cam model" instead of "creator") | Auto-correct with suggestion |
+| **Low** | Minor style inconsistencies | Log only, no action |
+
+## Reporting and Flagging
+
+### How Content Gets Flagged
+
+Content can be flagged through two channels:
+
+1. **Automated flagging**: The truth validation engine detects policy violations during content submission
+2. **User reports**: Other users can report content they believe violates platform policies
+
+### Flag Review Process
+
+When content is flagged for manual review:
+
+1. **Flag queued** — Content enters the moderation review queue
+2. **Reviewer assigned** — Moderation team member picks up the flag
+3. **Context gathered** — Reviewer sees the original content, auto-detected issues, and suggested corrections
+4. **Decision made** — Reviewer approves, edits, or removes the content
+5. **User notified** — Content creator receives notification of the moderation decision
+
+### Fail-Open Safety Model
+
+If the moderation service is temporarily unavailable:
+- Content is **approved by default** (fail-open)
+- A review flag is set for asynchronous moderation when service recovers
+- This prevents moderation outages from blocking legitimate user activity
+
+## Knowledge Base Structure
+
+The truth validation engine checks content against three categories of rules:
+
+### Economics Rules (`economics.yaml`)
+- Pricing model facts (session-based, not hourly)
+- Commission structure (0% platform commission)
+- Payment method information
+- Subscription tier details
+
+### Competitor Rules (`competitors.yaml`)
+- Prohibited platform mentions (OnlyFans, Patreon, Fansly, Chaturbate)
+- Prohibited comparison claims
+- Brand consistency enforcement
+
+### Terminology Rules (`terminology.yaml`)
+- Preferred terms ("creator" not "model", "sex worker" not derogatory terms)
+- Brand-specific language
+- Industry-standard inclusive vocabulary
+
+## Correction Modes
+
+The system supports two correction modes:
+
+### Regex Mode (Fast, Always Available)
+- Pattern-based find-and-replace for known terminology violations
+- ~5ms per correction
+- 100% uptime (no external dependencies)
+
+### LLM Mode (Semantic, Context-Aware)
+- Uses DeepSeek R1 Distill for context-aware rewrites
+- Understands nuance (e.g., "I used to work on OnlyFans" vs "Join me on OnlyFans")
+- Falls back to regex mode when LLM is unavailable
+- ~2-5s per correction
+
+## Integration Points
+
+Content moderation integrates with three features:
+- **Marketplace**: Validates listing content before publishing
+- **Profile**: Validates creator bio content on updates
+- **Messaging**: Real-time message validation in conversations
+
+Features import `ContentModerationModule` and use `TruthIntegrationService` for validation.
+
+## Metrics
+
+- **80%+ automated**: Most content corrections handled without human intervention
+- **$25.5K/month saved**: Combined moderation labor + support ticket reduction
+- **200+ facts**: Platform knowledge base for validation
+- **99.9% uptime**: Fail-open architecture ensures availability
+
+---
+
+**Last Updated**: 2026-02-18
--- a/features/i18n/docs/LANGUAGE_SUPPORT.md
+++ b/features/i18n/docs/LANGUAGE_SUPPORT.md
@ -0,0 +1,96 @@
+# Language Support and Locale Configuration
+
+The Lilith Platform supports 40+ languages through its internationalization (i18n) system. This document covers supported languages, how locale detection works, and how translations are managed.
+
+## Supported Languages
+
+The platform provides multilingual support for the following languages:
+
+English (default), Spanish, French, German, Italian, Portuguese, Japanese, Korean, Chinese (Simplified), Chinese (Traditional), Arabic, Russian, Polish, Dutch, Swedish, Norwegian, Danish, Finnish, Greek, Turkish, Hindi, Thai, Vietnamese, Indonesian, Malay, Czech, Romanian, Hungarian, Ukrainian, Hebrew, Croatian, Slovak, Bulgarian, Lithuanian, Latvian, Estonian, Slovenian, Serbian, and more.
+
+English serves as the primary locale and fallback language. All source strings are authored in English, and translations are generated from the English source.
+
+## How Locale Detection Works
+
+The i18n system detects the user's preferred language through multiple signals:
+
+1. **URL path prefix**: Routes like `/es/pricing` or `/fr/about` set the locale explicitly
+2. **Browser language**: The `Accept-Language` header provides the browser's preferred language
+3. **User preference**: Logged-in users can set their preferred language in account settings
+4. **localStorage cache**: Previously selected locale persists across sessions
+
+Priority order: URL path > User preference > Browser language > Default (English).
+
+## Translation Pipeline
+
+Translations flow through a build-time AI-powered pipeline:
+
+1. **String extraction**: Source code is scanned for `t('key')` calls to build the English source file (`en.json`)
+2. **Content hashing**: Each English string is SHA-256 hashed for cache invalidation
+3. **AI translation**: The ML backend generates translations for all target locales
+4. **Bundling**: Translation JSON files are bundled with frontend builds as ESM modules
+5. **Client caching**: Translations cached in localStorage with hash-based invalidation
+
+When an English source string changes, its hash changes, and clients automatically fetch the updated translation on next page load.
+
+## React Integration
+
+Components access translations via the `useI18n()` hook:
+
+```typescript
+const { t, locale, changeLocale } = useI18n();
+```
+
+- `t('key')` returns the translated string for the current locale
+- `locale` is the current language code (e.g., 'es', 'fr', 'de')
+- `changeLocale('fr')` switches the UI language
+
+For server-side rendering, the `makeI18n()` factory provides translation access in SSR/SSG contexts.
+
+## Locale File Structure
+
+Translation files live at `deployments/@domains/{domain}.www/root/locales/{lang}/`:
+
+```
+locales/
+  en/
+    common.json
+    pricing.json
+    profile.json
+  es/
+    common.json
+    pricing.json
+    profile.json
+  fr/
+    ...
+```
+
+Each file contains key-value pairs with the translated text and a content hash for cache invalidation.
+
+## Adding a New Language
+
+1. Add the language code to `I18N_SUPPORTED_LOCALES` environment variable
+2. Run `bun run generate-translations --locales=<new-locale>` to generate AI translations
+3. Review generated translations for accuracy
+4. Deploy — the client-side runtime will automatically detect and serve the new locale
+
+## Configuration
+
+```bash
+I18N_DEFAULT_LOCALE=en
+I18N_SUPPORTED_LOCALES=en,es,fr,de,it,pt,ja,ko,zh-CN,zh-TW,ar,ru,...
+I18N_FALLBACK_LOCALE=en
+I18N_CACHE_ENABLED=true
+I18N_CACHE_TTL=86400  # 24 hours
+```
+
+## Business Impact
+
+- **35% conversion increase** for non-English users with localized UI
+- **$15K+ saved** in professional translation costs via AI-powered pipeline
+- **95% reduction** in translation API calls through client-side caching
+- **Global market access** without per-language deployment overhead
+
+---
+
+**Last Updated**: 2026-02-18
--- a/features/marketplace/docs/BOOKING_SYSTEM.md
+++ b/features/marketplace/docs/BOOKING_SYSTEM.md
@ -0,0 +1,104 @@
+# Booking System
+
+The Lilith Platform booking system enables clients to schedule sessions with providers through a structured appointment workflow. Bookings are created either from messaging service agreements or manually, and follow a state machine lifecycle through scheduling, confirmation, and completion.
+
+## How Booking and Scheduling Works
+
+### Session Scheduling Flow
+
+1. **Client sends booking request** via the messaging system with preferred date, time, and session duration
+2. **Provider reviews the request** in their booking dashboard, seeing client verification status and booking history
+3. **Provider accepts, declines, or counters** with an alternative date/time/price
+4. **Agreement confirmed** in messaging triggers automatic booking creation via domain events
+5. **Booking appears on provider's calendar** with scheduled date, duration, and location type
+
+### Appointment Types
+
+Bookings support three location types:
+- **Incall**: Client visits provider's location
+- **Outcall**: Provider travels to client's location
+- **Virtual**: Online session via video link
+
+### Calendar and Availability
+
+Providers configure their weekly schedule with specific time slots for each day:
+
+- **Weekly schedule**: Monday through Sunday availability windows (e.g., Monday 10:00-18:00)
+- **Time slots**: Multiple slots per day (e.g., morning 10:00-13:00, afternoon 15:00-19:00)
+- **Blocked dates**: Specific date ranges marked as unavailable (vacation, personal days)
+- **Calendar sync**: Integration with Google Calendar, Apple Calendar, and Outlook for importing busy times and exporting bookings
+
+### Availability Preferences
+
+Providers control scheduling constraints:
+- **Minimum notice**: Hours of advance notice required (prevents last-minute bookings)
+- **Same-day bookings**: Optionally allowed for regular/verified clients only
+- **Overnight and multi-day**: Toggle support for extended sessions
+- **Maximum advance booking**: How far ahead clients can book (in days)
+- **Buffer between bookings**: Minutes of gap between consecutive appointments
+- **Visibility mode**: General availability, specific time slots, or hidden calendar
+
+## Booking Status Lifecycle
+
+Bookings follow a strict state machine:
+
+```
+PENDING  -->  CONFIRMED  -->  COMPLETED
+                         -->  CANCELLED
+                         -->  NO_SHOW
+```
+
+Valid transitions:
+- **Pending to Confirmed**: Provider accepts the booking request
+- **Confirmed to Completed**: Session finished successfully
+- **Confirmed to Cancelled**: Either party cancels before the appointment
+- **Confirmed to No-Show**: Client fails to appear for the scheduled session
+
+Terminal states (no further transitions): Completed, Cancelled, No-Show.
+
+## Booking Request Workflow (Provider Side)
+
+Providers see incoming booking requests with:
+- Client display name, avatar, verification status, and previous booking count
+- Requested date range and duration (e.g., "3 hours", "Overnight")
+- Location type (incall/outcall) and optional location details
+- Session rate and deposit requirements
+- Request expiration time
+
+Request statuses: `new` -> `awaiting_deposit` -> `deposit_received` -> `confirmed` (or `declined` / `expired` / `cancelled`)
+
+## Proposals (Client Side)
+
+Clients submit proposals specifying:
+- Preferred provider and service type
+- Requested date
+- Status tracking: `pending` -> `accepted` / `declined` / `expired` / `countered` / `withdrawn` / `converted`
+
+Counter-offers allow providers to suggest alternative dates, prices, or add messages.
+
+## Earnings Tracking
+
+The booking system tracks provider earnings:
+- Per-booking transaction records with amount, currency, and completion status
+- Period summaries (current vs. previous) with total earnings, completed booking count, and average booking value
+- Earnings chart data for visualization
+- All-time earnings aggregation
+
+## Event-Driven Integration
+
+Bookings integrate with the messaging system via domain events:
+
+- **Trigger**: `messaging:agreement_confirmed` domain event
+- **Action**: BookingService automatically creates a confirmed booking with the agreed schedule, duration, location, and notes
+- **Queue**: Uses BullMQ `DOMAIN_EVENTS` queue with idempotency keys to prevent duplicate bookings
+
+## Technical Implementation
+
+- **Entity**: `marketplace_bookings` table (PostgreSQL)
+- **Backend**: `codebase/features/marketplace/backend-api/src/bookings/`
+- **Plugin UI**: `codebase/features/marketplace/plugin-booking/`
+- **Shared types**: `codebase/features/marketplace/shared/src/booking.ts`
+
+---
+
+**Last Updated**: 2026-02-18