Skip to content

Web Portal Implementation Plan

Project: Archety Web Portal - Personality-Based AI Companion Onboarding Created: November 13, 2025 Last Updated: November 13, 2025 - Phase 1 Complete Frontend: /Users/justin-genies/code/archety-web (Next.js + TypeScript) Backend: /Users/justin-genies/Code/archety (FastAPI + Python) Status: Phase 1 Complete ✅ - Onboarding Flow Fully Functional

🎯 Project Overview

User Flow

  1. Landing - User accesses website on mobile web
  2. Photo Upload - User selects 10 photos to upload
  3. AI Conversation - Quick conversation with AI
  4. Trait Analysis - Photos analyzed for personality traits
  5. Profile Display - Show Big 5 personality + traits + interests
  6. Persona Selection - AI assigned (Sage or Echo, more later)
  7. Phone Verification - Verify via Twilio OTP
  8. Payment - $5 trial payment via Stripe
  9. Chat Launch - iMessage deeplink to start chatting
  10. Dashboard - User home with profile, settings, billing, AI management

Tech Stack

  • Frontend: Next.js 14, TypeScript, Axios, Tailwind CSS
  • Backend: FastAPI, Python, PostgreSQL, SQLAlchemy
  • AI/ML: OpenAI GPT-4o Vision (photo analysis), GPT-5 (chat)
  • External Services: Twilio (SMS/OTP), Stripe (payments), mem0 (memory storage)
  • Hosting: Vercel (frontend), Railway (backend)

✅ What's Been Merged (November 13, 2025)

Branch 1: email-calendar-alerts

  • Purpose: Optimize proactive notification workflows
  • Changes:
  • Use GPT-5-mini for cost-efficient analysis (30% cost reduction)
  • Better error handling and JSON parsing
  • Register all 6 proactive workflows in catalog
  • Improved prompts for user-friendly alerts

Branch 2: photo-upload-system (Traits Framework)

  • Purpose: Personality-based onboarding system
  • Added:
  • app/traits/ module (traits analyzer, traits service)
  • app/api/traits_routes.py - Traits API endpoints
  • Database models: UserTrait, TraitProfile, OnboardingSession
  • Big 5 personality assessment
  • Persona matching algorithm
  • Frontend integration guide (1,700+ lines)

Branch 3: auth-payments-setup

  • Purpose: Complete monetization infrastructure
  • Added:
  • app/identity/ module (phone verification, OTP, sessions)
  • app/payment/ module (Stripe integration, checkouts)
  • app/usage/ module (credit tracking, usage analytics)
  • app/api/auth_routes.py - Authentication endpoints
  • app/api/payment_routes.py - Payment endpoints
  • app/api/usage_routes.py - Usage tracking endpoints
  • Database models: PhoneVerification, CreditTransaction, UsageEvent
  • Session management with HTTP-only cookies
  • Frontend separation package

📋 API Endpoints Status

✅ Implemented (Merged)

Onboarding Endpoints

  • ✅ POST /onboarding/start - Start session (supports anonymous users)
  • ✅ POST /onboarding/upload-photos - Upload photos
  • ✅ GET /onboarding/status/{session_id} - Poll status
  • ✅ GET /onboarding/trait-profile/{session_id} - IMPLEMENTED Nov 13 - Returns Big 5 + traits
  • ✅ GET /onboarding/persona-recommendations/{session_id} - IMPLEMENTED Nov 13 - Returns persona matches
  • ✅ POST /onboarding/select-persona/{session_id} - IMPLEMENTED Nov 13 - Accepts JSON body
  • ✅ GET /onboarding/chat-deeplink/{session_id} - IMPLEMENTED Nov 13 - Returns QR code + deeplink

Auth Endpoints

  • ✅ POST /auth/verify/start - Send OTP
  • ✅ POST /auth/verify/confirm - Verify OTP + create user
  • ✅ GET /auth/session - Get current session
  • ✅ POST /auth/logout - End session

