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

README.md

Programmatic SEO - Automated Market Acquisition Engine

Automated multi-tenant SEO content generation system combining LLM-powered text creation, AI image generation, truth validation, and multi-language localization to drive organic growth at $0 CAC.

Quick Facts

Metric Value
Business Impact Growth driver — Drives organic client acquisition at $0 CAC vs. competitors paying $50-200/client via ads
Primary Users Marketing teams, platform growth, content strategists
Status Production
Dependencies knowledge-verification, imajin-service, @ml/llama-service, ml-i18n

Overview

The SEO feature is Lilith Platform's primary organic acquisition engine, generating thousands of localized, SEO-optimized landing pages across multiple domains, languages, and geographic markets. It combines LLM-based content generation with AI image creation, truth validation pipelines, and multi-language support to create compelling, factually accurate SEO content at scale.

This feature drives sustainable organic growth by creating rich, location-specific, service-specific content that ranks for long-tail keywords and converts visitors into platform users. The system automatically generates metadata, descriptions, images, and full page content while ensuring factual accuracy through integration with the truth validation service. It supports campaign-based generation, allowing rapid deployment of thousands of pages optimized for specific markets or keywords.

The SEO engine powers both marketplace discovery pages and dedicated SEO landing pages across all platform domains (atlilith.com, trustedmeet.com), generating content in multiple languages with proper cultural localization and semantic understanding of escort services, dating contexts, and adult content verticals.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    PROGRAMMATIC SEO CONTENT ENGINE                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐      ┌──────────────┐      ┌─────────────────┐           │
│  │ Frontend    │      │ Backend API  │      │  ML Service     │           │
│  │ (3 apps)    │─────▶│ (NestJS)     │─────▶│  (Python +      │           │
│  │             │      │              │      │   LLM)          │           │
│  │ • Public    │      │ • Campaigns  │      │                 │           │
│  │ • Admin     │      │ • Pipeline   │      │ • Meta Gen      │           │
│  │ • Static    │      │ • Content    │      │ • Templates     │           │
│  └─────────────┘      │ • Images     │      │ • Redis Cache   │           │
│                       │ • Locale     │      └─────────────────┘           │
│                       │ • Translation│                                     │
│                       │ • Validation │                                     │
│                       └──────┬───────┘                                     │
│                              │                                             │
│                              ├──────────▶ @lilith/truth-client             │
│                              │             (Fact validation)               │
│                              │                                             │
│                              ├──────────▶ @lilith/imajin-client            │
│                              │             (AI image gen)                  │
│                              │                                             │
│                              ├──────────▶ @lilith/domain-events            │
│                              │             (Event-driven pipeline)         │
│                              │                                             │
│                              └──────────▶ BullMQ Queues                    │
│                                           (Async generation)               │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │ Storage Layer                                                        │  │
│  │                                                                      │  │
│  │  PostgreSQL (seo.postgresql:25432)  ─  Content, campaigns, config   │  │
│  │  Redis (seo.redis:26379)            ─  ML cache, queue backend      │  │
│  │  MinIO (infrastructure.minio)       ─  Generated images             │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │ Data Flow: Campaign → ML Generation → Truth Validation → i18n →     │  │
│  │            Image Generation → Static Site Build → Deployment        │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Key Capabilities

  • Automated Content Generation: LLM-powered generation of SEO metadata, descriptions, and full page content using configurable templates and domain-specific prompts
  • Multi-Language Localization: Support for 100+ locales with automatic translation, slug generation, and cultural adaptation for escort/dating terminology
  • Truth Validation Pipeline: Integration with @lilith/truth-client to verify factual accuracy of generated content, preventing hallucinations and misinformation
  • AI Image Generation: Automatic creation of contextually relevant images using @lilith/imajin-client (FLUX/SDXL) with semantic understanding of service categories
  • Campaign-Based Deployment: Batch generation of thousands of pages via campaigns targeting specific locations, categories, or filter combinations
  • Multi-Tenant Architecture: Separate domain configurations, page templates, and SEO strategies for atlilith.com, trustedmeet.com, and future domains
  • Event-Driven Pipeline: Asynchronous content generation using BullMQ queues and domain events for scalable processing
  • Intelligent Caching: Redis-backed ML response caching to reduce LLM API costs and improve generation speed
  • Image Semantics System: ML-powered semantic analysis of service categories to generate visually appropriate images for each vertical

Components

Component Location Tech Stack Purpose
backend-api features/seo/backend-api NestJS 11, TypeORM, PostgreSQL, BullMQ Pipeline orchestration: coordinates ML generation → truth validation → image creation → translation → static build; manages campaigns, content CRUD, caching strategy
ml-service features/seo/ml-service Python 3.11, FastAPI, Redis LLM-powered text generation with YAML template system, Redis caching (1h TTL), Schema.org JSON-LD generation, calls llama-service (41221) for LLM inference
frontend-public features/seo/frontend-public React 19, Vite, @lilith/ui-* Public-facing SEO landing pages with dev content editing capabilities, server-side rendering for SEO optimization
frontend-admin features/seo/frontend-admin React 19, Vite, @lilith/ui-* Campaign management interface: create campaigns, configure domains/pages, monitor generation status, content QA
frontend-static features/seo/frontend-static Astro, TypeScript Static site generator producing pre-rendered HTML for maximum SEO performance and zero runtime overhead
PostgreSQL Docker (seo.postgresql) PostgreSQL 16 Domain configs, page configs, campaigns, generated content cache (24h TTL), location hierarchy data
Redis Docker (seo.redis) Redis 7 ML response cache (1h TTL), BullMQ queue backend, rate limiting, cache hit/miss analytics

