Canonical source: the canonical architecture document for this domain is
deep-dive/architecture.md , rendered in the
docs center. This file is its operational companion (service topology, APIs,
schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).
Lilith -- Conversational AI and Consciousness Experience Platform
Lilith is Oshun's largest domain: a comprehensive consciousness experience
platform with 79 applications (70+ microservices, web, mobile, desktop, CLI)
and 22 shared libraries . It provides guided meditations, AI conversations,
real-time chat, Sophia-backed grounded retrieval, TTS/STT, multi-persona
support, subscription management, Web3 integration, and VR/AR meditation spaces.
System Overview#
Lilith is a microservices-oriented platform organized around several functional
clusters:
Core Platform -- BFF gateway, authentication, conversation, content
management, media processing
AI and Knowledge -- LLM orchestration, Sophia-backed retrieval, search,
and knowledge graph access
Meditation and Wellness -- Meditation sessions, breathwork, yoga, group
meditation, spiritual guidance, journal
Voice and Audio -- TTS (Chatterbox), STT, voice pipeline, audio handoff,
WebRTC
Content and Delivery -- Catalog, daily content, curricula, review,
moderation, content licensing
User and Progress -- User preferences, progress sync, offline,
cross-device sync, biometric, notifications
Commerce -- Tiered subscriptions, payment orchestration, creator
royalties, partner API
Web3 and Blockchain -- Native token, staking, DeFi, DAO governance, IPFS,
cross-chain bridge, NFT/token verification, micro-transactions, fiat ramp,
settlement
Immersive -- Metaverse (VR/AR), avatar cosmetics, AI generation routes,
Veilborn tabletop RPG
Infrastructure -- Observability, error handling, operational excellence,
multi-region resilience, data governance, anonymization, safety automation
Localization -- Language detection, community translation
Clients -- Web (Next.js PWA), Mobile (React Native), Desktop (Electron),
CLI
Service Architecture#
Port Assignments#
The core services follow a sequential port scheme starting at 3000:
Port
Service
Description
3000
bff
Backend-for-Frontend API Gateway (GraphQL + REST proxy)
3001
svc-conversation
Real-time chat, threading, WebSocket
3002
svc-ai
LLM orchestration with RAG, document parsing
3003
svc-auth
Authentication (JWT, WebAuthn, TOTP, passkeys)
3004
svc-content
Content management with cultural localization
3005
svc-media
Media processing and storage
3006
svc-notification
Push/email dispatch
3007
svc-moderation
Content safety and policy guardrails
3009
svc-tts
Text-to-speech synthesis (AWS Polly)
3010
svc-stt
Speech-to-text recognition
All Applications (79)#
Gateway and Clients (6)#
Application
Type
Framework
Description
bff
API Gateway
Fastify + Mercurius (GraphQL)
Backend-for-Frontend: proxies all backend services, provides GraphQL layer, SSE chat streaming, circuit breaker, response shaping
web
Web App
Next.js 14, React 18, Three.js, Radix UI, TailwindCSS
PWA with 3D visualization (BabylonJS/R3F), i18n (next-intl), Storybook, Web3 wallet (wagmi/viem)
mobile
Mobile App
React Native 0.73, Detox E2E
iOS/Android with audio recording, WebRTC, biometrics, haptics, offline, push notifications, track player
desktop
Desktop App
Electron
Desktop client for consciousness experience
cli
CLI Tool
--
Command-line interface
locales
Resource
--
Localization string resources
Service
Description
svc-auth
Authentication with JWT, argon2/bcrypt, WebAuthn (FIDO2), TOTP/2FA, QR codes, password strength (zxcvbn), Knex migrations
svc-auth-orchestrator
Cross-platform auth flow coordination
svc-conversation
Real-time chat with WebSocket, threading, Knex migrations
svc-ai
LLM orchestration with document parsing (PDF, Office, HTML, Markdown), Cheerio, TypeDoc API docs
svc-content
Content management with cultural localization, Knex migrations
svc-media
Media processing and storage, Knex migrations
svc-notification
Push/email notifications, Knex migrations
svc-moderation
Content safety guardrails and policy enforcement
svc-error-handler
Consistent error handling and offline fallback
svc-real-time-sync
Cross-platform real-time messaging sync
svc-sync
CRDT-based conflict-free sync, WebSocket collaboration, cross-device continuity
AI and Knowledge Services (4)#
Component
Ownership
Description
svc-ai
Lilith
LLM orchestration, persona logic, and conversation generation
svc-indexer
Lilith
Content indexing service
sophia-search-api
Sophia
Search and grounded answer retrieval used by Lilith knowledge APIs
sophia-knowledge-graph
Sophia
Entity graph and document metadata APIs consumed by Lilith
Meditation and Wellness Services (10)#
Service
Description
svc-meditation-core
Core meditation service with safety and mode-selection
svc-meditation-experience
Meditation experience orchestration
svc-meditation-generation
AI-generated meditation creation
svc-group-meditation
Collaborative group meditation with real-time sync
svc-breathwork
Breathing exercises and techniques
svc-yoga-practice
Yoga practice sessions and guidance
svc-spiritual-guidance
AI spiritual guidance conversations
svc-journal
Personal journaling and reflection
svc-notes
Scholar notes, highlights, and learning journals
svc-daily-content
Scheduled daily meditation delivery with personalization
Voice and Audio Services (5)#
Service
Description
svc-tts
Text-to-speech via AWS Polly with S3 storage
svc-stt
Speech-to-text recognition
svc-voice-pipeline
Duplex voice pipeline for real-time audio processing
svc-audio-handoff
Cross-device audio handoff for seamless meditation continuity
svc-webrtc
WebRTC SFU for real-time voice chat
Content and Delivery Services (7)#
Service
Description
svc-curricula
Structured learning paths and progress tracking
svc-review
Human-in-the-loop content review
svc-content-licensing
Content licensing management
svc-content-verification
Content verification
svc-rights-management
Automated license gates and content source validation
svc-teacher-blessing
Teacher content approval workflows
bff generation routes
AI image/video generation routed through shared Isis/RunComfy integrations
User and Progress Services (7)#
Service
Description
svc-user-preferences
User preference management and sync, Knex migrations
svc-progress-sync
Cross-device progress and bookmark synchronization
svc-offline
Offline downloads with encrypted bundles and license management
svc-biometric
Health data integration (HealthKit, Google Fit)
svc-analytics
Analytics service, Knex migrations
svc-anonymization
Privacy-preserving anonymization
svc-language-detection
Language detection and auto-switching
Commerce Services (5)#
Service
Description
svc-tiered-subscription
Subscription tiers (Free, Premium, Creator, Enterprise)
svc-payment-orchestrator
Payment orchestration, Knex migrations
svc-creator-royalty
Creator payment and royalty tracking
svc-partner-api
Third-party partner integrations
svc-avatar-cosmetic
Avatar customization and cosmetics marketplace
Web3 and Blockchain Services (14)#
Service
Description
svc-blockchain
Blockchain/Web3 integration for NFTs, crypto payments, token economy
svc-native-token
Native platform token
svc-token-core
Shared token/NFT primitives
svc-token-access
Token-gated content access
svc-token-verification
Token/NFT verification
svc-staking-mechanism
Token staking
svc-dao-governance
DAO governance voting
svc-defi-integration
DeFi protocol integration
svc-cross-chain-bridge
Cross-chain token bridging
svc-ipfs-integration
IPFS decentralized storage
svc-micro-transaction
Micro-transaction processing
svc-fiat-ramp
Fiat on/off ramp
svc-settlement
Web3 payment settlement orchestration
svc-transaction-core
Shared transaction primitives and flow helpers
Additional transaction services: svc-transaction-manager ,
svc-consent-management (research/analytics/voice cloning consent),
svc-data-governance (compliance), svc-community-translation (translation
workflows).
Immersive and Gaming Services (3)#
Service
Description
svc-metaverse
3D VR/AR meditation spaces
svc-veilborn-core
Veilborn Chronicles -- tabletop RPG game engine
svc-veilborn-strategy
Veilborn Chronicles -- The Veil War strategy game
Infrastructure Services (5)#
Service
Description
svc-observability
SLO definitions, error budgets, alerting
svc-operational-excellence
Operational excellence automation
svc-multi-region-resilience
Active/active multi-region with failover
svc-safety-automation
Safety evaluation automation and red-team program
svc-meditation-core
Meditation safety and mode selection helpers (shared library)
Special Applications (2)#
Application
Description
seed-corpus
Seed data and corpus for knowledge systems
contracts
API contracts and interface definitions
Library Architecture#
Shared Libraries (22)#
text Copy
libs/lilith/
core/ @lilith/core Core types, utilities, constants, validation (Zod)
common/ @lilith/common Common types and constants
config/ @lilith/config Configuration management with env validation
errors/ @lilith/errors Standardized error types
logger/ @lilith/logger Logging utilities
database/ @lilith/database PostgreSQL with Knex.js, connection pooling
cache/ @lilith/cache Redis caching layer
queue/ @lilith/queue Job queue abstraction
fastify-core/ @lilith/fastify-core Shared Fastify server bootstrap (all services use this)
service-lib/ @lilith/service-lib Shared service utilities (OpenTelemetry tracing, JWT,
Redis, Elasticsearch, Axios, DOMPurify, circuit breaker)
event-handlers/ @lilith/event-handlers Event subscription management
event-publisher/ @lilith/event-publisher Event publishing
metrics/ @lilith/metrics Prometheus metrics
tracing/ @lilith/tracing OpenTelemetry distributed tracing
sophia-adapter/ @lilith/sophia-adapter Sophia integration helpers
vectordb/ @lilith/vectordb Vector database client (Milvus)
sdk/ @lilith/sdk TypeScript SDK with OpenAPI type generation
partner-sdk/ @lilith/partner-sdk External partner SDK
testing/ @lilith/testing Shared test utilities and fixtures
eslint-config-lilith/ -- ESLint configuration
prettier-config-lilith/ -- Prettier configuration
tsconfig-lilith/ @lilith/tsconfig Shared TypeScript configuration
Library Dependency Hierarchy#
text Copy
@lilith/tsconfig
|
@lilith/core (Zod, types, validation)
/ | \
@lilith/config @lilith/errors @lilith/logger
\ | /
@lilith/database (Knex, pg)
|
@lilith/fastify-core
|
@lilith/service-lib
(OpenTelemetry, JWT, Redis, ES, Axios)
/ | \
@lilith/ @lilith/ @lilith/
cache queue metrics
|
All 70+ svc-* services
Key Library Details#
@lilith/fastify-core -- The foundation every service builds on. Provides
createServiceServer() which bootstraps a Fastify instance with:
Structured logging (Elasticsearch output)
Health check endpoints
Graceful shutdown handling
OpenTelemetry instrumentation
Error handling middleware
@lilith/service-lib -- The operational backbone. Includes:
OpenTelemetry SDK auto-instrumentation (Jaeger exporter)
JWT authentication middleware
Redis client (ioredis)
Elasticsearch client
Axios HTTP client with circuit breaker
Input sanitization (DOMPurify)
AJV JSON Schema validation
AWS SDK integration
Semantic versioning (semver)
@lilith/database -- PostgreSQL access via Knex.js with:
Connection pool management
Migration support
Query builder
@lilith/sdk -- TypeScript SDK for API consumers:
OpenAPI type generation (openapi-typescript)
Typed API client methods
Data Flow#
Primary Request Flow#
text Copy
Client (Web/Mobile/Desktop)
|
v
+------+------+
| BFF :3000 | GraphQL (Mercurius) + REST proxy
| Fastify | Circuit breaker, response shaping
+------+------+ SSE chat streaming
|
+----+----+----+----+----+----+
| | | | | | |
v v v v v v v
Auth Conv AI Cont Med Sophia ...
:3003 :3001 :3002 :3004 :30xx via BFF
| | |
v v v
+----+----+----+----+----+----+
| | | |
Postgres Redis Elasticsearch Sophia
(Knex) (ioredis) (search/logs) APIs
|
+--------+
| |
MinIO Shared retrieval stores
(S3) (owned by Sophia)
AI Conversation Flow#
text Copy
User message
|
v
BFF (chat-orchestration-routes, SSE streaming)
|
v
svc-conversation :3001 (threading, WebSocket)
|
+---> svc-ai :3002 (LLM orchestration)
| |
| +---> BFF Sophia knowledge routes
| | |
| | +---> sophia-search-api (/rag, /search)
| | +---> sophia-knowledge-graph (/entities, /documents)
| |
| +---> LLM API (OpenAI, etc.)
|
+---> svc-moderation :3007 (safety check)
|
v
Response streamed via SSE
Voice Conversation Flow#
text Copy
User speaks into mic
|
v
svc-webrtc (WebRTC SFU, real-time audio)
|
v
svc-voice-pipeline (duplex audio processing)
|
+---> svc-stt :3010 (speech-to-text)
| |
| v
| Text sent to conversation flow (above)
| |
| v
+---> svc-tts :3009 (text-to-speech via AWS Polly)
| |
| v
+---> Audio returned to user
|
svc-audio-handoff (cross-device continuity)
Meditation Session Flow#
text Copy
User starts meditation
|
v
svc-meditation-core (safety checks, mode selection)
|
v
svc-meditation-experience (session orchestration)
|
+---> svc-daily-content (personalized selection)
+---> svc-catalog (content metadata)
+---> svc-content :3004 (content retrieval)
+---> svc-media :3005 (audio/video assets)
|
v
Audio/guided meditation delivered
|
+---> svc-biometric (optional health data capture)
+---> svc-progress-sync (session tracking)
+---> svc-notification :3006 (streak/achievement alerts)
|
v
svc-analytics (session metrics)
Database Architecture#
Lilith uses PostgreSQL (via Knex.js) as the primary database. The following
services have their own Knex migration sets (database-per-service pattern):
Service
Database Purpose
svc-auth
Users, credentials, sessions, WebAuthn registrations, TOTP secrets
svc-conversation
Threads, messages, participants, reactions
svc-content
Content items, categories, localizations
svc-media
Media assets, transcodes, thumbnails
svc-notification
Notification templates, delivery logs, preferences
svc-analytics
Events, metrics, aggregations
svc-payment-orchestrator
Payments, subscriptions, invoices
svc-user-preferences
User settings, themes, language preferences
svc-meditation-core
Meditation sessions, completions, safety logs
Additional Data Stores#
Store
Port
Purpose
PostgreSQL
5432 (5433 for Lilith-local)
Primary relational data
Redis
6379
Caching, sessions, pub/sub, job queues
Elasticsearch
--
Full-text search, log aggregation
Sophia APIs
external
Search, grounded retrieval, entity graph, documents
MinIO
9000
S3-compatible object storage for media
BFF Route Structure#
The BFF serves as the single entry point for all clients. Its route files reveal
the full API surface:
Authentication#
auth-proxy-routes.ts -- Proxy to auth service
Chat and Conversations#
chat-basic-routes.ts -- Basic chat endpoints
chat-audio-routes.ts -- Audio chat
chat-orchestration-routes.ts -- AI orchestration with SSE streaming
chat-orchestration-streaming.ts -- Streaming helpers
chat-orchestration-json.ts -- JSON response mode
chat-core-register.ts -- Chat core registration
Content#
content-proxy-routes.ts -- Content service proxy
content-fallback-register.ts -- Content fallback handling
research-content-route.ts -- Research content
mythology-content-route.ts -- Mythology content
User and Dashboard#
user-routes.ts -- User profile/settings
dashboard-route.ts -- User dashboard aggregation
persona-routes.ts -- AI persona management
Knowledge#
sophia-knowledge-routes.ts -- Sophia-backed search, grounded answer, graph,
and document routes
curricula-routes.ts -- Learning curricula
scholar-notes-routes.ts -- Scholar notes
Operations#
health-routes.ts -- Health checks
metrics-route.ts -- Prometheus metrics
models-route.ts -- AI model information
experiments-route.ts -- Feature experiments
experiments-models-register.ts -- Experiment registration
error-management-routes.ts -- Error handling
circuit-breaker-routes.ts -- Circuit breaker status
observability-register.ts -- Observability setup
Aggregation and Proxy#
aggregation-route.ts -- Multi-service aggregation
bulk-operations-route.ts -- Batch operations
service-proxy-route.ts -- Generic service proxy
conversation-proxy-routes.ts -- Conversation proxy
Specialized#
reflections-routes.ts -- Reflections/journaling
notification-test-route.ts -- Notification testing
partner-routes.ts -- Partner API proxy
comfyui-routes.ts -- ComfyUI generative AI
API Endpoints (Primary)#
Public API (via BFF)#
Method
Endpoint
Description
GET
/v1/meditations
List meditations
GET
/v1/meditations/:id
Get meditation details
POST
/v1/sessions
Start meditation 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
Events (Domain Events)#
Event
Description
lilith.meditation.started
Session started
lilith.meditation.completed
Session completed
lilith.achievement.earned
Achievement unlocked
lilith.progress.updated
Progress milestone
lilith.streak.extended
Streak continued
lilith.streak.broken
Streak lost
lilith.subscription.changed
Tier changed
Technology Stack#
Layer
Technologies
API Gateway
Fastify 4.x, Mercurius (GraphQL), @lilith/fastify-core
Services
Fastify 4.x/5.x, @lilith/service-lib, @lilith/fastify-core
Web Client
Next.js 14, React 18, TailwindCSS 3, Radix UI, Three.js/R3F, BabylonJS, Framer Motion, next-intl, WaveSurfer.js, Storybook 8, Zustand, TanStack Query
Mobile Client
React Native 0.73, React Navigation 6, RN Track Player, WebRTC, Biometrics, Haptics, Lottie, Detox E2E
Desktop Client
Electron
Web3
ethers.js 6, wagmi/viem, Web3Modal
Database
PostgreSQL (Knex.js), Redis (ioredis), Elasticsearch, Sophia-managed retrieval stores
Storage
MinIO (S3), IPFS
AI
OpenAI, LLM orchestration, Sophia-backed grounded retrieval
Voice
AWS Polly (TTS), STT, WebRTC SFU
Auth
JWT, argon2/bcrypt, WebAuthn/FIDO2, TOTP, zxcvbn
Observability
OpenTelemetry, Jaeger (tracing), Elasticsearch (logs), Prometheus (metrics)
Media
Isis/RunComfy-backed generation, FFmpeg (implied), S3 storage
Build
Nx, TypeScript, ESM
Testing
Vitest, Playwright, Detox, @testing-library, @lilith/testing
Storybook
Storybook 8 with Chromatic visual testing
Localization
next-intl, custom translation CLI, community translation workflows
Deployment Architecture#
text Copy
+-------------------+
| CDN / CloudFront |
+--------+----------+
|
+-------------+-------------+
| | |
+-----v-----+ +----v----+ +------v------+
| Web (PWA) | | Mobile | | Desktop |
| Next.js | | RN | | Electron |
+-----------+ +---------+ +-------------+
| | |
+------+------+------+------+
|
+------v------+
| BFF :3000 |
| (Gateway) |
+------+------+
|
+-----------------+-----------------+
| | | | |
+----v---+ +--v---+ +--v---+ +--v---+ +--v---+
|Auth | |Conv | |AI | |Cont | |Medit |
|:3003 | |:3001 | |:3002 | |:3004 | |:30xx |
+--------+ +------+ +------+ +------+ +------+
|Media | |RAG | |TTS | |STT | |WebRTC|
|:3005 | |:3008 | |:3009 | |:3010 | | |
+--------+ +------+ +------+ +------+ +------+
|Notif | |Moder | |Knowl | |VecDB | |Voice |
|:3006 | |:3007 | |edge | | | |Pipe |
+--------+ +------+ +------+ +------+ +------+
| | | | |
+--------+--------+--------+--------+
| |
+-------------+---+ +---------+---------+
| | | | |
v v v v v
PostgreSQL Redis Milvus Neo4j Elasticsearch
(per-service (cache, (vector (KG) (search,
schemas) pub/sub) search) logs)
|
v
MinIO (S3)
Infrastructure Notes#
Database-per-Service : Each service with Knex migrations manages its own
schema/tables within the shared PostgreSQL instance (database: lilith)
Port Offsets : Lilith local dev uses PostgreSQL on port 5433 (vs 5432 for
main Oshun) to avoid conflicts
Docker Compose + Kind : Supports both Docker Compose and Kind Kubernetes
for local development
Multi-Region : The svc-multi-region-resilience service provides
active/active deployment with automated failover
Cross-Domain Dependencies#
Shared @oshun/* Libraries Used#
Library
Used By
@oshun/types
bff, web, mobile
@oshun/errors
bff, web, mobile
@oshun/logging
bff, svc-ai, svc-tts, service-lib
@oshun/http-client
bff, web, mobile
@oshun/auth-primitives
web, mobile
@oshun/tracing
service-lib
@oshun/metrics
service-lib
@oshun/config
bff
Internal @lilith/* Libraries Used by Services#
Nearly all services depend on:
@lilith/fastify-core (server bootstrap)
@lilith/service-lib (operational utilities)
@lilith/testing (test fixtures, dev dependency)
Services with database access additionally use:
@lilith/database (Knex connection pooling)
@lilith/config (environment validation)
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
Configuration#
Environment Variables#
bash Copy
# Required
LILITH_DATABASE_URL=postgresql://...?schema=lilith
REDIS_URL=redis://localhost:6379
# Content Storage
MEDITATION_BUCKET=oshun-lilith-content
MEDITATION_CDN_URL=https://content.lilith.io
# AI
OPENAI_API_KEY=sk-...
# Push Notifications
FIREBASE_PROJECT_ID=...
FIREBASE_PRIVATE_KEY=...
# TTS
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
# Health Integrations (optional)
APPLE_HEALTHKIT_ENABLED=true
GOOGLE_FIT_CLIENT_ID=...
Development#
bash Copy
# 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
# Run database migrations for auth service
cd apps/lilith/svc-auth && pnpm db:migrate
# Start web app
cd apps/lilith/web && pnpm dev
# Start mobile app
cd apps/lilith/mobile && pnpm start
Legacy Documentation#
Lilith has extensive pre-monorepo documentation at docs/domains/lilith/extras/
(440+ files) covering architecture, product specs, infrastructure, coding
guidelines, and go-live checklists. Key files:
Document
Path
Architecture
docs/domains/lilith/extras/ARCHITECTURE.md
Product Spec
docs/domains/lilith/extras/PRODUCT.md
Local Dev Guide
docs/domains/lilith/extras/LOCAL_DEVELOPMENT_GUIDE.md
Infrastructure
docs/domains/lilith/extras/INFRASTRUCTURE_SETUP.md
Coding Standards
docs/domains/lilith/extras/CODING_GUIDELINES.md
Go-Live Checklist
docs/domains/lilith/extras/GO_LIVE_CHECKLIST.md
API Gap Analysis
docs/domains/lilith/extras/OPENAPI_DOCUMENTATION_GAP_ANALYSIS.md