Eve library

Lilith Domain Architecture

Guide

Revision 1

On this page

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:

  1. Core Platform -- BFF gateway, authentication, conversation, content management, media processing
  2. AI and Knowledge -- LLM orchestration, Sophia-backed retrieval, search, and knowledge graph access
  3. Meditation and Wellness -- Meditation sessions, breathwork, yoga, group meditation, spiritual guidance, journal
  4. Voice and Audio -- TTS (Chatterbox), STT, voice pipeline, audio handoff, WebRTC
  5. Content and Delivery -- Catalog, daily content, curricula, review, moderation, content licensing
  6. User and Progress -- User preferences, progress sync, offline, cross-device sync, biometric, notifications
  7. Commerce -- Tiered subscriptions, payment orchestration, creator royalties, partner API
  8. Web3 and Blockchain -- Native token, staking, DeFi, DAO governance, IPFS, cross-chain bridge, NFT/token verification, micro-transactions, fiat ramp, settlement
  9. Immersive -- Metaverse (VR/AR), avatar cosmetics, AI generation routes, Veilborn tabletop RPG
  10. Infrastructure -- Observability, error handling, operational excellence, multi-region resilience, data governance, anonymization, safety automation
  11. Localization -- Language detection, community translation
  12. 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

Core Platform Services (11)#

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
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
                   @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
  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
  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
  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
  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
                         +-------------------+
                         |  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
# 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
# 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