# Metaverse Sessions System

Technical documentation for Lilith's comprehensive session management system
covering group meditation, AI-guided instruction, healing circles, and metaverse
integration.

## Overview

The Lilith Platform implements a unified session management framework
supporting:

- **Group Meditation**: Synchronized breathing and intention sharing
- **AI Teachers**: Personalized instruction with procedural personalities
- **Healing Circles**: Collective energy transmission and guardian presence
- **Dream Circles**: Shared dream exploration and symbol analysis
- **Philosophy Forums**: Discourse and dialectic sessions
- **Telepathy Experiments**: Collective consciousness research
- **Virtual Retreats**: Multi-day immersive experiences
- **Yoga Sessions**: AI instructor with real-time animation

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                       Sessions Architecture                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    Session Management Layer                      │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │    │
│  │  │   Session   │  │  Lifecycle  │  │   Participant           │  │    │
│  │  │   Builder   │──│   Manager   │──│   Manager               │  │    │
│  │  │             │  │(State Machine)│ │  (Join/Leave/State)    │  │    │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                  Real-Time Sync Layer                            │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────┐  │    │
│  │  │   WebSocket   │  │  Audio Sync   │  │   Breathing Sync    │  │    │
│  │  │   Handler     │──│  Coordinator  │──│   (Group Harmony)   │  │    │
│  │  │               │  │               │  │                     │  │    │
│  │  └───────────────┘  └───────────────┘  └─────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                  Specialized Session Layer                       │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────┐  │    │
│  │  │   Healing     │  │    Dream      │  │   AI Teacher        │  │    │
│  │  │   Circles     │──│   Circles     │──│   Sessions          │  │    │
│  │  │               │  │               │  │                     │  │    │
│  │  └───────────────┘  └───────────────┘  └─────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Session Types

### Overview Table

| Session Type         | Collection                   | Max Participants | Key Features                       |
| -------------------- | ---------------------------- | ---------------- | ---------------------------------- |
| **Group Meditation** | `group_sessions`             | 12               | Synchronized breathing, intentions |
| **Telepathy**        | `telepathy_experiments`      | Unlimited        | Signal metrics, collective focus   |
| **Philosophy Forum** | `philosophy_forums`          | Unlimited        | Discourse, milestone tracking      |
| **Dream Circle**     | `dream_sharing_circles`      | 8                | Symbol analysis, integration       |
| **Healing Circle**   | `collective_healing_circles` | 12               | Energy transmission, guardians     |
| **Rituals**          | `rituals`                    | Variable         | Progression, checkpoints           |
| **AI Teacher**       | `personal_ai_teachers`       | 1                | Personalized, adaptive             |
| **Yoga**             | (3D only)                    | 20               | Animation, form correction         |

---

## Core Session Management

### Session State Machine

**Location**: `services/meditation-core/src/session.ts`

```
┌───────────┐
│   IDLE    │
└─────┬─────┘
      │ START
      ▼
┌───────────┐     ┌───────────┐
│ PREPARING │────→│  ACTIVE   │◄────┐
└───────────┘     └─────┬─────┘     │
                        │           │
                   PAUSE│     RESUME│
                        ▼           │
                  ┌───────────┐     │
                  │  PAUSED   │─────┘
                  └───────────┘
                        │
                   COMPLETE
                        ▼
                  ┌───────────┐
                  │COMPLETING │
                  └─────┬─────┘
                        │
                        ▼
                  ┌───────────┐     ┌───────────┐
                  │ COMPLETED │     │ CANCELLED │
                  └───────────┘     └───────────┘
                                          ▲
                                    CANCEL│
                                   (from any)
```

#### Session States

| State        | Description                       |
| ------------ | --------------------------------- |
| `IDLE`       | Initial state, not started        |
| `PREPARING`  | Setup phase, participants joining |
| `ACTIVE`     | Session in progress               |
| `PAUSED`     | Temporarily paused                |
| `COMPLETING` | Wrapping up, final stage          |
| `COMPLETED`  | Successfully finished             |
| `CANCELLED`  | Terminated early                  |

#### State Events

| Event      | Description               |
| ---------- | ------------------------- |
| `START`    | Begin session             |
| `PAUSE`    | Pause session             |
| `RESUME`   | Resume from pause         |
| `COMPLETE` | Finish session            |
| `CANCEL`   | Cancel session            |
| `TIMEOUT`  | Auto-cancel on inactivity |
| `ERROR`    | Error occurred            |

