Lilith — Feature Reference

Lilith is the Conversational AI and Consciousness Experience Platform. It delivers guided meditations, AI-powered spiritual conversations, real-time voice chat, RAG-based knowledge retrieval, TTS/STT, multi-persona AI support, subscription management, Web3 token economy, and immersive VR/AR meditation spaces — unified into a single wellness ecosystem across web, mobile, desktop, and immersive platforms.

Lilith is one of the largest domains in the Oshun monorepo: 78 packages under apps/lilith/ (69 backend svc-* services plus web, mobile, desktop, CLI, and the smart-contracts, seed-corpus, locales, and shared packages), 9 shared libraries under libs/lilith/, and 5 client platforms. It sits at the intersection of AI technology, spiritual wellness, creative expression, and Web3 — serving practitioners from their first five-minute guided session through advanced multi-tradition learning paths, content creation, and community leadership.

Platform Overview#

Architecture Scale#

The numbers below give a quick orientation to the domain's scope before diving into individual features:

Service Clusters#

The 69 svc-* services are grouped functionally. The clustering reflects the domain's breadth: a new engineer working on subscription billing (Commerce) and one working on voice sessions (Voice and Audio) are working in largely separate service namespaces with clearly bounded concerns:

Technology Stack#

The table below lists the primary technology at each layer of the stack. Choices favor TypeScript end-to-end, Fastify for high-throughput microservices, and React-based clients for maximum code sharing across web and mobile:

Shared Library Ecosystem (9 Libraries)#