Payment Endpoints

  • ✅ POST /payment/checkout/trial - Create $5 trial checkout
  • ✅ POST /payment/checkout/topup - Create top-up checkout
  • ✅ GET /payment/status/{user_id} - Get payment status
  • ✅ POST /webhooks/stripe - Stripe webhook handler

User/Dashboard Endpoints

  • ⚠️ GET /user/profile - NEEDS IMPLEMENTATION
  • ⚠️ PUT /user/profile - NEEDS IMPLEMENTATION
  • ⚠️ GET /user/settings - NEEDS IMPLEMENTATION
  • ⚠️ PUT /user/settings - NEEDS IMPLEMENTATION

✅ Phase 1 Complete: Onboarding Endpoints (November 13, 2025)

Status: All onboarding endpoints implemented and tested Commit: 22916c6 - "feat: Update onboarding endpoints to match frontend API contracts"

What Was Built: 1. Fixed /onboarding/trait-profile/{session_id} to match frontend TraitProfile interface 2. Created /onboarding/persona-recommendations/{session_id} (NEW ENDPOINT) 3. Updated /onboarding/select-persona/{session_id} to accept JSON body 4. Enhanced /onboarding/chat-deeplink/{session_id} with QR code generation 5. Made /onboarding/start support anonymous users (no phone required initially)

Dependencies Added: - qrcode[pil]>=7.4.0 - For QR code generation

Frontend Integration: - All endpoint response formats now match TypeScript interfaces in archety-web/types/index.ts - No format mismatches remaining - Ready for end-to-end testing

🚧 Phase 2: User Dashboard Endpoints (Priority: HIGH)

Task 1.1: Implement Trait Profile API

File: app/api/traits_routes.py Endpoint: GET /onboarding/trait-profile/{session_id}

Requirements: 

Response = {
  "session_id": str,
  "big_five": {
    "openness": float (0-1),
    "conscientiousness": float (0-1),
    "extraversion": float (0-1),
    "agreeableness": float (0-1),
    "neuroticism": float (0-1)
  },
  "top_traits": [
    {
      "id": str,
      "name": str,
      "description": str,
      "score": float (0-1),
      "category": str  # "personality", "interests", "values"
    }
  ],
  "interests": [str],  # 3-10 interests
  "values": [str],  # 3-8 values
  "profile_completeness": int (0-100),
  "insights": [str]  # 2-5 insights
}

Implementation Steps: 1. Query TraitProfile by session_id → user_id 2. Query UserTrait for top traits (sorted by confidence_score) 3. Format Big 5 personality dimensions 4. Generate insights based on trait combinations 5. Calculate profile completeness 6. Return formatted response

Task 1.2: Implement Persona Recommendations API

File: app/api/traits_routes.py Endpoint: GET /onboarding/persona-recommendations/{session_id}

Requirements: 

Response = {
  "session_id": str,
  "recommendations": [
    {
      "persona": {
        "id": str,  # "sage_001", "echo_001"
        "name": str,  # "sage", "echo"
        "display_name": str,  # "Sage", "Echo"
        "description": str,
        "personality_archetype": str,  # "The Philosopher", "The Explorer"
        "avatar_url": str,
        "traits": [str],
        "best_for": [str]
      },
      "match_score": float (0-1),
      "compatibility_breakdown": {
        "personality_alignment": float (0-1),
        "interest_overlap": float (0-1),
        "communication_style": float (0-1),
        "emotional_compatibility": float (0-1)
      },
      "reasoning": str,
      "why_good_match": [str]  # 2-4 reasons
    }
  ],
  "best_match": {...}  # Copy of highest scoring recommendation
}

Implementation Steps: 1. Load all available personas from app/persona/passports/ 2. Get user's trait profile 3. Calculate match scores for each persona using: - Big 5 personality similarity (cosine similarity) - Interest overlap (Jaccard index) - Communication style matching - Emotional compatibility 4. Sort personas by match_score (descending) 5. Generate reasoning for top 2-3 matches 6. Return formatted recommendations

Persona Files: - app/persona/passports/sage.json - app/persona/passports/echo.json - (Future: add more personas)

Task 1.3: Implement Select Persona API

