Eve library

Metaverse Sessions System

Guide

Revision 1

On this page

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#

text
┌─────────────────────────────────────────────────────────────────────────┐
│                       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

text
┌───────────┐
│   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


Last Updated: January 2026