### Session Manager

```typescript
import { createSessionManager } from '@/meditation-core/session';

const manager = createSessionManager({
  db: mongoClient,
  audioService: audioService,
  analyticsService: analyticsService,
});

// Create session
const session = await manager.createSession({
  tradition: 'zen',
  duration: 1800, // 30 minutes
  facilitatorId: 'user123',
  intention: 'Cultivating inner peace',
  maxParticipants: 12,
});

// Transition states
await manager.transition(session, 'START');
await manager.transition(session, 'PAUSE');
await manager.transition(session, 'RESUME');
await manager.transition(session, 'COMPLETE');

// Get summary
const summary = manager.getSummary(session);
```

### Meditation Stages

Sessions progress through structured stages:

| Stage             | Duration % | Purpose              |
| ----------------- | ---------- | -------------------- |
| **ARRIVAL**       | 10%        | Welcome, grounding   |
| **BREATH**        | 20%        | Breathing exercises  |
| **BODY**          | 20%        | Body scan awareness  |
| **VISUALIZATION** | 35%        | Guided visualization |
| **INTEGRATION**   | 15%        | Closing, integration |

```typescript
// Progress to next stage
await manager.progressStage(session);

// Generate stage script
const script = await manager.generateScript(session);

// Synthesize audio from script
const audio = await manager.synthesizeAudio(session);
```

---

## Group Meditation Sessions

### Session Builder

**Location**: `services/group-meditation/src/group-session-builder.ts`

```typescript
import { buildGroupSessionRecord } from '@/group-session-builder';

const session = buildGroupSessionRecord(
  {
    name: 'Morning Zen Meditation',
    tradition: 'zen',
    duration: 1800,
    facilitatorId: 'facilitator123',
    intention: 'Starting the day with clarity',
    maxParticipants: 12,
    allowLateJoin: true,
    guidanceLevel: 'intermediate',
  },
  context
);
```

### Session Structure

```typescript
interface GroupSession {
  id: string;
  name: string;
  tradition: TraditionType;
  status: SessionStatus;
  facilitatorId: string;
  intention: string;

  // Participants
  participants: Set<string>;
  maxParticipants: number;
  allowLateJoin: boolean;

  // Configuration
  duration: number;
  guidanceLevel: GuidanceLevel;
  audioLayers: string[];
  collaborationTags: string[];

  // Timing
  createdAt: Date;
  startedAt?: Date;
  endedAt?: Date;
  scheduledFor?: Date;
}
```

### Tradition Configurations

| Tradition   | Audio Layers            | Collaboration Tags  |
| ----------- | ----------------------- | ------------------- |
| **Zen**     | shakuhachi, temple_bell | compassion, clarity |
| **Stoic**   | lyre, wind              | resilience, reason  |
| **Sufi**    | ney, frame_drum         | devotion, whirling  |
| **General** | ambient, heartbeat      | unity, breath       |

### Create Session

**Location**: `services/group-meditation/src/group-session-create-service.ts`

```typescript
import { createGroupSession } from '@/group-session-create-service';

const session = await createGroupSession({
  sessionData: {
    name: 'Evening Sufi Circle',
    tradition: 'sufi',
    duration: 2700, // 45 minutes
    intention: 'Opening the heart',
  },
  sessions: sessionMap,
  updateSessionInDatabase: db.updateSession,
});
```

---

## Participant Management

### Joining Sessions

**Location**: `services/group-meditation/src/group-session-join-service.ts`

```typescript
import { joinSession, JoinSessionError } from '@/group-session-join-service';

try {
  const participant = await joinSession(
    {
      sessionId: 'session123',
      userId: 'user456',
      displayName: 'John',
      deviceCapabilities: {
        audioPlayback: true,
        spatialAudio: true,
        binauralBeats: true,
      },
    },
    dependencies
  );
} catch (error) {
  if (error instanceof JoinSessionError) {
    if (error.code === 'session.late_join_forbidden') {
      // Session already started
    } else if (error.code === 'session.full') {
      // Max participants reached
    }
  }
}
```

### Participant State

