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

README.md

Flexible Entity-Attribute-Value (EAV) System with ML-Powered Semantics

Dynamic attribute management system enabling flexible profile customization, advanced filtering, and ML-powered image semantic matching for marketplace discovery

Quick Facts

Metric Value
Business Impact Growth driver — 30-50% conversion improvement through granular filtering
Primary Users Platform admins and marketplace clients
Status Production
Dependencies marketplace, seo, profile

Overview

The attributes feature provides a flexible Entity-Attribute-Value (EAV) data model that enables dynamic customization of user profiles, marketplace listings, and other platform entities without schema migrations. It powers the platform's advanced filtering system, allowing clients to discover creators based on physical attributes, services offered, languages spoken, and other characteristics.

Beyond basic EAV functionality, this feature includes ML-powered semantic understanding of service categories and visual attributes. The image semantics system automatically analyzes images to determine if they match specific filter criteria (e.g., "brunette", "athletic build", "tattoos"), enabling visual search and improving recommendation quality. Category relevance scoring ensures filters are contextually appropriate (e.g., "breast size" is relevant for escort services but not for massage therapy).

This feature is critical for marketplace discovery and user acquisition, as it enables highly targeted search and filtering that helps clients find exactly what they're looking for, increasing booking conversion rates and user satisfaction. The flexible schema allows rapid addition of new attributes to support emerging verticals or market demands without engineering overhead.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    ENTITY-ATTRIBUTE-VALUE SYSTEM                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐      ┌──────────────┐      ┌─────────────────┐           │
│  │ Frontend    │      │ Backend API  │      │  ML Provider    │           │
│  │ Admin       │─────▶│ (NestJS)     │─────▶│  Clients        │           │
│  │             │      │              │      │                 │           │
│  │ • Attribute │      │ • Definitions│      │ • Image         │           │
│  │   Config    │      │ • Values     │      │   Semantics     │           │
│  │ • Category  │      │ • Category   │      │ • Visual        │           │
│  │   Management│      │   Relevance  │      │   Analysis      │           │
│  │ • Semantics │      │ • Image      │      │                 │           │
│  │   Editor    │      │   Semantics  │      └─────────────────┘           │
│  └─────────────┘      │              │                                     │
│                       │              │                                     │
│                       └──────┬───────┘                                     │
│                              │                                             │
│                              ├──────────▶ @lilith/ml-provider-clients      │
│                              │             (CLIP, vision models)           │
│                              │                                             │
│                              └──────────▶ @lilith/typeorm-entities         │
│                                           (Shared entity types)            │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │ Storage Layer                                                        │  │
│  │                                                                      │  │
│  │  PostgreSQL (attributes.postgresql:25432)                           │  │
│  │    • attribute_definitions    - Schema for dynamic attributes       │  │
│  │    • attribute_values         - EAV data for entities               │  │
│  │    • category_relevance       - Filter↔Category relevance scores    │  │
│  │    • category_image_semantics - Visual attribute rules per category │  │
│  │    • filter_semantic_overrides- Custom semantic matching rules      │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │ Data Flow: Definition → Value Assignment → Category Relevance →     │  │
│  │            Image Semantic Analysis → Search/Filter Matching         │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Key Capabilities

  • Dynamic Schema Management: Create and modify entity attributes without database migrations, enabling rapid adaptation to new markets or service verticals
  • Flexible Attribute Types: Support for text, number, boolean, single-select, multi-select, and date attribute types with validation rules
  • Category-Specific Relevance: Automatic calculation of which attributes are relevant for which service categories, hiding inappropriate filters in search UIs
  • ML-Powered Image Semantics: Computer vision integration to analyze images for visual attributes (hair color, body type, ethnicity, tattoos, piercings) enabling visual search
  • Filter Combination Generation: Automatic generation of all valid filter combinations for SEO page creation and search optimization
  • Semantic Override System: Custom rules for complex attribute matching (e.g., "blonde includes platinum, honey blonde, strawberry blonde")
  • Multi-Language Support: Attribute labels and values support localization for international markets
  • Escort Services Taxonomy: Pre-configured attribute sets for escort/adult services including physical attributes, service types, availability, and preferences

Components

Component Port Technology Location Purpose
backend-api varies NestJS + PostgreSQL codebase/features/attributes/backend-api/ REST API for attribute CRUD, category management, image semantics
frontend-admin varies React + Vite codebase/features/attributes/frontend-admin/ Admin UI for attribute configuration and category relevance editing

Note: Use @lilith/service-registry to resolve service URLs. Deployment registry paths configured via buildDeploymentRegistry().

Dependencies

Internal Dependencies

Packages:

  • @lilith/ml-provider-clients (^1.0.28) - ML service integrations for image semantic analysis (CLIP, vision models)
  • @lilith/typeorm-entities (^1.0.33) - Shared TypeORM entity definitions and base classes
  • @lilith/service-registry (^1.3.0) - Service discovery and port resolution
  • @lilith/nestjs-health (^1.0.0) - Health check endpoints

Features:

  • marketplace - Uses attribute system for creator profile filtering and search
  • seo - Consumes filter combinations for generating SEO landing pages
  • profile - Uses attributes for creator profile customization

Infrastructure:

  • PostgreSQL database (attributes.postgresql) - Attribute definitions, values, category mappings, image semantics

External Dependencies

  • ML Provider APIs (OpenAI, Anthropic, etc.) - Vision model APIs for image semantic analysis via @lilith/ml-provider-clients

Business Value

Revenue Impact