File: app/api/traits_routes.py or app/api/onboarding_routes.py Endpoint: POST /onboarding/select-persona/{session_id}

Requirements: 

Request = {
  "persona_id": str  # "sage_001" or "echo_001"
}

Response = {
  "success": bool,
  "message": str,
  "selected_persona": {
    "id": str,
    "name": str,
    "display_name": str,
    "description": str,
    "personality_archetype": str,
    "avatar_url": str,
    "traits": [str],
    "best_for": [str]
  }
}

Implementation Steps: 1. Validate session_id exists 2. Validate persona_id is valid 3. Update OnboardingSession.persona_selected 4. Update TraitProfile.selected_persona_id 5. Return success response with persona details

File: app/api/onboarding_routes.py Endpoint: GET /onboarding/chat-deeplink/{session_id}

Requirements: 

Response = {
  "deeplink": str,  # "sms:+15551234567&body=Start"
  "qr_code_data": str,  # Same as deeplink or QR-specific format
  "instructions": str  # User-friendly instructions
}

Implementation Steps: 1. Get user's phone number from session 2. Generate iMessage deeplink: sms:{user_phone}&body=Hi 3. Optionally generate QR code data 4. Return deeplink with instructions

Edge Agent Integration: - When user sends first message via iMessage, Edge Agent should: - Recognize new user by phone number - Load selected persona (Sage or Echo) - Start conversation with persona's personality - Store conversations in mem0 namespace: {user_id}_{persona_id}

Phase 2: Implement User/Dashboard APIs (Priority: HIGH)

Task 2.1: Implement User Profile API

Files: app/api/user_routes.py (create new file) Endpoints: - GET /user/profile - PUT /user/profile

GET /user/profile Response: 

{
  "id": str (UUID),
  "phone": str (E.164 format),
  "name": str,
  "pronouns": str,
  "email": str,
  "createdAt": str (ISO 8601),
  "hasCompletedOnboarding": bool,
  "selectedPersona": {
    "id": str,
    "display_name": str,
    "personality_archetype": str
  },
  "traitProfile": {
    "big_five": {...},
    "top_traits": [...]
  }
}

PUT /user/profile Request: 

{
  "name": str,
  "pronouns": str,
  "email": str
}

Implementation Steps: 1. Create app/api/user_routes.py 2. Add authentication middleware (check session cookie) 3. GET: Query User + TraitProfile + PersonaPassport 4. PUT: Update User model fields 5. Return updated user profile

Task 2.2: Implement User Settings API

File: app/api/user_routes.py Endpoints: - GET /user/settings - PUT /user/settings

GET /user/settings Response: 

{
  "notifications": {
    "sms": bool,
    "email": bool,
    "push": bool
  },
  "privacy": {
    "data_sharing": bool,
    "analytics": bool
  },
  "preferences": {
    "theme": str,  # "auto", "light", "dark"
    "language": str  # "en"
  }
}

Implementation Steps: 1. Create UserSettings database model (or use JSON in User model) 2. GET: Query settings for authenticated user 3. PUT: Update settings (partial updates supported) 4. Return updated settings

Phase 3: Frontend-Backend Integration (Priority: HIGH)

Task 3.1: Configure CORS for Frontend

File: app/main.py

Current CORS: Backend needs to allow frontend origin

Required Changes: 

# Add to app/main.py
allowed_origins = [
    "http://localhost:3000",  # Local development
    "https://archety-web.vercel.app",  # Production frontend (adjust URL)
    "https://archety.com",  # Custom domain (if applicable)
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=allowed_origins,
    allow_credentials=True,  # Required for cookies
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization"],
)

Testing: 1. Test OPTIONS preflight requests 2. Verify cookies are sent/received correctly 3. Test from frontend localhost:3000

Task 3.2: Configure Environment Variables

Files: .env (backend), archety-web/.env.local (frontend)

Backend (.env): 

# Frontend URL for CORS
FRONTEND_URL=http://localhost:3000  # or production URL

# Twilio (Phone Verification)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+15551234567

