# @lilith - Consciousness Experience Platform

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

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

## Services

```
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](/CLAUDE.md) for detailed local development setup.

## Related Documentation

- [API Reference](/docs/api/lilith/)
- [SDK Documentation](/docs/sdk/lilith/)
- [Partner Integration](/docs/guides/partner-integration.md)
- [Migration Guide](/docs/migration/lilith-migration-guide.md)