```typescript
interface SessionParticipant {
  participantId: string;
  userId: string;
  displayName: string;
  deviceCapabilities: DeviceCapabilities;
  joinedAt: Date;
  state: ParticipantState;
  progress: ParticipantProgress;
}

interface ParticipantProgress {
  position: number; // 0-1 progress through session
  focusLevel: number; // 0-1 focus metric
  heartRate?: number;
  stressLevel?: number;
}

type ParticipantState =
  | 'preparing' // Just joined, setting up
  | 'active' // Actively participating
  | 'paused' // Temporarily paused
  | 'completed'; // Finished session
```

### Leaving Sessions

**Location**: `services/group-meditation/src/group-session-leave-service.ts`

```typescript
import { leaveSession } from '@/group-session-leave-service';

await leaveSession(
  {
    sessionId: 'session123',
    userId: 'user456',
  },
  dependencies
);
```

---

## Real-Time Synchronization

### WebSocket Connection

**Location**: `services/group-meditation/src/session-websocket-route.js`

```typescript
// Client connection
const socket = new WebSocket('wss://api.lilith.app/v1/ws/session');

// Authenticate
socket.send(
  JSON.stringify({
    type: 'auth',
    token: jwtToken,
  })
);

// Join session
socket.send(
  JSON.stringify({
    type: 'join_session',
    sessionId: 'session123',
  })
);

// Leave session
socket.send(
  JSON.stringify({
    type: 'leave_session',
    sessionId: 'session123',
  })
);

// Update state
socket.send(
  JSON.stringify({
    type: 'state_update',
    sessionId: 'session123',
    state: 'active',
    progress: {
      position: 0.45,
      focusLevel: 0.85,
    },
  })
);

// Send chat
socket.send(
  JSON.stringify({
    type: 'chat_message',
    sessionId: 'session123',
    content: 'Beautiful session everyone',
  })
);

// Ping
socket.send(
  JSON.stringify({
    type: 'ping',
  })
);
```

### Message Types

| Type                 | Direction       | Purpose                       |
| -------------------- | --------------- | ----------------------------- |
| `auth`               | Client → Server | JWT authentication            |
| `join_session`       | Client → Server | Join a session                |
| `leave_session`      | Client → Server | Leave a session               |
| `state_update`       | Client → Server | Update participant state      |
| `audio_sync`         | Bidirectional   | Synchronize audio playback    |
| `chat_message`       | Bidirectional   | Send/receive messages         |
| `ping`               | Client → Server | Heartbeat                     |
| `participant_joined` | Server → Client | New participant notification  |
| `participant_left`   | Server → Client | Participant left notification |
| `session_started`    | Server → Client | Session began                 |
| `session_ended`      | Server → Client | Session concluded             |

### Audio Synchronization

**Location**: `services/group-meditation/src/group-session-audio-sync.js`

```typescript
import { handleAudioSyncCommand } from '@/group-session-audio-sync';

// Synchronize playback
handleAudioSyncCommand(
  {
    sessionId: 'session123',
    action: 'play', // play, pause, seek, resume
    position: 120.5, // seconds
    timestamp: Date.now(),
  },
  context
);
```

#### Sync Actions

| Action   | Description                    |
| -------- | ------------------------------ |
| `play`   | Start playback at position     |
| `pause`  | Pause playback                 |
| `seek`   | Jump to position               |
| `resume` | Continue from current position |

### Broadcasting Events

**Location**: `services/group-meditation/src/group-session-broadcast.js`

```typescript
import { broadcastSessionEvent } from '@/group-session-broadcast';

// Broadcast to all participants
broadcastSessionEvent(
  {
    type: 'participant_joined',
    sessionId: 'session123',
    participant: {
      userId: 'user456',
      displayName: 'John',
    },
    totalParticipants: 8,
  },
  wsConnections
);
```

---

## Metaverse Group Meditation

### Group Meditation Circles

**Location**: `services/metaverse/src/advanced/GroupMeditationCircles.ts`

3D synchronized meditation with visual breathing and energy feedback.

#### Circle Configuration

```typescript
interface MeditationCircle {
  id: string;
  name: string;
  center: [number, number, number]; // 3D position
  radius: number;
  maxParticipants: number;
  participants: Map<string, Participant>;
  leader: string | null;
  active: boolean;
  startTime: number;
  duration: number;
  intention: string;
}

interface Participant {
  userId: string;
  position: [number, number, number];
  breathingPhase: number; // 0-1
  breathingRate: number; // breaths per minute
  synchronized: boolean;
  energyContribution: number;
  meditationDepth: number;
}
```

#### Usage