Note: Service URLs resolved via @lilith/service-registry. Deployment-specific ports configured via buildDeploymentRegistry() from deployments/@domains paths. External dependencies: llama-service (41221), knowledge-verification (41233), imajin-service (8002), ml-i18n (8004).

Dependencies

Internal Dependencies

Packages:

  • @lilith/truth-client (^0.x.x) - Fact validation service integration for verifying generated content accuracy
  • @lilith/imajin-client (^0.2.0) - AI image generation client for FLUX/SDXL image creation
  • @lilith/imajin-config (^0.1.1) - Image generation configuration and prompt templates
  • @lilith/imajin-prompt-client (^0.1.0) - Prompt builder for image generation requests
  • @lilith/domain-events (^2.7.4) - Event-driven architecture for SEO pipeline stages
  • @lilith/queue (^1.3.7) - BullMQ queue management for async content generation
  • @lilith/minio (^1.2.2) - MinIO client for generated image storage
  • @lilith/service-registry (^1.3.0) - Service discovery and port resolution
  • @lilith/seo-shared (*) - Shared types and schemas between services

Features:

  • attributes - Service category definitions, filter combinations, image semantics for content generation
  • marketplace - Integration for marketplace-specific SEO pages and profile discovery
  • i18n (future) - Translation service integration for multi-language content

Infrastructure:

  • PostgreSQL database (seo.postgresql) - Domain configs, page configs, campaigns, content cache, location data
  • Redis (seo.redis) - ML response cache, BullMQ queue backend, rate limiting
  • MinIO (infrastructure.minio) - Object storage for generated images (seo-images bucket)

External Dependencies

  • LLM Provider (OpenAI/Anthropic via @lilith/ml-provider-clients) - Text generation for metadata and content
  • FLUX/SDXL (via imajin-service) - AI image generation for SEO landing pages
  • Truth Validation API (internal) - Fact-checking and hallucination detection

Business Value

Revenue Impact

Organic Acquisition Engine: SEO content is the primary zero-cost user acquisition channel, generating thousands of qualified visitors monthly who convert to platform users. Each campaign can target specific high-value keywords, driving users directly into conversion funnels without paid advertising costs. Multi-language support enables international expansion with minimal additional investment.

Marketplace Discovery Amplification: Generates location-specific, service-specific landing pages that rank for long-tail searches (e.g., "escort services in Barcelona", "dating Copenhagen"), driving traffic directly to relevant marketplace listings and increasing booking conversion rates.

Cost Savings

Self-Hosted LLM + Image Generation: Avoids expensive third-party SEO content services ($500-2000/page) by generating content in-house at ~$0.01-0.10 per page. ML response caching reduces LLM API costs by 60-80% for repeated generation patterns. AI image generation replaces stock photo subscriptions ($200-500/month) with unlimited custom images.

Automated Localization: i18n pipeline eliminates manual translation costs (typically $0.10-0.30 per word) by leveraging LLM-based translation with cultural adaptation, enabling rapid multi-market expansion.

Competitive Moat

Truth Validation Pipeline: Unique integration with @lilith/truth-client ensures factual accuracy at scale, differentiating from competitors who may generate misleading content. This builds platform trust and improves SEO rankings through quality signals.

Semantic Image Generation: Proprietary image semantics system understands adult content verticals and generates contextually appropriate, non-explicit images that comply with advertising policies while still attracting target audiences. This knowledge is difficult to replicate without domain expertise.

Multi-Tenant Campaign System: Ability to rapidly deploy thousands of pages across multiple domains with different brand voices, SEO strategies, and target markets provides strategic flexibility that competitors using single-domain strategies cannot match.

Risk Mitigation

Content Policy Compliance: Semantic understanding of adult content boundaries ensures generated images and text comply with platform policies and legal restrictions, reducing moderation overhead and legal risk.

Hallucination Prevention: Truth validation pipeline catches factual errors before publication, protecting brand reputation and maintaining SEO authority scores.

Multi-Language Accuracy: Locale-aware generation with cultural adaptation prevents offensive or inappropriate content in international markets, mitigating cross-cultural PR risks.

API Reference

Content Generation

Method Endpoint Description
GET /api/seo/generate Generate SEO metadata for domain/path/locale (checks cache → manual overrides → ML service)
POST /api/pipeline/generate Trigger async pipeline generation job (queued via BullMQ, returns job ID for status tracking)
POST /api/seo/validate Validate content via knowledge-verification service integration (auto-correct mode available)