libs/lilith/ holds nine packages that provide Lilith-specific shared infrastructure. Cross-cutting concerns (config, errors, logging, metrics, tracing, testing, types) come from monorepo-wide @oshun/* packages rather than Lilith-local libraries, keeping the libs/lilith/ packages focused on Lilith-specific concerns:

Platform Access#

Lilith is available on every major platform, giving users the freedom to practice wherever they are. Each client platform shares the same backend services and user account, so switching devices requires no manual sync.

Client Applications#

Web Features#

• Progressive Web App (PWA) — Installable on any device from the browser; works offline with service-worker caching and receives push notifications like a native app.
• 3D Visualizations — Rich 3D meditation environments rendered via Three.js, BabylonJS, and React Three Fiber (R3F) directly in the browser without plugins.
• Real-Time AI Chat — AI responses stream word-by-word via Server-Sent Events (SSE) for a natural conversational feel rather than waiting for full responses.
• Web3 Wallet Connection — Connect MetaMask, WalletConnect, or other wallets via wagmi/viem; access token-gated content and participate in DAO governance.
• Storybook Design System — Radix UI components with Tailwind CSS; consistent visual language across all interface surfaces; components developed and tested in Storybook with visual regression via Chromatic.
• Internationalization — next-intl with full RTL (right-to-left) layout support for Arabic, Hebrew, and other RTL languages.

Mobile Features#

• Native Biometric Authentication — Face ID, Touch ID, and fingerprint login via the device's secure enclave; no password required for returning users.
• Background Audio Playback — Continue meditating while the screen is off or while using other apps; Track Player handles native audio session management and lock-screen controls.
• Haptic Feedback — Vibration patterns synchronized with breathing exercises create a tactile rhythm guide without requiring eyes on the screen.
• Offline Downloads — Download meditation sessions, courses, and teachings as encrypted bundles that play without any network connection.
• Health Data Integration — Apple HealthKit and Google Fit integration pulls heart rate and HRV (Heart Rate Variability) data into session tracking and provides post-session insights.
• Push Notifications — Meditation reminders, streak alerts, and community notifications delivered natively via the device notification system.
• WebRTC Voice Chat — High-quality, low-latency real-time voice communication for group meditation sessions.
• Detox E2E Test Suite — Automated end-to-end tests run on real devices and simulators for every release via Detox.

AI Conversations#

Conversational AI (svc-conversation, svc-ai)#

Conversations are the primary interface through which users engage with Lilith's AI layer. The system supports multiple AI personas with distinct personalities and tradition focuses; conversations are organized into named, resumable threads; and responses stream word-by-word over SSE so the user begins reading immediately. The svc-ai service handles LLM orchestration and can parse uploaded documents (PDFs, Office files, HTML, Markdown) for in-context discussion.

AI Knowledge System (Sophia-backed retrieval)#

Rather than maintaining its own vector stores and ingestion pipelines, Lilith delegates all knowledge retrieval to the Sophia domain via @lilith/sophia-adapter. This design keeps the spiritual corpus and knowledge graph management in a single shared platform while letting Lilith focus on session experience and persona logic.

Spiritual Guidance (svc-spiritual-guidance)#

Beyond general AI chat, svc-spiritual-guidance provides personalized advisory conversations calibrated to the user's spiritual tradition. The advisor draws on the Sophia knowledge graph and respects the user's stated practice path rather than offering generic responses:

Meditation and Wellness#

Meditation Sessions (svc-meditation-core, svc-meditation-experience)#

The meditation core handles mode selection and safety screening before handing off to the experience service for actual session delivery. Three session lengths (5, 12, and 20 minutes) let users fit practice into any schedule, while AI-generated sessions personalize content on demand rather than drawing from a fixed catalog:

Group Meditation (svc-group-meditation)#

Group sessions use WebSocket coordination to align audio playback sub-second across all participants, creating a genuine sense of shared practice across geographic distance:

Breathwork (svc-breathwork)#

The breathwork service extends beyond a simple timer. HRV is a clinically recognized measure of autonomic nervous system health and a standard metric in breathwork research; Lilith surfaces it through HealthKit/Google Fit integration during sessions:

Yoga Practice (svc-yoga-practice)#

Voice and Audio#

Text-to-Speech (svc-tts)#

svc-tts uses AWS Polly as its primary synthesis engine with S3 audio caching to avoid re-synthesizing identical text. The service selects voice characteristics contextually — slower and warmer for sleep sessions, clearer and more measured for philosophical teaching:

Speech-to-Text (svc-stt)#

Voice Conversations (svc-voice-pipeline)#

The duplex voice pipeline combines svc-stt, AI conversation, svc-tts, and WebRTC into a seamless voice-first interaction. An SFU (Selective Forwarding Unit) routes audio streams between participants without mixing them on the server, which minimizes latency for group sessions:

Knowledge and Learning#

Curricula and Courses (svc-curricula)#

Curricula are multi-session structured paths designed for progressive skill building. Each lesson tracks completion state independently so users can pause and resume at any point, and the platform issues certificates once course requirements are met:

Knowledge Catalog (svc-catalog)#

The catalog is the browse surface for Lilith's content library. Knowledge curation and the concept graph are managed in Sophia's knowledge platform, while the catalog service provides the user-facing search and browse experience:

Knowledge Ingestion and Indexing (svc-indexer)#

The indexer service manages Lilith's own content indices while delegating the broader spiritual corpus to Sophia. Crawling, enrichment, and the retrieval graph are Sophia's responsibility; Lilith retains only the indices it needs for its own catalog search:

Scholar Notes (svc-notes)#

Scholar notes let users build a personal knowledge layer on top of the platform content. Notes are full-text indexed for search and can be linked across the knowledge base, creating a personal graph connecting user insights to source material:

Journaling and Reflection#

Journaling is tightly integrated with meditation: a prompt fires automatically after every session, mood is tracked before and after to measure impact, and all entries are encrypted at rest and never used for model training without explicit consent:

Content Discovery#

Content discovery combines Elasticsearch-powered search, AI-based recommendations, and curated daily delivery to surface relevant content at every touchpoint:

Content Review (svc-review, svc-teacher-blessing)#

A two-tier review process gates new content before it reaches users: human moderators check quality and safety for all content, while sacred content from specific lineages requires approval from a verified teacher in that tradition:

Community Features#

Social Features#

The social layer lets practitioners share their journey, learn from others, and practice together. Community translation contributions make the platform accessible in languages not yet officially supported:

Real-Time Chat#

Community chat is delivered via WebSocket with sub-100 ms message delivery. DOMPurify sanitization on all user-submitted content prevents XSS injection attacks:

Immersive Experiences#

VR/AR Meditation Spaces (svc-metaverse)#

The metaverse service renders fully immersive 3D environments for meditation. Spatial audio — birds, water, bells positioned in 3D space — reinforces the sense of presence. Premium environments are unlockable via subscription or token purchase, giving the Web3 economy a tangible experiential utility:

3D Visualizations#

3D visuals are rendered using Three.js, BabylonJS, and React Three Fiber directly in the browser via WebGL. Fractal art is a product-level capability (no longer backed by a standalone svc-generative-fractal service), while interactive mandalas respond to the user's biometric and meditation state in real time:

Avatar Customization (svc-avatar-cosmetic)#

The avatar cosmetics marketplace creates a seasonal collectible economy around virtual identity. Token-gated items give Lilith token holders exclusive cosmetic access, creating tangible utility for token ownership beyond governance:

Creator Economy#

Creator Tools (svc-content-licensing, svc-content-verification, svc-rights-management)#

The creator economy lets practitioners publish and monetize their own guided meditations, yoga sequences, and spiritual teachings. Licensing terms are configurable per creator, and rights enforcement is automated — content played beyond licensed scope is blocked automatically and the rights holder is notified:

Monetization#

Creators can configure payout method and schedule independently, choosing bank transfer, crypto, or Lilith tokens, with a minimum threshold to avoid fragmented micro-payouts:

Web3 and Token Economy#

Native Token (svc-native-token, svc-token-core)#

The native token is the economic unit that connects subscriptions, creator earnings, governance, and premium content access. A built-in non-custodial wallet and fiat on-ramp let users engage with the token economy without needing a third-party wallet app:

Token-Gated Access (svc-token-access, svc-token-verification)#

Token-gated access uses on-chain cryptographic verification — the gate cannot be spoofed because it checks actual token balances on the blockchain rather than relying on a database flag:

Staking and DeFi (svc-staking-mechanism, svc-defi-integration)#

DAO Governance (svc-dao-governance)#

All governance votes, proposals, and treasury transactions are recorded on-chain and publicly viewable, ensuring the community-governed treasury is accountable to all token holders:

Transaction Management (svc-transaction-core, svc-transaction-manager, svc-settlement)#

The transaction infrastructure coordinates payment across multiple rails and ensures creator royalties are settled reliably on schedule regardless of transaction volume:

Account and Identity#

Authentication (svc-auth, svc-auth-orchestrator)#

svc-auth is one of Lilith's most comprehensive services (164 source files). It supports the full range of modern authentication patterns: argon2id password hashing (memory-hard and GPU-cracking-resistant), WebAuthn passkeys (phishing-resistant by design), TOTP and SMS OTP for two-factor, QR-code device pairing, and OAuth federated login. The auth orchestrator coordinates multi-step flows and enforces auth policy per subscription tier:

Profile Management#

Personalization and Progress#

Progress Tracking (svc-progress-sync)#

Progress data syncs across all devices in real time and includes 50+ achievement badges for milestones. Streak logic includes a configurable grace period for missed days, acknowledging that daily practice is a goal, not a punitive requirement:

Biometric Integration (svc-biometric)#

Biometric data is anonymized, encrypted, and never shared with advertisers. Its purpose is to give users an objective view of how their practice affects their physiology over time:

Personalized Recommendations#

Recommendations improve over time as the system learns from implicit engagement signals (completion rate, replays, skips) in addition to explicitly stated goals and mood entries:

Offline and Cross-Device#

Offline Access (svc-offline)#

Downloaded content is stored as encrypted bundles tied to the user's account. License enforcement applies offline: content downloaded on a Premium plan becomes inaccessible after a subscription downgrade until the device reconnects and re-validates:

Cross-Device Continuity (svc-sync, svc-real-time-sync)#

Cross-device sync uses CRDT algorithms (Conflict-free Replicated Data Types) to merge concurrent edits made on multiple devices without data loss or manual conflict resolution. The dedicated svc-real-time-sync service manages all WebSocket connections for sync:

Notifications and Daily Content#

Notification System (svc-notification)#

The notification service balances user engagement against notification fatigue. New content alerts from followed teachers are capped at once per day, and streak alerts are sent only in the evening when a streak is at risk — not as indiscriminate push blasts:

Daily Content (svc-daily-content)#

The daily content service personalizes each day's selection based on the user's practice history, recent mood, and current streak stage. Seasonal collections align with solstices, equinoxes, lunar phases, and culturally significant spiritual dates to keep content timely and contextually resonant:

Subscription Plans#

The four subscription tiers define what each user segment can access. Free gives enough to experience the platform; Premium unlocks the full catalog and offline use; Creator adds the ability to publish and monetize; Enterprise adds team management, advanced analytics, and partner API access:

Tiered Subscription Management (svc-tiered-subscription)#

The tiered subscription service handles plan changes, prorations, trial periods, and grace periods. It integrates with the payment orchestrator for billing and emits subscription change events that gate-unlock or gate-restrict feature access across all services immediately on plan change.

Payment Options#

Accessibility and Localization#

Language Support (svc-language-detection)#

Language detection uses the browser locale on first visit and stores the preference in svc-user-preferences. Adding a new locale requires only translation files — no code changes — because the string system is built on next-intl with full coverage:

Accessibility#

All accessibility features meet WCAG standards. The prefers-reduced-motion media query is respected system-wide, and all layout uses relative font units so system font size scaling does not break the interface:

Privacy and Data Governance#

Privacy is a first-class concern throughout Lilith's design. Journal entries, health data, and conversation history are encrypted at rest with AES-256 and in transit with TLS 1.3. Consent is managed per category (research, voice-cloning, analytics, blockchain) and is independently revocable at any time:

Platform Infrastructure#

Observability and Reliability#

The infrastructure services operate beneath the user-facing feature surface, providing the reliability guarantees the wellness platform depends on. All services inherit OpenTelemetry tracing through @lilith/service-lib; the observability service collects and surfaces those traces alongside Prometheus metrics and structured logs:

Safety Automation#

Safety runs at two layers: svc-moderation screens content in real time at upload and submission; svc-safety-automation runs scheduled scans across the entire content library to catch safety regressions when AI safety models are updated:

Developer and Partner Access#

Lilith exposes a fully typed TypeScript SDK (@lilith/sdk) auto-generated from its OpenAPI specifications, along with a separate partner-facing SDK (@lilith/partner-sdk) for enterprise integration teams. The BFF's GraphQL interface lets clients request exactly the data shape they need, while REST endpoints cover all platform operations:

Domain Events#

Lilith exchanges domain events over the monorepo @oshun/event-bus (Redis Streams) via @lilith/event-publisher and @lilith/event-handlers. Events are the primary mechanism for notifying other domains of Lilith activity without direct service-to-service coupling.

Published by Lilith (10 events, from LilithEventTypes):

The ten outbound events cover meditation lifecycle, journaling, progress, teacher interactions, and offline downloads. Each event routes to the domains that care about it: Hathor (narrative world), Isis (generation), and Sophia (knowledge platform):

Consumed by Lilith (8 events, from LILITH_SUBSCRIPTIONS):

The eight inbound subscriptions let Lilith react to activity in other domains — typically by invalidating caches and broadcasting updates to connected WebSocket clients. Crucially, these handlers do not write to authoritative storage; they are fan-out-only:

Lilith's event handlers fan out to WebSocket clients; they do not write to authoritative storage.

Generative Art#

ComfyUI Integration#

AI image and video generation routes through shared Isis/RunComfy integrations rather than a Lilith-local svc-comfyui service. This means Lilith benefits from Isis's GPU infrastructure and generation queue management without duplicating those resources:

Generative Fractal Visualizations#

Fractal art is generated mathematically in real time and modulated by the user's biometric state. The parameters — complex number coordinates, iteration depth, color mapping, zoom level — can be adjusted interactively or driven automatically by the session's progression:

Source Verification#

This file was checked against the actual codebase: the 78 apps/lilith/ packages (69 svc-* services + bff, web, mobile, desktop, cli, contracts, seed-corpus, locales, shared), the 9 libs/lilith/ libraries, the @lilith/event-publisher / @lilith/event-handlers event catalogs, the BFF route registration, and the Solidity sources under apps/lilith/contracts/contracts/. Counts, the library list, the event tables, and the smart-contract list reflect that inventory; capabilities with no backing service in the codebase have been removed. Lilith owns the consciousness/spiritual experience surface; Tara owns the App Store-safe meditation product, Shakti owns physical training, and Sophia supplies knowledge grounding.