```typescript
import { GroupMeditationCircles } from '@/advanced/GroupMeditationCircles';

const circles = new GroupMeditationCircles();

// Create circle
const circle = circles.createCircle({
  name: 'Sunrise Meditation',
  center: [0, 0, 0],
  radius: 5,
  maxParticipants: 12,
  duration: 1800,
  intention: 'Welcoming the new day',
});

// Join circle (auto-positions in circle)
circles.joinCircle(circle.id, 'user123');

// Start synchronized session
circles.startSession(circle.id);

// Update meditation depth
circles.updateParticipantDepth(circle.id, 'user123', 0.85);

// Update in render loop
function update(deltaTime: number) {
  circles.update(circle.id, deltaTime);
}

// End session and get stats
const stats = circles.endSession(circle.id);
```

#### Breathing Synchronization

Breathing pattern: 4:4:6:2 (inhale:hold:exhale:pause)

```typescript
const BREATHING_PATTERN = {
  inhale: 4, // 4 seconds
  hold: 4, // 4 seconds
  exhale: 6, // 6 seconds
  pause: 2, // 2 seconds
};

// Total cycle: 16 seconds
const CYCLE_DURATION = 16;

// Breathing phase calculation
function updateBreathing(participant: Participant, deltaTime: number) {
  const cycleProgress = (Date.now() % (CYCLE_DURATION * 1000)) / 1000;

  if (cycleProgress < 4) {
    participant.breathingPhase = cycleProgress / 4; // Inhale
  } else if (cycleProgress < 8) {
    participant.breathingPhase = 1; // Hold
  } else if (cycleProgress < 14) {
    participant.breathingPhase = 1 - (cycleProgress - 8) / 6; // Exhale
  } else {
    participant.breathingPhase = 0; // Pause
  }
}
```

#### Collective Energy System

```typescript
interface CollectiveEnergy {
  totalEnergy: number;
  harmony: number; // 0-1, based on breathing sync
  resonanceFactor: number; // Amplification multiplier
  visualColor: Color; // Blue → Purple based on harmony
}

// Harmony calculation
function calculateHarmony(participants: Participant[]): number {
  const phases = participants.map((p) => p.breathingPhase);
  const avgPhase = phases.reduce((a, b) => a + b, 0) / phases.length;

  // Calculate deviation from average
  const deviation =
    phases.reduce((sum, phase) => sum + Math.abs(phase - avgPhase), 0) /
    phases.length;

  // High harmony = low deviation
  return 1 - deviation * 2;
}
```

---

## Specialized Sessions

### Healing Circles

**Location**: `services/group-meditation/src/healing-circle-*.ts`

Collective energy healing with transmission tracking.

```typescript
interface HealingCircle {
  id: string;
  name: string;
  intention: string;
  participants: HealingParticipant[];
  transmissions: EnergyTransmission[];
  guardians: string[]; // Guardian presence IDs
  metrics: HealingMetrics;
}

interface EnergyTransmission {
  id: string;
  senderId: string;
  receiverId: string;
  type: 'direct' | 'collective' | 'earth';
  intensity: number;
  timestamp: Date;
}

interface HealingMetrics {
  totalTransmissions: number;
  activeHealers: number;
  guardianPresence: number;
  collectiveIntensity: number;
}
```

#### API Endpoints

```typescript
// Create healing circle
POST /v1/healing-circles
{
  "name": "Full Moon Healing",
  "intention": "Collective healing for all beings"
}

// Record transmission
POST /v1/healing-circles/:circleId/transmissions
{
  "receiverId": "recipient123",
  "type": "direct",
  "intensity": 0.8
}

// Complete circle
POST /v1/healing-circles/:circleId/complete
```

### Dream Circles

**Location**: `services/group-meditation/src/dream-circle-*.ts`

Shared dream exploration with symbol analysis.

```typescript
interface DreamCircle {
  id: string;
  name: string;
  participants: DreamParticipant[];
  dreamLog: DreamEntry[];
  symbolHighlights: Symbol[];
  metrics: DreamMetrics;
}

interface DreamEntry {
  id: string;
  participantId: string;
  content: string;
  symbols: string[];
  emotions: string[];
  lucidity: number; // 0-1
  vividness: number; // 0-1
  timestamp: Date;
}

interface Symbol {
  name: string;
  frequency: number;
  interpretations: string[];
}
```

### Philosophy Forums

**Location**: `services/group-meditation/src/philosophy-session-service.js`