# Stripe (Payments)
STRIPE_SECRET_KEY=<REDACTED_STRIPE_SECRET_KEY>
STRIPE_WEBHOOK_SECRET=<REDACTED_STRIPE_WEBHOOK_SECRET>

# Session Management
SESSION_SECRET=random-secret-key-change-me
SESSION_COOKIE_NAME=session_id
SESSION_MAX_AGE=2592000  # 30 days

# Database
DATABASE_URL=<REDACTED_POSTGRES_URL>

# OpenAI (for trait analysis)
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

# mem0 (memory storage)
MEM0_API_KEY=your_mem0_api_key

Frontend (.env.local): 

NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8000  # or production URL

Task 3.3: Set Up Stripe Webhooks

Platform: Stripe Dashboard

Steps: 1. Go to Stripe Dashboard → Developers → Webhooks 2. Add endpoint: https://your-backend.railway.app/webhooks/stripe 3. Select events: - checkout.session.completed - charge.succeeded - charge.failed - charge.refunded 4. Copy webhook signing secret to STRIPE_WEBHOOK_SECRET

Test: 

stripe listen --forward-to localhost:8000/webhooks/stripe
stripe trigger checkout.session.completed

Phase 4: Database Setup & Migrations (Priority: CRITICAL)

Task 4.1: Create Database Migration

Tool: Alembic

New Tables to Create: 1. user_traits - Individual personality traits 2. trait_profiles - Aggregated personality profiles 3. onboarding_sessions - Enhanced onboarding tracking 4. phone_verifications - OTP codes 5. credit_transactions - Credit ledger 6. usage_events - Usage tracking

Steps: 

# Generate migration
alembic revision --autogenerate -m "Add traits, auth, payment tables"

# Review migration file in alembic/versions/

# Apply migration
alembic upgrade head

Or use existing migration: - alembic/versions/b2c3d4e5f6g7_add_auth_payment_and_usage_tables.py (from auth-payments branch) - May need to manually add traits tables

Task 4.2: Test Database Schema

File: Create test_database_schema.py

Tests: 1. Create OnboardingSession 2. Create UserTrait + TraitProfile 3. Create PhoneVerification 4. Create CreditTransaction 5. Verify foreign key relationships 6. Test indexes

Phase 5: Persona Matching Algorithm (Priority: MEDIUM)

Task 5.1: Implement Matching Logic

File: app/traits/matching.py (create new file)

Algorithm: 

def calculate_persona_match(user_traits: TraitProfile, persona: PersonaPassport) -> float:
    """
    Calculate match score between user and persona.
    Returns float 0.0-1.0
    """

    # 1. Personality Alignment (40% weight)
    # Compare Big 5 scores using cosine similarity
    personality_score = cosine_similarity(
        user_traits.big_five,
        persona.personality_dimensions
    )

    # 2. Interest Overlap (25% weight)
    # Calculate Jaccard index of interests
    interest_score = jaccard_index(
        set(user_traits.top_interests),
        set(persona.interests)
    )

    # 3. Communication Style (20% weight)
    # Match communication preferences
    comm_score = match_communication_style(
        user_traits.communication_style,
        persona.communication_style
    )

    # 4. Emotional Compatibility (15% weight)
    # Match emotional needs/support style
    emotional_score = match_emotional_compatibility(
        user_traits.emotional_needs,
        persona.support_style
    )

    # Weighted average
    match_score = (
        0.40 * personality_score +
        0.25 * interest_score +
        0.20 * comm_score +
        0.15 * emotional_score
    )

    return match_score

Persona Configuration: Add to app/persona/passports/sage.json: 

{
  "id": "sage_001",
  "name": "sage",
  "display_name": "Sage",
  "description": "A wise, thoughtful companion who values deep conversation",
  "personality_archetype": "The Philosopher",
  "avatar_url": "https://example.com/sage.jpg",
  "traits": ["wise", "thoughtful", "patient", "empathetic"],
  "best_for": ["Deep thinkers", "Introspection", "Philosophical discussions"],
  "personality_dimensions": {
    "openness": 0.85,
    "conscientiousness": 0.70,
    "extraversion": 0.40,
    "agreeableness": 0.80,
    "neuroticism": 0.30
  },
  "interests": ["philosophy", "literature", "psychology", "art", "mindfulness"],
  "communication_style": "reflective",
  "support_style": "empathetic_listener"
}

