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)#
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#
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#
# 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/:
- ARCHITECTURE.md -- System architecture
- PRODUCT.md -- Product specification
- LOCAL_DEVELOPMENT_GUIDE.md -- Docker/Kind setup
- INFRASTRUCTURE_SETUP.md -- Database/service config
- CODING_GUIDELINES.md -- Coding standards
- GO_LIVE_CHECKLIST.md -- Launch checklist
- OPENAPI_DOCUMENTATION_GAP_ANALYSIS.md -- API gaps
Note: Lilith's development environment uses port 5433 for PostgreSQL (vs 5432 for main Oshun) to avoid conflicts.
Related Documentation#
- Architecture -- Detailed architecture document
- Monorepo Architecture -- Monorepo overview
- Cross-Domain Integration