Discourse and dialectic sessions with milestone tracking.

```typescript
interface PhilosophyForum {
  id: string;
  topic: string;
  tradition: string; // stoic, eastern, existential, etc.
  participants: ForumParticipant[];
  contributions: Contribution[];
  nextMilestone: Milestone;
  metrics: ForumMetrics;
}

interface Contribution {
  id: string;
  participantId: string;
  type: 'argument' | 'question' | 'reflection' | 'synthesis';
  content: string;
  references: string[];
  votes: number;
}
```

### Telepathy Experiments

**Location**: `services/group-meditation/src/telepathy-session-service.ts`

Collective consciousness research sessions.

```typescript
interface TelepathyExperiment {
  id: string;
  experimentType: 'sender_receiver' | 'collective_focus' | 'remote_viewing';
  participants: TelepathyParticipant[];
  signals: SignalRecord[];
  metrics: TelepathyMetrics;
  sessionLog: LogEntry[];
}

interface SignalRecord {
  senderId: string;
  targetImage?: string;
  receiverGuesses: Guess[];
  accuracy: number;
  timestamp: Date;
}
```

### Rituals

**Location**: `services/group-meditation/src/ritual-*.ts`

Structured ritual progression with checkpoints.

```typescript
interface Ritual {
  id: string;
  name: string;
  tradition: string;
  phases: RitualPhase[];
  currentPhase: number;
  progress: number; // 0-1
  participants: RitualParticipant[];
}

interface RitualPhase {
  name: string;
  duration: number;
  instructions: string;
  requirements: string[];
  completed: boolean;
}
```

#### API Endpoints

```typescript
// Design ritual
POST /v1/rituals
{
  "name": "New Moon Ceremony",
  "tradition": "earth",
  "phases": [...]
}

// Record progress
POST /v1/rituals/:ritualId/progress
{
  "phaseIndex": 2,
  "completed": true,
  "notes": "..."
}

// Complete ritual
POST /v1/rituals/:ritualId/complete
```

---

## AI Teacher Sessions

### Personal AI Teacher

**Location**: `services/group-meditation/src/personal-ai-teacher-*.ts`

Personalized instruction with adaptive learning.

```typescript
interface PersonalAITeacher {
  id: string;
  architectId: string; // Creator of the teacher
  studentId: string;
  personality: TeacherPersonality;
  curriculum: Module[];
  progress: LearnerProgress;
  insights: PersonalizationInsights;
}

interface LearnerProgress {
  trainingSessionCount: number;
  currentModule: number;
  completedModules: string[];
  averageSatisfaction: number;
  lastCalibrationAt: Date;
}

interface PersonalizationInsights {
  attunementScore: number;
  nervousSystemState: string;
  recommendedPractices: string[];
  ritualSupport: string[];
}

interface TeacherPersonality {
  warmth: number;
  patience: number;
  directness: number;
  humor: number;
  mysticism: number;
}
```

### AI Teacher Generation

**Location**:
`services/ai/src/ai-teacher-generation/ai-teacher-generation-service.ts`

Procedural generation of unique AI personalities.

#### OCEAN Personality Model

```typescript
interface OCEANPersonality {
  openness: {
    score: number;
    facets: {
      imagination: number;
      artisticInterests: number;
      emotionality: number;
      adventurousness: number;
      intellect: number;
      liberalism: number;
    };
  };
  conscientiousness: {
    score: number;
    facets: {
      selfEfficacy: number;
      orderliness: number;
      dutifulness: number;
      achievementStriving: number;
      selfDiscipline: number;
      cautiousness: number;
    };
  };
  extraversion: {
    score: number;
    facets: {
      friendliness: number;
      gregariousness: number;
      assertiveness: number;
      activityLevel: number;
      excitementSeeking: number;
      cheerfulness: number;
    };
  };
  agreeableness: {
    score: number;
    facets: {
      trust: number;
      morality: number;
      altruism: number;
      cooperation: number;
      modesty: number;
      sympathy: number;
    };
  };
  neuroticism: {
    score: number;
    facets: {
      anxiety: number;
      anger: number;
      depression: number;
      selfConsciousness: number;
      immoderation: number;
      vulnerability: number;
    };
  };
}
```

#### Teacher Components

