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.