Sanctuaire User Flow

Directory Structure

apps/web/app/sanctuaire/
├── page.tsx                 # Main portal (post-login)
├── layout.tsx               # Sanctuaire layout with auth
├── SanctuaireLayoutClient.tsx
├── login/                   # Magic link login
├── profile/                 # User profile management
├── insights/                # AI-generated insights grid
├── path/                    # 7-day spiritual timeline
├── chat/                    # Chat with Oracle Lumira
├── draws/                   # Tarot/oracle draws
├── synthesis/               # Overall reading synthesis
└── settings/                # User preferences

Product Tiers

Defined in: packages/shared/src/constants/catalog.ts

Authentication Flow

Token Storage

// User tokens (Sanctuaire)
localStorage.getItem('sanctuaire_token')  // JWT
localStorage.getItem('lumira_token')      // Legacy alias

// Expert tokens (Admin Desk)
localStorage.getItem('expert_token')      // Admin JWT

Contexts

// apps/web/context/
├── SanctuaireAuthContext.tsx  // User auth state
├── SanctuaireContext.tsx      // Entitlements & capabilities
├── AuthContext.tsx            // Legacy/general auth
└── ExpertAuthContext.tsx      // Admin auth

Checking Entitlements

'use client';
import { useSanctuaire } from '@/context/SanctuaireContext';

function FeatureComponent() {
  const { 
    capabilities, 
    hasCapability, 
    highestLevel,
    levelMetadata 
  } = useSanctuaire();

  // Check specific capability
  if (!hasCapability('chat_unlimited')) {
    return <UpgradePrompt />;
  }

  // Check level
  if (highestLevel < 2) {
    return <LockedFeature minLevel={2} />;
  }

  return <Feature />;
}

Onboarding Wizard

Component: apps/web/components/onboarding/HolisticWizard.tsx

Multi-step form collecting:

interface OnboardingData {
  // Step 1: Identity
  firstName: string;
  lastName: string;
  email: string;
  
  // Step 2: Birth Data
  birthDate: string;
  birthTime?: string;
  birthPlace?: string;
  
  // Step 3: Life Context
  specificQuestion: string;    // Main spiritual question
  objective: string;           // Life goal
  highs: string;               // Life highlights
  lows: string;                // Life challenges
  
  // Step 4: Photos (optional)
  facePhoto?: File;            // Physiognomy analysis
  palmPhoto?: File;            // Chiromancy analysis
  
  // Step 5: Preferences
  deliveryStyle: 'direct' | 'gentle' | 'poetic';
  pace: number;                // Reading pace 1-5
  
  // Step 6: Deeper Context
  ailments?: string;
  fears?: string;
  rituals?: string;
}

Checkout Flow

1. Stripe Provider

// apps/web/context/StripeProvider.tsx
import { Elements } from '@stripe/react-stripe-js';

<Elements stripe={stripePromise} options={options}>
  <CheckoutForm />
</Elements>

2. Payment Intent Creation

// API: POST /api/payments/create-session
const response = await api.post('/payments/create-session', {
  productId: 'mystique',
  formData: onboardingData,
});
// Returns: { sessionId, url }

3. Webhook Processing

Stripe Webhook (checkout.session.completed)
    │
    ▼
apps/api/src/modules/webhooks/webhooks.controller.ts
    │
    ├─▶ Create Order (status: PAID)
    ├─▶ Trigger VertexOracle.generateCompleteReading()
    ├─▶ Generate PDF via PdfFactory
    └─▶ Send notification email

Post-Purchase Flow

Order Status Flow

PENDING → PAID → PROCESSING → AWAITING_VALIDATION → COMPLETED
                     │               │
                     ▼               ▼
               AI Generation    Expert Review

Content Delivery

1. Insights - Extracted from synthesis → Insight model
2. Timeline - Saved to SpiritualPath + PathStep models
3. PDF - Stored in S3, link in Order.generatedContent
4. Akashic Record - Updated with new session data

Key API Endpoints

// Sanctuaire routes
GET  /api/users/entitlements     // Check user capabilities
GET  /api/users/profile          // Get profile data
PUT  /api/users/profile          // Update profile

// Orders
GET  /api/orders                 // List user orders
GET  /api/orders/:id             // Order details + content

// Insights
GET  /api/insights               // User's insight cards
PUT  /api/insights/:id/view      // Mark as viewed

// Spiritual Path
GET  /api/path                   // Get 7-day timeline
PUT  /api/path/:stepId/complete  // Mark step done

// Chat
POST /api/chat                   // Send message to Lumira
GET  /api/chat/sessions          // List chat sessions
GET  /api/chat/sessions/:id      // Get session messages

UI Components

Key Sanctuaire Components

apps/web/components/sanctuary/
├── InsightsGrid.tsx       # 8-category insight cards
├── TimelineView.tsx       # 7-day path visualization
├── ChatInterface.tsx      # Chat with Lumira
└── SynthesisCard.tsx      # Overview archetype card

apps/web/components/onboarding/
├── HolisticWizard.tsx     # Multi-step form
├── SmartPhotoUploader.tsx # Face/palm photo upload
└── OracleOnboardingChat.tsx # Conversational onboarding

Best Practices