Similarly add to app/persona/passports/echo.json: 

{
  "id": "echo_001",
  "name": "echo",
  "display_name": "Echo",
  "description": "An energetic, curious companion who loves exploration",
  "personality_archetype": "The Explorer",
  "avatar_url": "https://example.com/echo.jpg",
  "traits": ["energetic", "curious", "spontaneous", "adventurous"],
  "best_for": ["Adventure seekers", "Active lifestyles", "Spontaneous conversations"],
  "personality_dimensions": {
    "openness": 0.90,
    "conscientiousness": 0.55,
    "extraversion": 0.85,
    "agreeableness": 0.75,
    "neuroticism": 0.35
  },
  "interests": ["travel", "adventure", "sports", "technology", "social"],
  "communication_style": "energetic",
  "support_style": "motivational_coach"
}

Phase 6: Testing & Validation (Priority: HIGH)

Task 6.1: End-to-End Testing

Tool: Python pytest + frontend testing

Test Flow: 1. Start onboarding session 2. Upload 10 photos (use test images) 3. Poll status until completed 4. Get trait profile (verify format) 5. Get persona recommendations (verify Sage + Echo) 6. Select persona 7. Start phone verification 8. Confirm OTP code 9. Create trial checkout 10. Simulate Stripe webhook 11. Get payment status 12. Get chat deeplink 13. Test all dashboard endpoints

Create: tests/test_full_onboarding_flow.py

Task 6.2: API Contract Validation

Tool: Postman or Insomnia

Steps: 1. Import API collection from BACKEND_REQUIREMENTS.md 2. Test each endpoint against requirements 3. Verify response schemas match frontend expectations 4. Test error cases (401, 404, 400, 429)

Phase 7: Deployment & Infrastructure (Priority: MEDIUM)

Task 7.1: Deploy Backend to Railway

Platform: Railway

Steps: 1. Connect GitHub repo to Railway 2. Configure environment variables (all from .env) 3. Add PostgreSQL database (Railway addon) 4. Run database migrations on deployment 5. Configure domains (archety-backend-prod.up.railway.app) 6. Set up health check endpoint 7. Configure Stripe webhooks to production URL

Task 7.2: Deploy Frontend to Vercel

Platform: Vercel

Steps: 1. Connect archety-web repo to Vercel 2. Configure environment variable: NEXT_PUBLIC_BACKEND_API_URL 3. Configure custom domain (if applicable) 4. Test CORS from production frontend to backend 5. Verify cookies work across domains (SameSite=None; Secure)

Phase 8: Dashboard Implementation (Priority: LOW - Future)

Task 8.1: Dashboard Home Page

Frontend: archety-web/app/dashboard/page.tsx Backend: Existing APIs

Features: - Display user's trait profile (Big 5 radar chart) - Show selected persona - Display credit balance - Show recent conversations count - Quick links to settings, billing, AI management

Task 8.2: Settings Page

Frontend: archety-web/app/dashboard/settings/page.tsx Backend: GET/PUT /user/settings

Features: - Edit profile (name, pronouns, email) - Notification preferences (SMS, email, push) - Privacy settings (data sharing, analytics) - Theme selection (auto, light, dark) - Language selection

Task 8.3: Billing Page

Frontend: archety-web/app/dashboard/billing/page.tsx Backend: GET /payment/status/{user_id}, POST /payment/checkout/topup

Features: - Current credit balance - Usage history chart - Top-up button - Transaction history table - Subscription status (if applicable)

Task 8.4: AI Management Page

Frontend: archety-web/app/dashboard/ai/page.tsx Backend: TBD - New endpoint needed

Features: - View selected persona - Switch persona (future) - AI superpowers management - OAuth connections (Google Calendar, Gmail) - Workflow triggers configuration

🔧 Technical Debt & Improvements