| Component                | Description                               |
| ------------------------ | ----------------------------------------- |
| **OCEAN Personality**    | 128-dimensional personality vectors       |
| **Teaching Style**       | Pacing, depth, interactivity              |
| **Spiritual Dimensions** | Tradition alignment                       |
| **Behavior Tree AI**     | Decision-making system                    |
| **Memory Systems**       | Short-term, long-term, episodic, semantic |
| **Emotional Modeling**   | Responsive to student state               |
| **Voice Generation**     | Unique voice characteristics              |
| **Avatar Generation**    | 3D appearance                             |

### Yoga Instructor

**Location**:
`services/ai/src/yoga-instructor-animation/yoga-instructor-animation-service.ts`

AI-driven yoga instruction with real-time animation.

#### Features

| Feature                      | Description                   |
| ---------------------------- | ----------------------------- |
| **Skeletal Animation**       | Full-body pose animation      |
| **Pose Modifications**       | Variants for different levels |
| **Breath Visualization**     | Synchronized with movement    |
| **Muscle Highlighting**      | Active muscle groups          |
| **Transition Interpolation** | Smooth pose-to-pose flow      |
| **Biomechanics Validation**  | Anatomically correct          |
| **Speed Variation**          | Adjustable difficulty         |
| **Mirror Mode**              | Student alignment assistance  |

---

## Session Analytics

### Analytics Service

**Location**: `services/group-meditation/src/group-session-analytics.ts`

```typescript
interface SessionAnalytics {
  sessionId: string;
  duration: number;
  timeline: TimelineEvent[];
  participantStats: {
    total: number;
    completed: number;
    avgJoinTime: number;
    engagementScore: number;
  };
  eventCounts: {
    audioSync: number;
    chatMessages: number;
    stateChanges: number;
  };
}

import { formatSessionAnalytics } from '@/group-session-analytics';

const analytics = formatSessionAnalytics(session, events);
```

### Event Tracking

**Location**: `services/group-meditation/src/session-event-service.ts`

```typescript
import { recordSessionEvent } from '@/session-event-service';

await recordSessionEvent(
  {
    sessionId: 'session123',
    type: 'participant_joined',
    participantId: 'user456',
    timestamp: new Date(),
    metadata: {
      deviceType: 'mobile',
      audioCapabilities: ['stereo', 'spatial'],
    },
  },
  db
);
```

#### Event Types

| Event                | Description               |
| -------------------- | ------------------------- |
| `participant_joined` | User joined session       |
| `participant_left`   | User left session         |
| `session_started`    | Session began             |
| `session_ended`      | Session concluded         |
| `state_update`       | Participant state changed |
| `audio_sync`         | Audio synchronized        |
| `chat_message`       | Chat sent                 |

---

## API Reference

### Session Routes

**Location**: `services/group-meditation/src/session-routes.js`

```typescript
// Create session
POST /v1/sessions
{
  "name": "Morning Meditation",
  "tradition": "zen",
  "duration": 1800,
  "intention": "Starting with clarity",
  "maxParticipants": 12
}

// Get session
GET /v1/sessions/:sessionId

// List sessions
GET /v1/sessions
  ?status=waiting|active|completed
  &tradition=zen|stoic|sufi|general
  &facilitatorId=user123
```

### Lifecycle Routes

**Location**: `services/group-meditation/src/session-lifecycle-routes.js`

```typescript
// Start session (facilitator only)
POST /v1/sessions/:sessionId/start

// End session (facilitator only)
POST /v1/sessions/:sessionId/end

// Get analytics
GET /v1/sessions/:sessionId/analytics
```

### AI Teacher Routes

**Location**: `services/group-meditation/src/personal-ai-teacher-routes.js`

```typescript
// Create teacher
POST /v1/ai-teachers
{
  "personality": {
    "warmth": 0.8,
    "patience": 0.9,
    "directness": 0.6
  },
  "traditions": ["zen", "stoic"]
}

// Update progress
POST /v1/ai-teachers/:teacherId/progress
{
  "moduleId": "breath-awareness",
  "completed": true,
  "satisfaction": 0.95,
  "reflection": "Deep insights today"
}
```

---

## Persistence

### MongoDB Collections

| Collection                   | Purpose                |
| ---------------------------- | ---------------------- |
| `group_sessions`             | Core session data      |
| `session_events`             | Event timeline         |
| `telepathy_experiments`      | Telepathy sessions     |
| `philosophy_forums`          | Philosophy discussions |
| `dream_sharing_circles`      | Dream circles          |
| `collective_healing_circles` | Healing circles        |
| `rituals`                    | Ritual data            |
| `personal_ai_teachers`       | AI teacher instances   |

