Eve library

@lilith - Consciousness Experience Platform

Other

Revision 1

On this page

Lilith is Oshun's end-user meditation and spiritual exploration platform, providing guided meditations, AI conversations, personalization, and progress tracking.

Overview#

Aspect Description
Domain Consciousness & Meditation
Scope Tag scope:lilith
API Port 4006
Database Schema lilith

Capabilities#

  • Guided Meditations: Audio-based meditation experiences
  • AI Conversations: Personalized spiritual guidance
  • Progress Tracking: Journey analytics and achievements
  • Personalization: Adaptive content recommendations
  • Biometric Integration: Health data sync (opt-in)
  • Community: Shared experiences and groups
  • Subscription Management: Tiered access levels

Libraries#

text
libs/lilith/
├── sdk/                     # TypeScript SDK
├── partner-sdk/             # External partner SDK
├── service-lib/             # Shared service utilities
├── common/                  # Common types/constants
└── event-handlers/          # Event subscriptions

Services#

text
apps/lilith/
├── svc-meditation-core/     # Core meditation service
├── svc-auth-orchestrator/   # Auth coordination
├── svc-notification/        # Push notifications
├── svc-real-time-sync/      # WebSocket sync
├── svc-catalog/             # Content catalog
├── svc-daily-content/       # Daily recommendations
├── svc-progress-sync/       # User progress
├── svc-biometric/           # Health data integration
├── svc-meditation-generation/ # AI meditation creation
├── svc-creator-royalty/     # Creator payments
├── svc-tiered-subscription/ # Subscription management
├── svc-avatar-cosmetic/     # Avatar customization
├── svc-user-preferences/    # User settings
└── ... (more services)

Quick Start#

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, // seconds
  feedback: { rating: 5 },
});

// Get user progress
const progress = await lilith.progress.get();
console.log(`Streak: ${progress.currentStreak} days`);

Running Locally#

bash
# Start Lilith API gateway
nx serve lilith-api

# Run individual service
nx serve lilith-svc-meditation-core

# Run tests
nx test @lilith/sdk

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

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 Get personalized content
GET /v1/catalog/daily Get daily content

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

Configuration#

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=...

# Health Integrations (optional)
APPLE_HEALTHKIT_ENABLED=true
GOOGLE_FIT_CLIENT_ID=...

Meditation Categories#

Category Description
stress-relief Anxiety and stress reduction
sleep Sleep improvement
focus Concentration and productivity
spiritual Spiritual exploration
movement Mindful movement
breathwork Breathing exercises
visualization Guided imagery

Subscription Tiers#

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

Partner Integration#

typescript
import { createPartnerClient } from '@lilith/partner-sdk';

const partner = createPartnerClient({
  apiKey: process.env.PARTNER_API_KEY,
});

// Embed meditation in partner app
const embed = await partner.embeds.create({
  meditationId: 'med-123',
  branding: {
    primaryColor: '#6B46C1',
    logo: 'https://partner.com/logo.png',
  },
});

console.log(`Embed URL: ${embed.url}`);

Local Development#

Start the full development environment:

bash
# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose -f docker/docker-compose.dev.yml up -d

# Run shared database migrations
pnpm nx run @oshun/database:prisma:migrate:dev

# Start the API
pnpm nx serve lilith-api

See CLAUDE.md for detailed local development setup.