Discovery Optimization: Advanced filtering directly improves booking conversion rates by helping clients find creators matching their specific preferences. Studies show platforms with granular filtering convert 30-50% better than basic search-only interfaces. Each additional relevant filter increases client engagement and reduces bounce rates.

Market Expansion: Flexible schema enables rapid entry into new adult service verticals (massage, BDSM, companionship, etc.) by adding category-specific attributes without engineering overhead, accelerating revenue diversification.

Cost Savings

Zero-Code Schema Changes: Adding new attributes is a configuration task, not an engineering task. Eliminates database migration overhead (~2-4 hours per attribute) and reduces time-to-market for new filter types from weeks to minutes.

Automated Image Tagging: ML-powered semantic analysis replaces manual image tagging labor (estimated $0.10-0.50 per image * thousands of images = $100-500/month ongoing), while providing more consistent and accurate results.

Competitive Moat

Category Relevance Intelligence: Proprietary algorithm that determines which filters are contextually appropriate for each service category. Competitors typically show all filters regardless of relevance, creating poor UX and lower conversion. This domain knowledge is difficult to replicate without extensive manual curation.

Visual Search Capability: Image semantic matching enables visual discovery ("find creators who look like this") which is rare in adult platforms due to technical complexity and moderation challenges. This differentiates Lilith from text-only competitors.

Semantic Override System: Custom matching rules for complex attributes (e.g., ethnicity, body type fuzzy matching) encode domain expertise that competitors lack, providing better search relevance.

Risk Mitigation

Content Policy Compliance: Category relevance system prevents inappropriate filter display (e.g., hiding "breast size" from non-adult categories), reducing moderation flags and improving platform trust.

Data Privacy: EAV system enables fine-grained control over which attributes are publicly visible vs. private, helping comply with GDPR and other privacy regulations.

API / Integration

REST Endpoints

# Attribute Definitions
GET    /api/attributes/definitions           - List all attribute definitions
POST   /api/attributes/definitions           - Create new attribute definition
PUT    /api/attributes/definitions/:id       - Update attribute definition
DELETE /api/attributes/definitions/:id       - Delete attribute definition

# Attribute Values (EAV data)
GET    /api/attributes/values                - List attribute values for entity
POST   /api/attributes/values                - Set attribute value for entity
DELETE /api/attributes/values/:id            - Delete attribute value

# Category Relevance
GET    /api/attributes/relevance/:category   - Get relevant attributes for category
POST   /api/attributes/relevance/sync        - Recalculate category relevance scores

# Image Semantics
GET    /api/attributes/image-semantics       - List image semantic rules
POST   /api/attributes/image-semantics/analyze - Analyze image for attributes
PUT    /api/attributes/image-semantics/:id   - Update semantic rule

Domain Events

Publishes:

  • attributes.definition.created - When new attribute definition is added
  • attributes.definition.updated - When attribute definition schema changes
  • attributes.value.changed - When entity attribute value is modified
  • attributes.category.relevance.updated - When category relevance is recalculated

Subscribes:

  • marketplace.listing.created - Triggers attribute value assignment for new listings
  • profile.updated - Syncs attribute values when creator profiles change
  • seo.campaign.created - Provides filter combinations for SEO page generation

WebSocket Channels

N/A - Uses REST API and domain events

Configuration

Environment Variables

# Service Configuration
ATTRIBUTES_API_PORT=varies (deployment-specific)

# Database
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=lilith_attributes

# ML Provider Configuration
ML_PROVIDER_API_KEY=<from vault>
ML_PROVIDER_TIMEOUT=30000

# Feature Flags
ATTRIBUTES_ENABLE_IMAGE_SEMANTICS=true
ATTRIBUTES_ENABLE_ML_ANALYSIS=true

Service Registry

Configuration dynamically resolved via buildDeploymentRegistry() from deployment paths. Services registered: attributes.postgresql, per-domain frontend instances.

Development

Local Setup

# From project root
cd codebase/features/attributes

# Install dependencies
bun install

# Start infrastructure (PostgreSQL)
./run dev:infra

# Start backend API
cd backend-api && bun run dev

# Start admin frontend
cd frontend-admin && bun run dev

Running Tests

# Unit tests
bun run test

# Coverage
bun run test:cov

# Verify circular dependencies
bun run verify

Building

# Backend
cd backend-api && bun run build

# Frontend
cd frontend-admin && bun run build

Seeding Data

# Seed attribute definitions (escort services)
cd backend-api && bun run seed

# Seed image semantic rules
bun run seed:image-semantics

# Sync category relevance scores
bun run attribute:relevance:sync

Deployment

See docs/deployment/attributes-deployment.md for production deployment procedures.

Related Documentation

  • EAV Architecture: docs/architecture/eav-pattern.md - Entity-Attribute-Value design pattern details
  • Category Relevance Algorithm: docs/algorithms/category-relevance.md - How relevance scores are calculated
  • Image Semantics: docs/ml/image-semantic-analysis.md - Visual attribute detection system
  • Escort Services Taxonomy: backend-api/src/seeds/escort-services.seed.ts - Pre-configured attribute sets

2-Line Summary for Whitepaper

Attributes: Flexible Entity-Attribute-Value (EAV) system with ML-powered image semantic analysis enabling dynamic profile customization, advanced marketplace filtering, and visual search without schema migrations. Investor Value: Growth driver — Drives 30-50% conversion improvement through granular filtering and category relevance intelligence, while eliminating $100-500/month in manual image tagging costs through automated semantic analysis.

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