### Session Snapshots

**Location**: `services/group-meditation/src/group-session-shape.ts`

```typescript
import { createSessionPersistenceSnapshot } from '@/group-session-shape';

// Prepare session for database
const snapshot = createSessionPersistenceSnapshot(session);
// Converts Set<participants> to Array

// Save to database
await db
  .collection('group_sessions')
  .updateOne({ _id: session.id }, { $set: snapshot }, { upsert: true });
```

### Two-Tier Caching

**Location**: `services/group-meditation/src/group-session-runtime-service.ts`

```typescript
// 1. Check in-memory cache
let session = runtimeMap.get(sessionId);

// 2. Fall back to database
if (!session) {
  session = await db.collection('group_sessions').findOne({ _id: sessionId });
  session = ensureSessionShape(session);
  runtimeMap.set(sessionId, session);
}
```

---

## Biometric Integration

### Supported Biometrics

| Type               | Description             |
| ------------------ | ----------------------- |
| `heart_rate`       | BPM from wearables      |
| `hrv`              | Heart rate variability  |
| `breathing_rate`   | Breaths per minute      |
| `skin_conductance` | Galvanic skin response  |
| `brain_wave`       | EEG data (if available) |

### Recording Biometrics

```typescript
import { recordBiometric } from '@/meditation-core/session';

await recordBiometric(session, {
  type: 'heart_rate',
  value: 68,
  timestamp: Date.now(),
});

await recordBiometric(session, {
  type: 'hrv',
  value: 45,
  timestamp: Date.now(),
});
```

---

## Integration Examples

### Complete Group Session Flow

```typescript
import { createGroupSession } from '@/group-session-create-service';
import { joinSession } from '@/group-session-join-service';
import { broadcastSessionEvent } from '@/group-session-broadcast';

// 1. Create session
const session = await createGroupSession({
  sessionData: {
    name: 'Evening Zen Circle',
    tradition: 'zen',
    duration: 1800,
    intention: 'Finding stillness',
  },
  sessions: sessionMap,
  updateSessionInDatabase: db.updateSession,
});

// 2. Participants join
for (const userId of participants) {
  await joinSession(
    {
      sessionId: session.id,
      userId,
      displayName: users[userId].name,
    },
    deps
  );
}

// 3. Start session
await startSession(session);
broadcastSessionEvent(
  {
    type: 'session_started',
    sessionId: session.id,
  },
  connections
);

// 4. Audio sync during session
handleAudioSyncCommand(
  {
    sessionId: session.id,
    action: 'play',
    position: 0,
  },
  context
);

// 5. End session
const stats = await endSession(session);
broadcastSessionEvent(
  {
    type: 'session_ended',
    sessionId: session.id,
    stats,
  },
  connections
);
```

### Metaverse Meditation Circle

```typescript
import { GroupMeditationCircles } from '@/advanced/GroupMeditationCircles';

const circles = new GroupMeditationCircles();

// Create 3D circle
const circle = circles.createCircle({
  name: 'Sacred Grove Meditation',
  center: [0, 0, 0],
  radius: 8,
  maxParticipants: 12,
  duration: 2700,
  intention: 'Connecting with nature',
});

// Add participants with 3D positioning
circles.joinCircle(circle.id, 'user1');
circles.joinCircle(circle.id, 'user2');
circles.joinCircle(circle.id, 'user3');

// Start synchronized session
circles.startSession(circle.id);

// Game loop
function animate() {
  const delta = clock.getDelta();

  // Update breathing sync and energy
  circles.update(circle.id, delta);

  // Get visual feedback data
  const energy = circles.getCollectiveEnergy(circle.id);
  updateEnergyVisualization(energy);

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
```

---

## Best Practices

### Do's

- Validate session capacity before joining
- Use state machine for predictable transitions
- Persist events for analytics
- Sync audio across all participants
- Track biometrics when available
- Clean up resources on session end

### Don'ts

- Don't allow state transitions out of order
- Don't exceed max participant limits
- Don't skip session persistence
- Don't ignore late-join restrictions
- Don't broadcast to disconnected clients

---

## Related Documentation

- [Networking](./networking.md)
- [Avatar System](./avatar-system.md)
- [Animation System](./animation-system.md)
- [Environments](./environments.md)

---

_Last Updated: January 2026_
