Eve library

Lilith Domain

Guide

Revision 1

On this page

Lilith -- Conversational AI and Consciousness Experience Platform

Lilith is the largest domain in the Oshun monorepo: a comprehensive consciousness experience platform with 79 applications (70+ microservices, web, mobile, desktop, CLI) and 21 shared libraries. It provides guided meditations, AI-powered spiritual conversations, real-time chat, Sophia-backed grounding and knowledge retrieval, TTS/STT, multi-persona support, subscription management, Web3 integration, and VR/AR meditation spaces.


Architecture#

See architecture.md for the full architecture document including data flow diagrams, API endpoints, database schemas, and deployment topology.


Service Categories#

Core Platform (10 services)#

Service Port Description
bff 3000 Backend-for-Frontend API Gateway (GraphQL + REST, SSE streaming)
svc-conversation 3001 Real-time chat with WebSocket, threading
svc-ai 3002 LLM orchestration with document parsing (PDF, Office, HTML)
svc-auth 3003 Authentication (JWT, WebAuthn, TOTP, argon2)
svc-content 3004 Content management with cultural localization
svc-media 3005 Media processing and storage
svc-notification 3006 Push/email notifications
svc-moderation 3007 Content safety guardrails
svc-tts 3009 Text-to-speech (AWS Polly)
svc-stt 3010 Speech-to-text recognition

AI and Knowledge#

Lilith now relies on svc-ai, svc-indexer, svc-catalog, and Sophia's search, knowledge-graph, and ingestion services for grounding, retrieval, and curation workflows.

Meditation and Wellness (10 services)#

svc-meditation-core, svc-meditation-experience, svc-meditation-generation, svc-group-meditation, svc-breathwork, svc-yoga-practice, svc-spiritual-guidance, svc-journal, svc-notes, svc-daily-content

Voice and Audio (5 services)#

svc-tts, svc-stt, svc-voice-pipeline, svc-audio-handoff, svc-webrtc

Content and Delivery (8 services)#

svc-curricula, svc-review, svc-content-licensing, svc-content-verification, svc-rights-management, svc-teacher-blessing

User and Progress (7 services)#

svc-user-preferences, svc-progress-sync, svc-offline, svc-biometric, svc-analytics, svc-anonymization, svc-language-detection

Commerce (5 services)#

svc-tiered-subscription, svc-payment-orchestrator, svc-creator-royalty, svc-partner-api, svc-avatar-cosmetic

Web3 and Blockchain (14 services)#

svc-blockchain, svc-native-token, svc-token-core, svc-token-access, svc-token-verification, svc-staking-mechanism, svc-dao-governance, svc-defi-integration, svc-cross-chain-bridge, svc-ipfs-integration, svc-micro-transaction, svc-fiat-ramp, svc-settlement, svc-transaction-core

Immersive (4 services)#

svc-metaverse (VR/AR), svc-veilborn-core (RPG), svc-veilborn-strategy (strategy game)

Infrastructure (5 services)#

svc-observability, svc-operational-excellence, svc-multi-region-resilience, svc-safety-automation, svc-error-handler

Client Applications (6)#

Application Framework Description
web Next.js 14, React 18, Three.js, Radix UI, TailwindCSS PWA with 3D visualization, Web3 wallet, Storybook
mobile React Native 0.73, Detox E2E iOS/Android with audio, WebRTC, biometrics, haptics
desktop Electron Desktop client
bff Fastify + Mercurius (GraphQL) API Gateway
cli -- Command-line interface
locales -- Localization resources

Libraries (21)#

text
libs/lilith/
  core/              Core types, utilities, constants, validation (Zod)
  common/            Common types and constants
  config/            Configuration with env validation
  errors/            Standardized error types
  logger/            Logging utilities
  database/          PostgreSQL with Knex.js
  cache/             Redis caching
  queue/             Job queue abstraction
  fastify-core/      Shared Fastify server bootstrap
  service-lib/       Shared service utilities (OpenTelemetry, JWT, Redis, ES)
  event-handlers/    Event subscriptions
  event-publisher/   Event publishing
  metrics/           Prometheus metrics
  tracing/           OpenTelemetry distributed tracing
  sdk/               TypeScript SDK with OpenAPI types
  partner-sdk/       External partner SDK
  testing/           Test utilities and fixtures
  eslint-config/     ESLint configuration
  prettier-config/   Prettier configuration
  tsconfig/          Shared TypeScript configuration

Databases#

Store Port Purpose
PostgreSQL 5433 (Lilith-local) Primary relational data (Knex.js, per-service schemas)
Redis 6379 Caching, sessions, pub/sub, job queues
Elasticsearch -- Full-text search, log aggregation
MinIO 9000 S3-compatible object storage

Subscription Tiers#

Tier Features
Free Basic meditations, limited daily content
Premium Full catalog, offline downloads, no ads
Creator Create and monetize content, royalty tracking
Enterprise Team features, analytics, partner API

Technology Stack#

Layer Technologies
Gateway Fastify, Mercurius (GraphQL)
Services Fastify 4/5, @lilith/fastify-core, @lilith/service-lib
Web Next.js 14, React 18, TailwindCSS, Radix UI, Three.js, Zustand
Mobile React Native 0.73, React Navigation, Track Player
Web3 ethers.js 6, wagmi/viem, Web3Modal
Database PostgreSQL (Knex), Redis, Elasticsearch, MinIO
AI OpenAI, Sophia search/knowledge APIs
Voice AWS Polly (TTS), STT, WebRTC SFU
Auth JWT, WebAuthn/FIDO2, TOTP, argon2
Observability OpenTelemetry, Jaeger, Elasticsearch, Prometheus
Testing Vitest, Playwright, Detox, Storybook, Chromatic

API Endpoints#

Method Endpoint Description
GET /v1/meditations List meditations
GET /v1/meditations/:id Get meditation details
POST /v1/sessions Start session
PUT /v1/sessions/:id/complete Complete session
GET /v1/progress Get user progress
GET /v1/achievements List achievements
POST /v1/conversations Start AI conversation
GET /v1/recommendations Personalized content
GET /v1/catalog/daily Daily content

Using the SDK#

typescript
import { createLilithClient } from '@lilith/sdk';

const lilith = createLilithClient({
  baseUrl: process.env.LILITH_API_URL || 'http://localhost:4006',
});

// Get meditation catalog
const meditations = await lilith.meditations.list({
  category: 'stress-relief',
  duration: { min: 5, max: 15 },
});

// Start a meditation session
const session = await lilith.sessions.start({
  meditationId: meditations[0].id,
});

// Track completion
await lilith.sessions.complete(session.id, {
  duration: 600,
  feedback: { rating: 5 },
});

Development#

bash
# Start Lilith API gateway
pnpm nx serve lilith-api

# Start individual service
pnpm nx serve lilith-svc-meditation-core

# Run SDK tests
pnpm nx test @lilith/sdk

# Build all Lilith libraries
pnpm nx run-many --target=build --projects=tag:scope:lilith

# Start web app
cd apps/lilith/web && pnpm dev

Legacy Documentation#

Lilith has 440+ files of pre-monorepo documentation at docs/domains/lilith/extras/:

Note: Lilith's development environment uses port 5433 for PostgreSQL (vs 5432 for main Oshun) to avoid conflicts.