Current Known Issues

  1. ⚠️ OnboardingSession missing user_id nullable constraint fix
  2. ⚠️ Photo storage needs S3 configuration (currently local only)
  3. ⚠️ Trait analysis needs actual GPT-4o Vision implementation
  4. ⚠️ Session cookie SameSite needs testing for cross-domain
  5. ⚠️ Rate limiting not implemented for API endpoints

Future Enhancements

  1. WebSocket support for real-time status updates (instead of polling)
  2. Image optimization for photo uploads (resize, compress)
  3. Caching layer (Redis) for trait profiles
  4. Admin dashboard for monitoring users
  5. Analytics integration (Amplitude, Mixpanel)
  6. A/B testing framework for persona matching
  7. Multi-language support
  8. Progressive web app (PWA) support

📊 Success Metrics

Technical KPIs

  • All API endpoints return correct response formats
  • Response times < 500ms for all endpoints (except photo upload)
  • Photo upload + analysis completes < 90 seconds
  • Zero CORS errors in production
  • Cookie-based auth works across domains
  • Stripe webhooks processed successfully (100% rate)
  • Database migrations run successfully

Product KPIs (Post-Launch)

  • Onboarding completion rate > 70%
  • Phone verification success rate > 95%
  • Payment success rate > 90%
  • Persona match satisfaction (survey) > 80%
  • D1 retention rate > 60%
  • Session depth (messages per session) > 10

🚀 Next Steps (Immediate Actions)

Week 1: Core API Implementation

  1. ✅ Merge all branches (DONE)
  2. ⏳ Implement missing onboarding endpoints (Task 1.1-1.4)
  3. ⏳ Test with frontend locally
  4. ⏳ Fix any API contract mismatches

Week 2: Authentication & Payment

  1. ⏳ Test Twilio phone verification end-to-end
  2. ⏳ Test Stripe trial checkout flow
  3. ⏳ Implement webhook handling
  4. ⏳ Test session management across frontend/backend

Week 3: Dashboard & Polish

  1. ⏳ Implement user profile/settings APIs
  2. ⏳ Test full onboarding flow
  3. ⏳ Deploy to staging (Railway + Vercel)
  4. ⏳ Conduct integration testing

Week 4: Production Launch

  1. ⏳ Configure production environment variables
  2. ⏳ Set up Stripe production webhooks
  3. ⏳ Deploy to production
  4. ⏳ Monitor errors and performance
  5. ⏳ Collect user feedback

📞 Team Coordination

Frontend Engineer Responsibilities

  • Ensure API calls match contract in BACKEND_REQUIREMENTS.md
  • Handle error responses gracefully (401, 404, 429, 500)
  • Implement loading states for all async operations
  • Test cookie-based authentication
  • Report any API contract violations

Backend Engineer Responsibilities (You)

  • Implement missing onboarding endpoints (Phase 1)
  • Implement user/dashboard endpoints (Phase 2)
  • Configure CORS for production frontend
  • Set up Stripe webhooks
  • Run database migrations
  • Monitor API performance and errors

Shared Responsibilities

  • End-to-end testing of onboarding flow
  • Cross-domain cookie testing
  • Production deployment coordination
  • Incident response and debugging

📚 Documentation

For Frontend Team

  • API Contract: /Users/justin-genies/code/archety-web/BACKEND_REQUIREMENTS.md
  • Quick Start: /Users/justin-genies/code/archety-web/QUICK_START_FOR_FRONTEND_ENGINEER.md
  • API Integration: /Users/justin-genies/code/archety-web/API_INTEGRATION.md
  • Traits Guide: /Users/justin-genies/code/archety-web/TRAITS_ONBOARDING_FRONTEND_GUIDE.md

For Backend Team

  • Project Instructions: /Users/justin-genies/Code/archety/CLAUDE.md
  • Traits Framework: /Users/justin-genies/Code/archety/docs/TRAITS_ONBOARDING_FRONTEND_GUIDE.md
  • Frontend Separation: /Users/justin-genies/Code/archety/FRONTEND_SEPARATION.md

Document Version: 1.0 Last Updated: November 13, 2025 Status: All branches merged ✅ | Implementation in progress ⏳