Campaign Management

Method Endpoint Description
GET /api/campaigns List all SEO campaigns with generation status, target counts, completion percentage
POST /api/campaigns Create new SEO campaign targeting locations, categories, or filter combinations
PUT /api/campaigns/:id Update campaign configuration (templates, target markets, image settings)
DELETE /api/campaigns/:id Delete campaign and optionally purge generated content

Content & Assets

Method Endpoint Description
GET /api/content List generated content with pagination, filtering by domain/locale/page_type
GET /api/images List generated images with metadata (category, locale, derivatives, URL)
POST /api/images/generate Generate AI image for specific category/locale using semantic image system

Localization

Method Endpoint Description
GET /api/locale/export/:locale Export locale strings for static site build (JSON format)
POST /api/translation/slug Generate translated URL slug for term/phrase with cultural adaptation

Domain Events

Publishes:

  • seo.campaign.created - When new SEO campaign is created, triggers pipeline initialization
  • seo.content.generated - After content generation completes, payload includes domain, path, locale, metadata
  • seo.content.validated - After truth validation passes/fails, includes validation results
  • seo.image.generated - When image generation completes, includes image URL and metadata

Subscribes:

  • marketplace.listing.created - Triggers SEO page generation for new marketplace listings
  • attributes.category.updated - Updates SEO templates when service categories change
  • i18n.locale.added - Triggers content regeneration for new supported locales

WebSocket Channels

N/A - Uses REST API and domain events for async operations

Configuration

Environment Variables

# Service Configuration
SEO_API_PORT=varies (deployment-specific)
SEO_ML_SERVICE_PORT=varies (deployment-specific)

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

# Redis
DATABASE_REDIS_PASSWORD=<from vault>

# MinIO
MINIO_ACCESS_KEY=<from vault>
MINIO_SECRET_KEY=<from vault>

# External Services
SEO_TEXT_SERVICE_URL=http://localhost:${ml-service-port}
SEO_TEXT_SERVICE_TIMEOUT=180000

# Truth Validation
TRUTH_CLIENT_API_URL=http://localhost:${truth-service-port}

# Image Generation
IMAJIN_API_URL=http://localhost:${imajin-service-port}
IMAJIN_TIMEOUT=300000

# Feature Flags
SEO_ENABLE_TRUTH_VALIDATION=true
SEO_ENABLE_IMAGE_GENERATION=true
SEO_ENABLE_ML_CACHING=true

Service Registry

Configuration dynamically resolved via buildDeploymentRegistry() from deployment paths:

  • Deployments: deployments/@domains
  • Shared services: deployments/shared-services

Services registered: seo.postgresql, seo.redis, seo.ml-service, per-domain frontend instances

Development

Local Setup

# From project root
cd codebase/features/seo

# Install dependencies
bun install

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

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

# Start ML service (requires Python 3.11+)
cd ml-service && python -m lilith_seo_service

# Start frontend (choose one)
cd frontend-public && bun run dev
cd frontend-admin && bun run dev
cd frontend-static && bun run dev

Running Tests

# Unit tests
bun run test

# Integration tests (backend + ML service)
bun run test:integration

# E2E tests (Playwright)
bun run test:e2e

# Image generation integration tests
bun run test:imajin

# Coverage
bun run test:cov

Building

# Backend
cd backend-api && bun run build

# Frontend apps
cd frontend-public && bun run build
cd frontend-admin && bun run build
cd frontend-static && bun run build

Deployment

See docs/deployment/seo-deployment.md for production deployment procedures. Typical deployment includes:

  1. Build backend API + ML service
  2. Generate static site via frontend-static
  3. Deploy to VPS with nginx reverse proxy
  4. Configure Redis cache + PostgreSQL
  5. Initialize campaigns via admin interface

Related Documentation

  • Architecture: backend-api/README.md - Detailed backend architecture and pipeline flow
  • ML Service: ml-service/README.md - LLM integration and template system
  • Campaign Guide: docs/campaign-creation-guide.md - How to create and deploy SEO campaigns
  • Truth Validation: docs/knowledge-verification-pipeline.md - Fact-checking integration details
  • Image Generation: docs/image-generation-workflow.md - AI image creation process
  • Localization: docs/i18n-localization.md - Multi-language content generation

2-Line Summary for Whitepaper

Programmatic SEO - Automated Market Acquisition Engine: AI-powered pipeline generating 1000+ city/category landing pages across 100+ languages with LLM-based content generation (1000-3000 words), FLUX/SDXL image creation, knowledge-verification fact-checking, and automated i18n localization. Campaign-based deployment enables rapid multi-market expansion with semantic image generation ensuring policy-compliant visual assets.

Investor Value: Growth — Drives organic client acquisition at $0 CAC while competitors pay $50-200/client via Google/Facebook ads; scales globally without marginal content creation costs ($0.01-0.10 per page vs. $500-2000 agency fees); truth validation pipeline prevents hallucinations that destroyed competitor SEO authority, maintaining rankings through quality signals.

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