Added onboarding progress tracking & landing page

2025-10-02 13:20:15 +05:30
parent e57d2577f8
commit 510b79bbf8
135 changed files with 25917 additions and 5768 deletions
--- a/backend/api/onboarding_utils/API_REFERENCE.md
+++ b/backend/api/onboarding_utils/API_REFERENCE.md
@@ -0,0 +1,706 @@
+# ALwrity Onboarding System - API Reference
+
+## Overview
+
+This document provides a comprehensive API reference for the ALwrity Onboarding System. All endpoints require authentication and return JSON responses.
+
+## 🔐 Authentication
+
+All endpoints require a valid Clerk JWT token in the Authorization header:
+
+```
+Authorization: Bearer <clerk_jwt_token>
+```
+
+## 📋 Core Endpoints
+
+### Onboarding Status
+
+#### GET `/api/onboarding/status`
+Get the current onboarding status for the authenticated user.
+
+**Response:**
+```json
+{
+  "is_completed": false,
+  "current_step": 2,
+  "completion_percentage": 33.33,
+  "next_step": 3,
+  "started_at": "2024-01-15T10:30:00Z",
+  "completed_at": null,
+  "can_proceed_to_final": false
+}
+```
+
+#### GET `/api/onboarding/progress`
+Get the full onboarding progress data.
+
+**Response:**
+```json
+{
+  "steps": [
+    {
+      "step_number": 1,
+      "title": "AI LLM Providers Setup",
+      "description": "Configure your AI services",
+      "status": "completed",
+      "completed_at": "2024-01-15T10:35:00Z",
+      "data": {...},
+      "validation_errors": []
+    }
+  ],
+  "current_step": 2,
+  "started_at": "2024-01-15T10:30:00Z",
+  "last_updated": "2024-01-15T10:35:00Z",
+  "is_completed": false,
+  "completed_at": null
+}
+```
+
+### Step Management
+
+#### GET `/api/onboarding/step/{step_number}`
+Get data for a specific step.
+
+**Parameters:**
+- `step_number` (int): The step number (1-6)
+
+**Response:**
+```json
+{
+  "step_number": 1,
+  "title": "AI LLM Providers Setup",
+  "description": "Configure your AI services",
+  "status": "in_progress",
+  "completed_at": null,
+  "data": {...},
+  "validation_errors": []
+}
+```
+
+#### POST `/api/onboarding/step/{step_number}/complete`
+Mark a step as completed.
+
+**Parameters:**
+- `step_number` (int): The step number (1-6)
+
+**Request Body:**
+```json
+{
+  "data": {
+    "api_keys": {
+      "gemini": "your_gemini_key",
+      "exa": "your_exa_key",
+      "copilotkit": "your_copilotkit_key"
+    }
+  },
+  "validation_errors": []
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Step 1 completed successfully",
+  "step_number": 1,
+  "data": {...}
+}
+```
+
+#### POST `/api/onboarding/step/{step_number}/skip`
+Skip a step (for optional steps).
+
+**Parameters:**
+- `step_number` (int): The step number (1-6)
+
+**Response:**
+```json
+{
+  "message": "Step 2 skipped successfully",
+  "step_number": 2
+}
+```
+
+#### GET `/api/onboarding/step/{step_number}/validate`
+Validate if user can access a specific step.
+
+**Parameters:**
+- `step_number` (int): The step number (1-6)
+
+**Response:**
+```json
+{
+  "can_proceed": true,
+  "validation_errors": [],
+  "step_status": "available"
+}
+```
+
+### Onboarding Control
+
+#### POST `/api/onboarding/start`
+Start a new onboarding session.
+
+**Response:**
+```json
+{
+  "message": "Onboarding started successfully",
+  "current_step": 1,
+  "started_at": "2024-01-15T10:30:00Z"
+}
+```
+
+#### POST `/api/onboarding/reset`
+Reset the onboarding progress.
+
+**Response:**
+```json
+{
+  "message": "Onboarding progress reset successfully",
+  "current_step": 1,
+  "started_at": "2024-01-15T10:30:00Z"
+}
+```
+
+#### GET `/api/onboarding/resume`
+Get information for resuming onboarding.
+
+**Response:**
+```json
+{
+  "can_resume": true,
+  "resume_step": 2,
+  "current_step": 2,
+  "completion_percentage": 33.33,
+  "started_at": "2024-01-15T10:30:00Z",
+  "last_updated": "2024-01-15T10:35:00Z"
+}
+```
+
+#### POST `/api/onboarding/complete`
+Complete the onboarding process.
+
+**Response:**
+```json
+{
+  "message": "Onboarding completed successfully",
+  "completion_data": {...},
+  "persona_generated": true,
+  "environment_setup": true
+}
+```
+
+## 🔑 API Key Management
+
+### GET `/api/onboarding/api-keys`
+Get all configured API keys (masked for security).
+
+**Response:**
+```json
+{
+  "api_keys": {
+    "gemini": "********************abcd",
+    "exa": "********************efgh",
+    "copilotkit": "********************ijkl"
+  },
+  "total_providers": 3,
+  "configured_providers": ["gemini", "exa", "copilotkit"]
+}
+```
+
+### POST `/api/onboarding/api-keys`
+Save an API key for a provider.
+
+**Request Body:**
+```json
+{
+  "provider": "gemini",
+  "api_key": "your_api_key_here",
+  "description": "Gemini API key for content generation"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "API key for gemini saved successfully",
+  "provider": "gemini",
+  "status": "saved"
+}
+```
+
+### GET `/api/onboarding/api-keys/validate`
+Validate all configured API keys.
+
+**Response:**
+```json
+{
+  "validation_results": {
+    "gemini": {
+      "valid": true,
+      "status": "active",
+      "quota_remaining": 1000
+    },
+    "exa": {
+      "valid": true,
+      "status": "active",
+      "quota_remaining": 500
+    }
+  },
+  "all_valid": true,
+  "total_providers": 2
+}
+```
+
+## ⚙️ Configuration
+
+### GET `/api/onboarding/config`
+Get onboarding configuration and requirements.
+
+**Response:**
+```json
+{
+  "total_steps": 6,
+  "required_steps": [1, 2, 3, 4, 6],
+  "optional_steps": [5],
+  "step_requirements": {
+    "1": ["gemini", "exa", "copilotkit"],
+    "2": ["website_url"],
+    "3": ["research_preferences"],
+    "4": ["personalization_settings"],
+    "5": ["integrations"],
+    "6": ["persona_generation"]
+  }
+}
+```
+
+### GET `/api/onboarding/providers`
+Get setup information for all providers.
+
+**Response:**
+```json
+{
+  "providers": {
+    "gemini": {
+      "name": "Gemini AI",
+      "description": "Advanced content generation",
+      "setup_url": "https://ai.google.dev/",
+      "required": true,
+      "validation_endpoint": "https://generativelanguage.googleapis.com/v1beta/models"
+    },
+    "exa": {
+      "name": "Exa AI",
+      "description": "Intelligent web research",
+      "setup_url": "https://exa.ai/",
+      "required": true,
+      "validation_endpoint": "https://api.exa.ai/v1/search"
+    }
+  }
+}
+```
+
+### GET `/api/onboarding/providers/{provider}`
+Get setup information for a specific provider.
+
+**Parameters:**
+- `provider` (string): Provider name (gemini, exa, copilotkit)
+
+**Response:**
+```json
+{
+  "name": "Gemini AI",
+  "description": "Advanced content generation",
+  "setup_url": "https://ai.google.dev/",
+  "required": true,
+  "validation_endpoint": "https://generativelanguage.googleapis.com/v1beta/models",
+  "setup_instructions": [
+    "Visit Google AI Studio",
+    "Create a new API key",
+    "Copy the API key",
+    "Paste it in the form above"
+  ]
+}
+```
+
+### POST `/api/onboarding/providers/{provider}/validate`
+Validate a specific provider's API key.
+
+**Parameters:**
+- `provider` (string): Provider name (gemini, exa, copilotkit)
+
+**Request Body:**
+```json
+{
+  "api_key": "your_api_key_here"
+}
+```
+
+**Response:**
+```json
+{
+  "valid": true,
+  "status": "active",
+  "quota_remaining": 1000,
+  "provider": "gemini"
+}
+```
+
+## 📊 Summary & Analytics
+
+### GET `/api/onboarding/summary`
+Get comprehensive onboarding summary for the final step.
+
+**Response:**
+```json
+{
+  "user_info": {
+    "user_id": "user_123",
+    "onboarding_started": "2024-01-15T10:30:00Z",
+    "current_step": 6
+  },
+  "api_keys": {
+    "gemini": "configured",
+    "exa": "configured",
+    "copilotkit": "configured"
+  },
+  "website_analysis": {
+    "url": "https://example.com",
+    "status": "completed",
+    "style_analysis": "professional",
+    "content_count": 25
+  },
+  "research_preferences": {
+    "depth": "comprehensive",
+    "auto_research": true,
+    "fact_checking": true
+  },
+  "personalization": {
+    "brand_voice": "professional",
+    "target_audience": "B2B professionals",
+    "content_types": ["blog_posts", "social_media"]
+  }
+}
+```
+
+### GET `/api/onboarding/website-analysis`
+Get website analysis data.
+
+**Response:**
+```json
+{
+  "url": "https://example.com",
+  "analysis_status": "completed",
+  "content_analyzed": 25,
+  "style_characteristics": {
+    "tone": "professional",
+    "voice": "authoritative",
+    "complexity": "intermediate"
+  },
+  "target_audience": "B2B professionals",
+  "content_themes": ["technology", "business", "innovation"]
+}
+```
+
+### GET `/api/onboarding/research-preferences`
+Get research preferences data.
+
+**Response:**
+```json
+{
+  "research_depth": "comprehensive",
+  "auto_research_enabled": true,
+  "fact_checking_enabled": true,
+  "content_types": ["blog_posts", "articles", "social_media"],
+  "research_sources": ["web", "academic", "news"]
+}
+```
+
+## 👤 Business Information
+
+### POST `/api/onboarding/business-info`
+Save business information for users without websites.
+
+**Request Body:**
+```json
+{
+  "business_name": "Acme Corp",
+  "industry": "Technology",
+  "description": "AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness"]
+}
+```
+
+**Response:**
+```json
+{
+  "id": 1,
+  "business_name": "Acme Corp",
+  "industry": "Technology",
+  "description": "AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness"],
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### GET `/api/onboarding/business-info/{id}`
+Get business information by ID.
+
+**Parameters:**
+- `id` (int): Business information ID
+
+**Response:**
+```json
+{
+  "id": 1,
+  "business_name": "Acme Corp",
+  "industry": "Technology",
+  "description": "AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness"],
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### GET `/api/onboarding/business-info/user/{user_id}`
+Get business information by user ID.
+
+**Parameters:**
+- `user_id` (int): User ID
+
+**Response:**
+```json
+{
+  "id": 1,
+  "business_name": "Acme Corp",
+  "industry": "Technology",
+  "description": "AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness"],
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### PUT `/api/onboarding/business-info/{id}`
+Update business information.
+
+**Parameters:**
+- `id` (int): Business information ID
+
+**Request Body:**
+```json
+{
+  "business_name": "Acme Corp Updated",
+  "industry": "Technology",
+  "description": "Updated AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness", "thought_leadership"]
+}
+```
+
+**Response:**
+```json
+{
+  "id": 1,
+  "business_name": "Acme Corp Updated",
+  "industry": "Technology",
+  "description": "Updated AI-powered solutions",
+  "target_audience": "B2B professionals",
+  "brand_voice": "professional",
+  "content_goals": ["lead_generation", "brand_awareness", "thought_leadership"],
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T11:00:00Z"
+}
+```
+
+## 🎭 Persona Management
+
+### GET `/api/onboarding/persona/readiness/{user_id}`
+Check if user has sufficient data for persona generation.
+
+**Parameters:**
+- `user_id` (int): User ID
+
+**Response:**
+```json
+{
+  "ready": true,
+  "missing_data": [],
+  "completion_percentage": 100,
+  "recommendations": []
+}
+```
+
+### GET `/api/onboarding/persona/preview/{user_id}`
+Generate a preview of the writing persona without saving.
+
+**Parameters:**
+- `user_id` (int): User ID
+
+**Response:**
+```json
+{
+  "persona_preview": {
+    "name": "Professional Content Creator",
+    "voice": "authoritative",
+    "tone": "professional",
+    "style_characteristics": {
+      "formality": "high",
+      "complexity": "intermediate",
+      "engagement": "informative"
+    },
+    "content_preferences": {
+      "length": "medium",
+      "format": "structured",
+      "research_depth": "comprehensive"
+    }
+  },
+  "generation_time": "2.5s",
+  "confidence_score": 0.95
+}
+```
+
+### POST `/api/onboarding/persona/generate/{user_id}`
+Generate and save a writing persona from onboarding data.
+
+**Parameters:**
+- `user_id` (int): User ID
+
+**Response:**
+```json
+{
+  "persona_id": 1,
+  "name": "Professional Content Creator",
+  "voice": "authoritative",
+  "tone": "professional",
+  "style_characteristics": {...},
+  "content_preferences": {...},
+  "created_at": "2024-01-15T10:30:00Z",
+  "status": "active"
+}
+```
+
+### GET `/api/onboarding/persona/user/{user_id}`
+Get all writing personas for the user.
+
+**Parameters:**
+- `user_id` (int): User ID
+
+**Response:**
+```json
+{
+  "personas": [
+    {
+      "id": 1,
+      "name": "Professional Content Creator",
+      "voice": "authoritative",
+      "tone": "professional",
+      "status": "active",
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "total_count": 1,
+  "active_persona": 1
+}
+```
+
+## 🚨 Error Responses
+
+### 400 Bad Request
+```json
+{
+  "detail": "Invalid request data",
+  "error_code": "INVALID_REQUEST",
+  "validation_errors": [
+    "Field 'api_key' is required",
+    "Field 'provider' must be one of: gemini, exa, copilotkit"
+  ]
+}
+```
+
+### 401 Unauthorized
+```json
+{
+  "detail": "Authentication required",
+  "error_code": "UNAUTHORIZED"
+}
+```
+
+### 404 Not Found
+```json
+{
+  "detail": "Step 7 not found",
+  "error_code": "STEP_NOT_FOUND"
+}
+```
+
+### 500 Internal Server Error
+```json
+{
+  "detail": "Internal server error",
+  "error_code": "INTERNAL_ERROR"
+}
+```
+
+## 📝 Request/Response Models
+
+### StepCompletionRequest
+```json
+{
+  "data": {
+    "api_keys": {
+      "gemini": "string",
+      "exa": "string",
+      "copilotkit": "string"
+    }
+  },
+  "validation_errors": ["string"]
+}
+```
+
+### APIKeyRequest
+```json
+{
+  "provider": "string",
+  "api_key": "string",
+  "description": "string"
+}
+```
+
+### BusinessInfoRequest
+```json
+{
+  "business_name": "string",
+  "industry": "string",
+  "description": "string",
+  "target_audience": "string",
+  "brand_voice": "string",
+  "content_goals": ["string"]
+}
+```
+
+## 🔄 Rate Limiting
+
+- **Standard endpoints**: 100 requests per minute
+- **API key validation**: 10 requests per minute
+- **Persona generation**: 5 requests per minute
+
+## 📊 Response Times
+
+- **Status checks**: < 100ms
+- **Step completion**: < 500ms
+- **API key validation**: < 2s
+- **Persona generation**: < 10s
+- **Website analysis**: < 30s
+
+---
+
+*This API reference provides comprehensive documentation for all onboarding endpoints. For additional support, please refer to the main project documentation or contact the development team.*
--- a/backend/api/onboarding_utils/DEVELOPER_GUIDE.md
+++ b/backend/api/onboarding_utils/DEVELOPER_GUIDE.md
@@ -0,0 +1,330 @@
+# ALwrity Onboarding System - Developer Guide
+
+## Architecture Overview
+
+The ALwrity Onboarding System is built with a modular, service-based architecture that separates concerns and promotes maintainability. The system is designed to handle user isolation, progressive setup, and comprehensive onboarding workflows.
+
+## 🏗️ System Architecture
+
+### Core Components
+
+```
+backend/api/onboarding_utils/
+├── __init__.py                           # Package initialization
+├── onboarding_completion_service.py      # Final onboarding completion logic
+├── onboarding_summary_service.py        # Comprehensive summary generation
+├── onboarding_config_service.py         # Configuration and provider management
+├── business_info_service.py             # Business information CRUD operations
+├── api_key_management_service.py       # API key operations and validation
+├── step_management_service.py          # Step progression and validation
+├── onboarding_control_service.py        # Onboarding session management
+├── persona_management_service.py        # Persona generation and management
+├── README.md                            # End-user documentation
+└── DEVELOPER_GUIDE.md                   # This file
+```
+
+### Service Responsibilities
+
+#### 1. OnboardingCompletionService
+**Purpose**: Handles the complex logic for completing the onboarding process
+**Key Methods**:
+- `complete_onboarding()` - Main completion logic with validation
+- `_validate_required_steps()` - Ensures all required steps are completed
+- `_validate_api_keys()` - Validates API key configuration
+- `_generate_persona_from_onboarding()` - Generates writing persona
+
+#### 2. OnboardingSummaryService
+**Purpose**: Generates comprehensive onboarding summaries for the final step
+**Key Methods**:
+- `get_onboarding_summary()` - Main summary generation
+- `_get_api_keys()` - Retrieves configured API keys
+- `_get_website_analysis()` - Gets website analysis data
+- `_get_research_preferences()` - Retrieves research preferences
+- `_check_persona_readiness()` - Validates persona generation readiness
+
+#### 3. OnboardingConfigService
+**Purpose**: Manages onboarding configuration and provider setup information
+**Key Methods**:
+- `get_onboarding_config()` - Returns complete onboarding configuration
+- `get_provider_setup_info()` - Provider-specific setup information
+- `get_all_providers_info()` - All available providers
+- `validate_provider_key()` - API key validation
+- `get_enhanced_validation_status()` - Comprehensive validation status
+
+#### 4. BusinessInfoService
+**Purpose**: Handles business information management for users without websites
+**Key Methods**:
+- `save_business_info()` - Create new business information
+- `get_business_info()` - Retrieve by ID
+- `get_business_info_by_user()` - Retrieve by user ID
+- `update_business_info()` - Update existing information
+
+#### 5. APIKeyManagementService
+**Purpose**: Manages API key operations with caching and security
+**Key Methods**:
+- `get_api_keys()` - Retrieves masked API keys with caching
+- `save_api_key()` - Saves new API keys securely
+- `validate_api_keys()` - Validates all configured keys
+
+#### 6. StepManagementService
+**Purpose**: Controls step progression and validation
+**Key Methods**:
+- `get_onboarding_status()` - Current onboarding status
+- `get_onboarding_progress_full()` - Complete progress data
+- `get_step_data()` - Specific step information
+- `complete_step()` - Mark step as completed with environment setup
+- `skip_step()` - Skip optional steps
+- `validate_step_access()` - Validate step accessibility
+
+#### 7. OnboardingControlService
+**Purpose**: Manages onboarding session control
+**Key Methods**:
+- `start_onboarding()` - Initialize new onboarding session
+- `reset_onboarding()` - Reset onboarding progress
+- `get_resume_info()` - Resume information for incomplete sessions
+
+#### 8. PersonaManagementService
+**Purpose**: Handles persona generation and management
+**Key Methods**:
+- `check_persona_generation_readiness()` - Validate persona readiness
+- `generate_persona_preview()` - Generate preview without saving
+- `generate_writing_persona()` - Generate and save persona
+- `get_user_writing_personas()` - Retrieve user personas
+
+## 🔧 Integration Points
+
+### Progressive Setup Integration
+
+The onboarding system integrates with the progressive setup service:
+
+```python
+# In step_management_service.py
+from services.progressive_setup_service import ProgressiveSetupService
+
+# Initialize/upgrade user environment based on new step
+if step_number == 1:
+    setup_service.initialize_user_environment(user_id)
+else:
+    setup_service.upgrade_user_environment(user_id, step_number)
+```
+
+### User Isolation
+
+Each user gets their own:
+- **Workspace**: `lib/workspace/users/user_<id>/`
+- **Database Tables**: `user_<id>_*` tables
+- **Configuration**: User-specific settings
+- **Progress**: Individual onboarding progress
+
+### Authentication Integration
+
+All services require authentication:
+
+```python
+from middleware.auth_middleware import get_current_user
+
+async def endpoint_function(current_user: Dict[str, Any] = Depends(get_current_user)):
+    user_id = str(current_user.get('id'))
+    # Service logic here
+```
+
+## 📊 Data Flow
+
+### 1. Onboarding Initialization
+```
+User Login → Authentication → Check Onboarding Status → Redirect to Appropriate Step
+```
+
+### 2. Step Completion
+```
+User Completes Step → Validate Step → Save Progress → Setup User Environment → Return Success
+```
+
+### 3. Environment Setup
+```
+Step Completed → Progressive Setup Service → User Workspace Creation → Feature Activation
+```
+
+### 4. Final Completion
+```
+All Steps Complete → Validation → Persona Generation → Environment Finalization → Onboarding Complete
+```
+
+## 🛠️ Development Guidelines
+
+### Adding New Services
+
+1. **Create Service Class**:
+```python
+class NewService:
+    def __init__(self):
+        # Initialize dependencies
+    
+    async def main_method(self, params):
+        # Main functionality
+        pass
+```
+
+2. **Update __init__.py**:
+```python
+from .new_service import NewService
+
+__all__ = [
+    # ... existing services
+    'NewService'
+]
+```
+
+3. **Update Main Onboarding File**:
+```python
+async def new_endpoint():
+    try:
+        from onboarding_utils.new_service import NewService
+        
+        service = NewService()
+        return await service.main_method()
+    except Exception as e:
+        logger.error(f"Error: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+```
+
+### Error Handling Pattern
+
+All services follow a consistent error handling pattern:
+
+```python
+try:
+    # Service logic
+    return result
+except HTTPException:
+    raise  # Re-raise HTTP exceptions
+except Exception as e:
+    logger.error(f"Error in service: {str(e)}")
+    raise HTTPException(status_code=500, detail="Internal server error")
+```
+
+### Logging Guidelines
+
+Use structured logging with context:
+
+```python
+logger.info(f"[service_name] Action for user {user_id}")
+logger.success(f"✅ Operation completed for user {user_id}")
+logger.warning(f"⚠️ Non-critical issue: {issue}")
+logger.error(f"❌ Error in operation: {str(e)}")
+```
+
+## 🧪 Testing
+
+### Unit Testing
+
+Each service should have comprehensive unit tests:
+
+```python
+import pytest
+from onboarding_utils.step_management_service import StepManagementService
+
+class TestStepManagementService:
+    def setup_method(self):
+        self.service = StepManagementService()
+    
+    async def test_get_onboarding_status(self):
+        # Test implementation
+        pass
+```
+
+### Integration Testing
+
+Test service interactions:
+
+```python
+async def test_complete_onboarding_flow():
+    # Test complete onboarding workflow
+    pass
+```
+
+## 🔒 Security Considerations
+
+### API Key Security
+- Keys are masked in responses
+- Encryption before storage
+- Secure transmission only
+
+### User Data Isolation
+- User-specific workspaces
+- Isolated database tables
+- No cross-user data access
+
+### Input Validation
+- Validate all user inputs
+- Sanitize data before processing
+- Use Pydantic models for validation
+
+## 📈 Performance Optimization
+
+### Caching Strategy
+- API key responses cached for 30 seconds
+- User progress cached in memory
+- Database queries optimized
+
+### Database Optimization
+- User-specific table indexing
+- Efficient query patterns
+- Connection pooling
+
+### Resource Management
+- Proper database session handling
+- Memory-efficient data processing
+- Background task optimization
+
+## 🚀 Deployment Considerations
+
+### Environment Variables
+```bash
+# Required for onboarding
+CLERK_PUBLISHABLE_KEY=your_key
+CLERK_SECRET_KEY=your_secret
+GEMINI_API_KEY=your_gemini_key
+EXA_API_KEY=your_exa_key
+COPILOTKIT_API_KEY=your_copilotkit_key
+```
+
+### Database Setup
+- User-specific tables created on demand
+- Progressive table creation based on onboarding progress
+- Automatic cleanup on user deletion
+
+### Monitoring
+- Track onboarding completion rates
+- Monitor step abandonment points
+- Performance metrics for each service
+
+## 🔄 Maintenance
+
+### Regular Tasks
+- Review and update API key validation
+- Monitor service performance
+- Update documentation
+- Clean up abandoned onboarding sessions
+
+### Version Updates
+- Maintain backward compatibility
+- Gradual feature rollouts
+- User migration strategies
+
+## 📚 Additional Resources
+
+### Related Documentation
+- [User Environment Setup](../services/user_workspace_manager.py)
+- [Progressive Setup Service](../services/progressive_setup_service.py)
+- [Authentication Middleware](../middleware/auth_middleware.py)
+
+### External Dependencies
+- FastAPI for API framework
+- SQLAlchemy for database operations
+- Pydantic for data validation
+- Loguru for logging
+
+---
+
+*This developer guide provides comprehensive information for maintaining and extending the ALwrity Onboarding System. For questions or contributions, please refer to the main project documentation.*
--- a/backend/api/onboarding_utils/README.md
+++ b/backend/api/onboarding_utils/README.md
@@ -0,0 +1,269 @@
+# ALwrity Onboarding System
+
+## Overview
+
+The ALwrity Onboarding System is a comprehensive, user-friendly process designed to get new users up and running with AI-powered content creation capabilities. This system guides users through a structured 6-step process to configure their AI services, analyze their content style, and set up personalized content creation workflows.
+
+## 🎯 What is Onboarding?
+
+Onboarding is your first-time setup experience with ALwrity. It's designed to:
+- **Configure your AI services** (Gemini, Exa, CopilotKit)
+- **Analyze your existing content** to understand your writing style
+- **Set up research preferences** for intelligent content creation
+- **Personalize your experience** based on your brand and audience
+- **Connect integrations** for seamless content publishing
+- **Generate your writing persona** for consistent, on-brand content
+
+## 📋 The 6-Step Onboarding Process
+
+### Step 1: AI LLM Providers Setup
+**Purpose**: Connect your AI services to enable intelligent content creation
+
+**What you'll do**:
+- Configure **Gemini API** for advanced content generation
+- Set up **Exa AI** for intelligent web research
+- Connect **CopilotKit** for AI-powered assistance
+
+**Why it's important**: These services work together to provide comprehensive AI functionality for content creation, research, and assistance.
+
+**Requirements**: All three services are mandatory to proceed.
+
+### Step 2: Website Analysis
+**Purpose**: Analyze your existing content to understand your writing style and brand voice
+
+**What you'll do**:
+- Provide your website URL
+- Let ALwrity analyze your existing content
+- Review style analysis results
+
+**What ALwrity does**:
+- Crawls your website content
+- Analyzes writing patterns, tone, and voice
+- Identifies your target audience
+- Generates style guidelines for consistent content
+
+**Benefits**: Ensures all AI-generated content matches your existing brand voice and style.
+
+### Step 3: AI Research Configuration
+**Purpose**: Set up intelligent research capabilities for fact-based content creation
+
+**What you'll do**:
+- Choose research depth (Basic, Standard, Comprehensive, Expert)
+- Select content types you create
+- Configure auto-research preferences
+- Enable factual content verification
+
+**Benefits**: Ensures your content is well-researched, accurate, and up-to-date.
+
+### Step 4: Personalization Setup
+**Purpose**: Customize ALwrity to match your specific needs and preferences
+
+**What you'll do**:
+- Set posting preferences (frequency, timing)
+- Configure content types and formats
+- Define your target audience
+- Set brand voice parameters
+
+**Benefits**: Creates a personalized experience that matches your content strategy.
+
+### Step 5: Integrations (Optional)
+**Purpose**: Connect external platforms for seamless content publishing
+
+**Available integrations**:
+- **Wix** - Direct publishing to your Wix website
+- **LinkedIn** - Automated LinkedIn content posting
+- **WordPress** - WordPress site integration
+- **Other platforms** - Additional integrations as available
+
+**Benefits**: Streamlines your content workflow from creation to publication.
+
+### Step 6: Complete Setup
+**Purpose**: Finalize your onboarding and generate your writing persona
+
+**What happens**:
+- Validates all required configurations
+- Generates your personalized writing persona
+- Sets up your user workspace
+- Activates all configured features
+
+**Result**: You're ready to start creating AI-powered content that matches your brand!
+
+## 🔧 Technical Architecture
+
+### Service-Based Design
+
+The onboarding system is built with a modular, service-based architecture:
+
+```
+onboarding_utils/
+├── onboarding_completion_service.py      # Handles final onboarding completion
+├── onboarding_summary_service.py        # Generates comprehensive summaries
+├── onboarding_config_service.py         # Manages configuration and providers
+├── business_info_service.py             # Handles business information
+├── api_key_management_service.py       # Manages API key operations
+├── step_management_service.py          # Controls step progression
+├── onboarding_control_service.py        # Manages onboarding sessions
+└── persona_management_service.py        # Handles persona generation
+```
+
+### Key Features
+
+- **User Isolation**: Each user gets their own workspace and configuration
+- **Progressive Setup**: Features are enabled incrementally based on progress
+- **Persistent Storage**: All settings are saved and persist across sessions
+- **Validation**: Comprehensive validation at each step
+- **Error Handling**: Graceful error handling with helpful messages
+- **Security**: API keys are encrypted and stored securely
+
+## 🚀 Getting Started
+
+### For New Users
+
+1. **Sign up** with your preferred authentication method
+2. **Start onboarding** - You'll be automatically redirected
+3. **Follow the 6-step process** - Each step builds on the previous
+4. **Complete setup** - Generate your writing persona
+5. **Start creating** - Begin using ALwrity's AI-powered features
+
+### For Returning Users
+
+- **Resume onboarding** - Continue where you left off
+- **Skip optional steps** - Focus on what you need
+- **Update configurations** - Modify settings anytime
+- **Add integrations** - Connect new platforms as needed
+
+## 📊 Progress Tracking
+
+The system tracks your progress through:
+
+- **Step completion status** - See which steps are done
+- **Progress percentage** - Visual progress indicator
+- **Validation status** - Know what needs attention
+- **Resume information** - Pick up where you left off
+
+## 🔒 Security & Privacy
+
+- **API Key Encryption**: All API keys are encrypted before storage
+- **User Isolation**: Your data is completely separate from other users
+- **Secure Storage**: Data is stored securely on your device
+- **No Data Sharing**: Your content and preferences are never shared
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**"Cannot proceed to next step"**
+- Complete all required fields in the current step
+- Ensure API keys are valid and working
+- Check for any validation errors
+
+**"API key validation failed"**
+- Verify your API key is correct
+- Check if the service is available
+- Ensure you have sufficient credits/quota
+
+**"Website analysis failed"**
+- Ensure your website is publicly accessible
+- Check if the URL is correct
+- Try again after a few minutes
+
+### Getting Help
+
+- **In-app help** - Use the "Get Help" button in each step
+- **Documentation** - Check the detailed setup guides
+- **Support** - Contact support for technical issues
+
+## 🎨 Customization Options
+
+### Writing Style
+- **Tone**: Professional, Casual, Friendly, Authoritative
+- **Voice**: First-person, Third-person, Brand voice
+- **Complexity**: Simple, Intermediate, Advanced, Expert
+
+### Content Preferences
+- **Length**: Short, Medium, Long, Variable
+- **Format**: Blog posts, Social media, Emails, Articles
+- **Frequency**: Daily, Weekly, Monthly, Custom
+
+### Research Settings
+- **Depth**: Basic, Standard, Comprehensive, Expert
+- **Sources**: Web, Academic, News, Social media
+- **Verification**: Auto-fact-check, Manual review, AI-assisted
+
+## 📈 Benefits of Completing Onboarding
+
+### Immediate Benefits
+- **AI-Powered Content Creation** - Generate high-quality content instantly
+- **Style Consistency** - All content matches your brand voice
+- **Research Integration** - Fact-based, well-researched content
+- **Time Savings** - Reduce content creation time by 80%
+
+### Long-term Benefits
+- **Brand Consistency** - Maintain consistent voice across all content
+- **Scalability** - Create more content without sacrificing quality
+- **Efficiency** - Streamlined workflow from idea to publication
+- **Growth** - Focus on strategy while AI handles execution
+
+## 🔄 Updating Your Configuration
+
+You can update your onboarding settings anytime:
+
+- **API Keys** - Update or add new service keys
+- **Website Analysis** - Re-analyze your content for style updates
+- **Research Preferences** - Adjust research depth and sources
+- **Personalization** - Update your brand voice and preferences
+- **Integrations** - Add or remove platform connections
+
+## 📞 Support & Resources
+
+### Documentation
+- **Setup Guides** - Step-by-step configuration instructions
+- **API Documentation** - Technical reference for developers
+- **Best Practices** - Tips for optimal onboarding experience
+
+### Community
+- **User Forum** - Connect with other ALwrity users
+- **Feature Requests** - Suggest improvements
+- **Success Stories** - Learn from other users' experiences
+
+### Support Channels
+- **In-app Support** - Get help directly within ALwrity
+- **Email Support** - support@alwrity.com
+- **Live Chat** - Available during business hours
+- **Video Tutorials** - Visual guides for complex setups
+
+## 🎯 Success Metrics
+
+Track your onboarding success with these metrics:
+
+- **Completion Rate** - Percentage of users who complete onboarding
+- **Time to Value** - How quickly users see benefits
+- **Feature Adoption** - Which features users engage with
+- **Satisfaction Score** - User feedback on the experience
+
+## 🔮 Future Enhancements
+
+We're constantly improving the onboarding experience:
+
+- **Smart Recommendations** - AI-suggested configurations
+- **Template Library** - Pre-built setups for different industries
+- **Advanced Analytics** - Detailed insights into your content performance
+- **Mobile Experience** - Optimized mobile onboarding flow
+- **Voice Setup** - Voice-based configuration for accessibility
+
+---
+
+## Quick Start Checklist
+
+- [ ] **Step 1**: Configure Gemini, Exa, and CopilotKit API keys
+- [ ] **Step 2**: Provide website URL for style analysis
+- [ ] **Step 3**: Set research preferences and content types
+- [ ] **Step 4**: Configure personalization settings
+- [ ] **Step 5**: Connect desired integrations (optional)
+- [ ] **Step 6**: Complete setup and generate writing persona
+
+**🎉 You're ready to create amazing AI-powered content!**
+
+---
+
+*This onboarding system is designed to get you up and running quickly while ensuring your content maintains your unique brand voice and style. Take your time with each step - the more accurate your configuration, the better your AI-generated content will be.*
--- a/backend/api/onboarding_utils/init.py
+++ b/backend/api/onboarding_utils/init.py
@@ -0,0 +1,23 @@
+"""
+Onboarding utilities package.
+"""
+
+from .onboarding_completion_service import OnboardingCompletionService
+from .onboarding_summary_service import OnboardingSummaryService
+from .onboarding_config_service import OnboardingConfigService
+from .business_info_service import BusinessInfoService
+from .api_key_management_service import APIKeyManagementService
+from .step_management_service import StepManagementService
+from .onboarding_control_service import OnboardingControlService
+from .persona_management_service import PersonaManagementService
+
+__all__ = [
+    'OnboardingCompletionService',
+    'OnboardingSummaryService',
+    'OnboardingConfigService',
+    'BusinessInfoService',
+    'APIKeyManagementService',
+    'StepManagementService',
+    'OnboardingControlService',
+    'PersonaManagementService'
+]
--- a/backend/api/onboarding_utils/api_key_management_service.py
+++ b/backend/api/onboarding_utils/api_key_management_service.py
@@ -0,0 +1,109 @@
+"""
+API Key Management Service
+Handles API key operations for onboarding.
+"""
+
+import time
+from typing import Dict, Any
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import APIKeyManager
+from services.validation import check_all_api_keys
+
+class APIKeyManagementService:
+    """Service for handling API key management operations."""
+    
+    def __init__(self):
+        self.api_key_manager = APIKeyManager()
+        # Simple cache for API keys
+        self._api_keys_cache = None
+        self._cache_timestamp = 0
+        self.CACHE_DURATION = 30  # Cache for 30 seconds
+    
+    async def get_api_keys(self) -> Dict[str, Any]:
+        """Get all configured API keys (masked)."""
+        current_time = time.time()
+        
+        # Return cached result if still valid
+        if self._api_keys_cache and (current_time - self._cache_timestamp) < self.CACHE_DURATION:
+            logger.debug("Returning cached API keys")
+            return self._api_keys_cache
+        
+        try:
+            self.api_key_manager.load_api_keys()  # Load keys from environment
+            api_keys = self.api_key_manager.api_keys  # Get the loaded keys
+            
+            # Mask the API keys for security
+            masked_keys = {}
+            for provider, key in api_keys.items():
+                if key:
+                    masked_keys[provider] = "*" * (len(key) - 4) + key[-4:] if len(key) > 4 else "*" * len(key)
+                else:
+                    masked_keys[provider] = None
+            
+            result = {
+                "api_keys": masked_keys,
+                "total_providers": len(api_keys),
+                "configured_providers": [k for k, v in api_keys.items() if v]
+            }
+            
+            # Cache the result
+            self._api_keys_cache = result
+            self._cache_timestamp = current_time
+            
+            return result
+        except Exception as e:
+            logger.error(f"Error getting API keys: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_api_keys_for_onboarding(self) -> Dict[str, Any]:
+        """Get all configured API keys for onboarding (unmasked)."""
+        try:
+            self.api_key_manager.load_api_keys()  # Load keys from environment
+            api_keys = self.api_key_manager.api_keys  # Get the loaded keys
+            
+            # Return actual API keys for onboarding pre-filling
+            result = {
+                "api_keys": api_keys,
+                "total_providers": len(api_keys),
+                "configured_providers": [k for k, v in api_keys.items() if v]
+            }
+            
+            return result
+        except Exception as e:
+            logger.error(f"Error getting API keys for onboarding: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def save_api_key(self, provider: str, api_key: str, description: str = None) -> Dict[str, Any]:
+        """Save an API key for a provider."""
+        try:
+            success = self.api_key_manager.save_api_key(provider, api_key)
+            
+            if success:
+                return {
+                    "message": f"API key for {provider} saved successfully",
+                    "provider": provider,
+                    "status": "saved"
+                }
+            else:
+                raise HTTPException(status_code=400, detail=f"Failed to save API key for {provider}")
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error saving API key: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def validate_api_keys(self) -> Dict[str, Any]:
+        """Validate all configured API keys."""
+        try:
+            validation_results = check_all_api_keys(self.api_key_manager)
+            
+            return {
+                "validation_results": validation_results.get('results', {}),
+                "all_valid": validation_results.get('all_valid', False),
+                "total_providers": len(validation_results.get('results', {}))
+            }
+        except Exception as e:
+            logger.error(f"Error validating API keys: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
--- a/backend/api/onboarding_utils/business_info_service.py
+++ b/backend/api/onboarding_utils/business_info_service.py
@@ -0,0 +1,86 @@
+"""
+Business Information Service
+Handles business information management for users without websites.
+"""
+
+from typing import Dict, Any, Optional
+from fastapi import HTTPException
+from loguru import logger
+
+class BusinessInfoService:
+    """Service for handling business information operations."""
+    
+    def __init__(self):
+        pass
+    
+    async def save_business_info(self, business_info: 'BusinessInfoRequest') -> Dict[str, Any]:
+        """Save business information for users without websites."""
+        try:
+            from models.business_info_request import BusinessInfoRequest
+            from services.business_info_service import business_info_service
+            
+            logger.info(f"🔄 Saving business info for user_id: {business_info.user_id}")
+            result = business_info_service.save_business_info(business_info)
+            logger.success(f"✅ Business info saved successfully for user_id: {business_info.user_id}")
+            return result
+        except Exception as e:
+            logger.error(f"❌ Error saving business info: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to save business info: {str(e)}")
+    
+    async def get_business_info(self, business_info_id: int) -> Dict[str, Any]:
+        """Get business information by ID."""
+        try:
+            from services.business_info_service import business_info_service
+            
+            logger.info(f"🔄 Getting business info for ID: {business_info_id}")
+            result = business_info_service.get_business_info(business_info_id)
+            if result:
+                logger.success(f"✅ Business info retrieved for ID: {business_info_id}")
+                return result
+            else:
+                logger.warning(f"⚠️ No business info found for ID: {business_info_id}")
+                raise HTTPException(status_code=404, detail="Business info not found")
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"❌ Error getting business info: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to get business info: {str(e)}")
+    
+    async def get_business_info_by_user(self, user_id: int) -> Dict[str, Any]:
+        """Get business information by user ID."""
+        try:
+            from services.business_info_service import business_info_service
+            
+            logger.info(f"🔄 Getting business info for user ID: {user_id}")
+            result = business_info_service.get_business_info_by_user(user_id)
+            if result:
+                logger.success(f"✅ Business info retrieved for user ID: {user_id}")
+                return result
+            else:
+                logger.warning(f"⚠️ No business info found for user ID: {user_id}")
+                raise HTTPException(status_code=404, detail="Business info not found")
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"❌ Error getting business info: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to get business info: {str(e)}")
+    
+    async def update_business_info(self, business_info_id: int, business_info: 'BusinessInfoRequest') -> Dict[str, Any]:
+        """Update business information."""
+        try:
+            from models.business_info_request import BusinessInfoRequest
+            from services.business_info_service import business_info_service
+            
+            logger.info(f"🔄 Updating business info for ID: {business_info_id}")
+            result = business_info_service.update_business_info(business_info_id, business_info)
+            if result:
+                logger.success(f"✅ Business info updated for ID: {business_info_id}")
+                return result
+            else:
+                logger.warning(f"⚠️ No business info found to update for ID: {business_info_id}")
+                raise HTTPException(status_code=404, detail="Business info not found")
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"❌ Error updating business info: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to update business info: {str(e)}")
--- a/backend/api/onboarding_utils/onboarding_completion_service.py
+++ b/backend/api/onboarding_utils/onboarding_completion_service.py
@@ -0,0 +1,94 @@
+"""
+Onboarding Completion Service
+Handles the complex logic for completing the onboarding process.
+"""
+
+from typing import Dict, Any, List
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import get_onboarding_progress_for_user, get_api_key_manager, StepStatus
+from services.persona_analysis_service import PersonaAnalysisService
+
+class OnboardingCompletionService:
+    """Service for handling onboarding completion logic."""
+    
+    def __init__(self):
+        self.required_steps = [1, 2, 3, 6]  # Steps 1, 2, 3, and 6 are required
+    
+    async def complete_onboarding(self, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Complete the onboarding process with full validation."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            
+            # Validate required steps are completed
+            missing_steps = self._validate_required_steps(progress)
+            if missing_steps:
+                missing_steps_str = ", ".join(missing_steps)
+                raise HTTPException(
+                    status_code=400, 
+                    detail=f"Cannot complete onboarding. The following steps must be completed first: {missing_steps_str}"
+                )
+            
+            # Validate API keys are configured
+            self._validate_api_keys()
+            
+            # Generate writing persona from onboarding data
+            persona_generated = await self._generate_persona_from_onboarding(user_id)
+            
+            # Complete the onboarding process
+            progress.complete_onboarding()
+            
+            return {
+                "message": "Onboarding completed successfully",
+                "completed_at": progress.completed_at,
+                "completion_percentage": 100.0,
+                "persona_generated": persona_generated
+            }
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error completing onboarding: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    def _validate_required_steps(self, progress) -> List[str]:
+        """Validate that all required steps are completed."""
+        missing_steps = []
+        
+        for step_num in self.required_steps:
+            step = progress.get_step_data(step_num)
+            if step and step.status not in [StepStatus.COMPLETED, StepStatus.SKIPPED]:
+                missing_steps.append(step.title)
+        
+        return missing_steps
+    
+    def _validate_api_keys(self):
+        """Validate that API keys are configured."""
+        api_manager = get_api_key_manager()
+        api_keys = api_manager.get_all_keys()
+        if not api_keys:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot complete onboarding. At least one AI provider API key must be configured."
+            )
+    
+    async def _generate_persona_from_onboarding(self, user_id: str) -> bool:
+        """Generate writing persona from onboarding data."""
+        try:
+            persona_service = PersonaAnalysisService()
+            
+            # Use user_id = 1 for now (assuming single user system)
+            persona_user_id = 1
+            persona_result = persona_service.generate_persona_from_onboarding(persona_user_id)
+            
+            if "error" not in persona_result:
+                logger.info(f"✅ Writing persona generated during onboarding completion: {persona_result.get('persona_id')}")
+                return True
+            else:
+                logger.warning(f"⚠️ Persona generation failed during onboarding: {persona_result['error']}")
+                return False
+        except Exception as e:
+            logger.warning(f"⚠️ Non-critical error generating persona during onboarding: {str(e)}")
+            return False
--- a/backend/api/onboarding_utils/onboarding_config_service.py
+++ b/backend/api/onboarding_utils/onboarding_config_service.py
@@ -0,0 +1,127 @@
+"""
+Onboarding Configuration Service
+Handles onboarding configuration and provider setup information.
+"""
+
+from typing import Dict, Any
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import get_api_key_manager
+from services.validation import check_all_api_keys
+
+class OnboardingConfigService:
+    """Service for handling onboarding configuration and provider setup."""
+    
+    def __init__(self):
+        self.api_key_manager = get_api_key_manager()
+    
+    def get_onboarding_config(self) -> Dict[str, Any]:
+        """Get onboarding configuration and requirements."""
+        return {
+            "total_steps": 6,
+            "steps": [
+                {
+                    "number": 1,
+                    "title": "AI LLM Providers",
+                    "description": "Configure AI language model providers",
+                    "required": True,
+                    "providers": ["openai", "gemini", "anthropic"]
+                },
+                {
+                    "number": 2,
+                    "title": "Website Analysis",
+                    "description": "Set up website analysis and crawling",
+                    "required": True
+                },
+                {
+                    "number": 3,
+                    "title": "AI Research",
+                    "description": "Configure AI research capabilities",
+                    "required": True
+                },
+                {
+                    "number": 4,
+                    "title": "Personalization",
+                    "description": "Set up personalization features",
+                    "required": False
+                },
+                {
+                    "number": 5,
+                    "title": "Integrations",
+                    "description": "Configure ALwrity integrations",
+                    "required": False
+                },
+                {
+                    "number": 6,
+                    "title": "Complete Setup",
+                    "description": "Finalize and complete onboarding",
+                    "required": True
+                }
+            ],
+            "requirements": {
+                "min_api_keys": 1,
+                "required_providers": ["openai"],
+                "optional_providers": ["gemini", "anthropic"]
+            }
+        }
+    
+    async def get_provider_setup_info(self, provider: str) -> Dict[str, Any]:
+        """Get setup information for a specific provider."""
+        try:
+            providers_info = self.get_all_providers_info()
+            if provider in providers_info:
+                return providers_info[provider]
+            else:
+                raise HTTPException(status_code=404, detail=f"Provider {provider} not found")
+        except Exception as e:
+            logger.error(f"Error getting provider setup info: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    def get_all_providers_info(self) -> Dict[str, Any]:
+        """Get setup information for all providers."""
+        return {
+            "openai": {
+                "name": "OpenAI",
+                "description": "GPT-4 and GPT-3.5 models for content generation",
+                "setup_url": "https://platform.openai.com/api-keys",
+                "required_fields": ["api_key"],
+                "optional_fields": ["organization_id"]
+            },
+            "gemini": {
+                "name": "Google Gemini",
+                "description": "Google's advanced AI models for content creation",
+                "setup_url": "https://makersuite.google.com/app/apikey",
+                "required_fields": ["api_key"],
+                "optional_fields": []
+            },
+            "anthropic": {
+                "name": "Anthropic",
+                "description": "Claude models for sophisticated content generation",
+                "setup_url": "https://console.anthropic.com/",
+                "required_fields": ["api_key"],
+                "optional_fields": []
+            }
+        }
+    
+    async def validate_provider_key(self, provider: str, api_key: str) -> Dict[str, Any]:
+        """Validate a specific provider's API key."""
+        try:
+            # This would need to be implemented based on the actual validation logic
+            # For now, return a basic validation result
+            return {
+                "provider": provider,
+                "valid": True,
+                "message": f"API key for {provider} is valid"
+            }
+        except Exception as e:
+            logger.error(f"Error validating provider key: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_enhanced_validation_status(self) -> Dict[str, Any]:
+        """Get enhanced validation status for all configured services."""
+        try:
+            return await check_all_api_keys(self.api_key_manager)
+        except Exception as e:
+            logger.error(f"Error getting enhanced validation status: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
--- a/backend/api/onboarding_utils/onboarding_control_service.py
+++ b/backend/api/onboarding_utils/onboarding_control_service.py
@@ -0,0 +1,73 @@
+"""
+Onboarding Control Service
+Handles onboarding session control and management.
+"""
+
+from typing import Dict, Any
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import get_onboarding_progress, get_onboarding_progress_for_user
+
+class OnboardingControlService:
+    """Service for handling onboarding control operations."""
+    
+    def __init__(self):
+        pass
+    
+    async def start_onboarding(self, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Start a new onboarding session."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            progress.reset_progress()
+            
+            return {
+                "message": "Onboarding started successfully",
+                "current_step": progress.current_step,
+                "started_at": progress.started_at
+            }
+        except Exception as e:
+            logger.error(f"Error starting onboarding: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def reset_onboarding(self) -> Dict[str, Any]:
+        """Reset the onboarding progress."""
+        try:
+            progress = get_onboarding_progress()
+            progress.reset_progress()
+            
+            return {
+                "message": "Onboarding progress reset successfully",
+                "current_step": progress.current_step,
+                "started_at": progress.started_at
+            }
+        except Exception as e:
+            logger.error(f"Error resetting onboarding: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_resume_info(self) -> Dict[str, Any]:
+        """Get information for resuming onboarding."""
+        try:
+            progress = get_onboarding_progress()
+            
+            if progress.is_completed:
+                return {
+                    "can_resume": False,
+                    "message": "Onboarding is already completed",
+                    "completion_percentage": 100.0
+                }
+            
+            resume_step = progress.get_resume_step()
+            
+            return {
+                "can_resume": True,
+                "resume_step": resume_step,
+                "current_step": progress.current_step,
+                "completion_percentage": progress.get_completion_percentage(),
+                "started_at": progress.started_at,
+                "last_updated": progress.last_updated
+            }
+        except Exception as e:
+            logger.error(f"Error getting resume info: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
--- a/backend/api/onboarding_utils/onboarding_summary_service.py
+++ b/backend/api/onboarding_utils/onboarding_summary_service.py
@@ -0,0 +1,166 @@
+"""
+Onboarding Summary Service
+Handles the complex logic for generating comprehensive onboarding summaries.
+"""
+
+from typing import Dict, Any, Optional
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import get_api_key_manager
+from services.database import get_db
+from services.website_analysis_service import WebsiteAnalysisService
+from services.research_preferences_service import ResearchPreferencesService
+from services.persona_analysis_service import PersonaAnalysisService
+
+class OnboardingSummaryService:
+    """Service for handling onboarding summary generation with user isolation."""
+    
+    def __init__(self, user_id: str):
+        """
+        Initialize service with user-specific context.
+        
+        Args:
+            user_id: Clerk user ID from authenticated request
+        """
+        # Convert Clerk user ID to integer for database compatibility
+        try:
+            self.user_id_int = int(user_id.replace('user_', '').replace('-', '')[:8], 16) % 2147483647
+        except:
+            self.user_id_int = hash(user_id) % 2147483647
+        
+        self.user_id = user_id  # Store original Clerk ID for logging
+        self.session_id = self.user_id_int  # Use user ID as session ID for backwards compatibility
+    
+    async def get_onboarding_summary(self) -> Dict[str, Any]:
+        """Get comprehensive onboarding summary for FinalStep."""
+        try:
+            # Get API keys
+            api_keys = self._get_api_keys()
+            
+            # Get website analysis data
+            website_analysis = self._get_website_analysis()
+            
+            # Get research preferences
+            research_preferences = self._get_research_preferences()
+            
+            # Get personalization settings
+            personalization_settings = self._get_personalization_settings(research_preferences)
+            
+            # Check persona generation readiness
+            persona_readiness = self._check_persona_readiness(website_analysis)
+            
+            # Determine capabilities
+            capabilities = self._determine_capabilities(api_keys, website_analysis, research_preferences, personalization_settings, persona_readiness)
+            
+            return {
+                "api_keys": api_keys,
+                "website_url": website_analysis.get('website_url') if website_analysis else None,
+                "style_analysis": website_analysis.get('style_analysis') if website_analysis else None,
+                "research_preferences": research_preferences,
+                "personalization_settings": personalization_settings,
+                "persona_readiness": persona_readiness,
+                "integrations": {},  # TODO: Implement integrations data
+                "capabilities": capabilities
+            }
+            
+        except Exception as e:
+            logger.error(f"Error getting onboarding summary: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    def _get_api_keys(self) -> Dict[str, Any]:
+        """Get configured API keys."""
+        api_manager = get_api_key_manager()
+        return api_manager.get_all_keys()
+    
+    def _get_website_analysis(self) -> Optional[Dict[str, Any]]:
+        """Get website analysis data."""
+        try:
+            db = next(get_db())
+            website_service = WebsiteAnalysisService(db)
+            return website_service.get_analysis_by_session(self.session_id)
+        except Exception as e:
+            logger.warning(f"Could not get website analysis: {str(e)}")
+            return None
+    
+    def _get_research_preferences(self) -> Optional[Dict[str, Any]]:
+        """Get research preferences data."""
+        try:
+            db = next(get_db())
+            research_service = ResearchPreferencesService(db)
+            return research_service.get_research_preferences(self.session_id)
+        except Exception as e:
+            logger.warning(f"Could not get research preferences: {str(e)}")
+            return None
+    
+    def _get_personalization_settings(self, research_preferences: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        """Get personalization settings from research preferences."""
+        if not research_preferences:
+            return None
+        
+        return {
+            'writing_style': research_preferences.get('writing_style', {}).get('tone', 'Professional'),
+            'tone': research_preferences.get('writing_style', {}).get('voice', 'Formal'),
+            'brand_voice': research_preferences.get('writing_style', {}).get('complexity', 'Trustworthy and Expert')
+        }
+    
+    def _check_persona_readiness(self, website_analysis: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        """Check if persona can be generated."""
+        try:
+            persona_service = PersonaAnalysisService()
+            
+            # Check if persona can be generated
+            onboarding_data = persona_service._collect_onboarding_data(self.user_id)
+            if onboarding_data:
+                data_sufficiency = persona_service._calculate_data_sufficiency(onboarding_data)
+                return {
+                    "ready": data_sufficiency >= 50.0,
+                    "data_sufficiency": data_sufficiency,
+                    "can_generate": website_analysis is not None
+                }
+            return {"ready": False, "data_sufficiency": 0.0, "can_generate": False}
+        except Exception as e:
+            logger.warning(f"Could not check persona readiness: {str(e)}")
+            return {"ready": False, "error": str(e)}
+    
+    def _determine_capabilities(self, api_keys: Dict[str, Any], website_analysis: Optional[Dict[str, Any]], 
+                              research_preferences: Optional[Dict[str, Any]], 
+                              personalization_settings: Optional[Dict[str, Any]], 
+                              persona_readiness: Optional[Dict[str, Any]]) -> Dict[str, bool]:
+        """Determine user capabilities based on onboarding data."""
+        return {
+            "ai_content": len(api_keys) > 0,
+            "style_analysis": website_analysis is not None,
+            "research_tools": research_preferences is not None,
+            "personalization": personalization_settings is not None,
+            "persona_generation": persona_readiness.get("ready", False) if persona_readiness else False,
+            "integrations": False  # TODO: Implement
+        }
+    
+    async def get_website_analysis_data(self) -> Optional[Dict[str, Any]]:
+        """Get website analysis data for FinalStep."""
+        try:
+            analysis = self._get_website_analysis()
+            
+            if analysis:
+                return {
+                    "website_url": analysis.get('website_url'),
+                    "style_analysis": analysis.get('style_analysis'),
+                    "style_patterns": analysis.get('style_patterns'),
+                    "style_guidelines": analysis.get('style_guidelines'),
+                    "status": analysis.get('status'),
+                    "completed_at": analysis.get('created_at')
+                }
+            else:
+                return None
+        except Exception as e:
+            logger.error(f"Error getting website analysis data: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_research_preferences_data(self) -> Optional[Dict[str, Any]]:
+        """Get research preferences data for FinalStep."""
+        try:
+            return self._get_research_preferences()
+        except Exception as e:
+            logger.error(f"Error getting research preferences data: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
--- a/backend/api/onboarding_utils/persona_management_service.py
+++ b/backend/api/onboarding_utils/persona_management_service.py
@@ -0,0 +1,51 @@
+"""
+Persona Management Service
+Handles persona generation and management for onboarding.
+"""
+
+from typing import Dict, Any
+from fastapi import HTTPException
+from loguru import logger
+
+class PersonaManagementService:
+    """Service for handling persona management operations."""
+    
+    def __init__(self):
+        pass
+    
+    async def check_persona_generation_readiness(self, user_id: int = 1) -> Dict[str, Any]:
+        """Check if user has sufficient data for persona generation."""
+        try:
+            from api.persona import validate_persona_generation_readiness
+            return await validate_persona_generation_readiness(user_id)
+        except Exception as e:
+            logger.error(f"Error checking persona readiness: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def generate_persona_preview(self, user_id: int = 1) -> Dict[str, Any]:
+        """Generate a preview of the writing persona without saving."""
+        try:
+            from api.persona import generate_persona_preview
+            return await generate_persona_preview(user_id)
+        except Exception as e:
+            logger.error(f"Error generating persona preview: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def generate_writing_persona(self, user_id: int = 1) -> Dict[str, Any]:
+        """Generate and save a writing persona from onboarding data."""
+        try:
+            from api.persona import generate_persona, PersonaGenerationRequest
+            request = PersonaGenerationRequest(force_regenerate=False)
+            return await generate_persona(user_id, request)
+        except Exception as e:
+            logger.error(f"Error generating writing persona: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_user_writing_personas(self, user_id: int = 1) -> Dict[str, Any]:
+        """Get all writing personas for the user."""
+        try:
+            from api.persona import get_user_personas
+            return await get_user_personas(user_id)
+        except Exception as e:
+            logger.error(f"Error getting user personas: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
--- a/backend/api/onboarding_utils/step3_research_service.py
+++ b/backend/api/onboarding_utils/step3_research_service.py
@@ -0,0 +1,518 @@
+"""
+Step 3 Research Service for Onboarding
+
+This service handles the research phase of onboarding (Step 3), including
+competitor discovery using Exa API and research data management.
+
+Key Features:
+- Competitor discovery using Exa API
+- Research progress tracking
+- Data storage and retrieval
+- Integration with onboarding workflow
+
+Author: ALwrity Team
+Version: 1.0
+Last Updated: January 2025
+"""
+
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+from loguru import logger
+from services.research.exa_service import ExaService
+from services.database import get_db_session
+from models.onboarding import OnboardingSession
+from sqlalchemy.orm import Session
+
+class Step3ResearchService:
+    """
+    Service for managing Step 3 research phase of onboarding.
+    
+    This service handles competitor discovery, research data storage,
+    and integration with the onboarding workflow.
+    """
+    
+    def __init__(self):
+        """Initialize the Step 3 Research Service."""
+        self.exa_service = ExaService()
+        self.service_name = "step3_research"
+        logger.info(f"Initialized {self.service_name}")
+    
+    async def discover_competitors_for_onboarding(
+        self,
+        user_url: str,
+        session_id: str,
+        industry_context: Optional[str] = None,
+        num_results: int = 25,
+        website_analysis_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Discover competitors for onboarding Step 3.
+        
+        Args:
+            user_url: The user's website URL
+            session_id: Onboarding session ID
+            industry_context: Industry context for better discovery
+            num_results: Number of competitors to discover
+            
+        Returns:
+            Dictionary containing competitor discovery results
+        """
+        try:
+            logger.info(f"Starting research analysis for session {session_id}, URL: {user_url}")
+            
+            # Step 1: Discover social media accounts
+            logger.info("Step 1: Discovering social media accounts...")
+            social_media_results = await self.exa_service.discover_social_media_accounts(user_url)
+            
+            if not social_media_results["success"]:
+                logger.warning(f"Social media discovery failed: {social_media_results.get('error')}")
+                # Continue with competitor discovery even if social media fails
+                social_media_results = {"success": False, "social_media_accounts": {}, "citations": []}
+            
+            # Step 2: Discover competitors using Exa API
+            logger.info("Step 2: Discovering competitors...")
+            competitor_results = await self.exa_service.discover_competitors(
+                user_url=user_url,
+                num_results=num_results,
+                exclude_domains=None,  # Let ExaService handle domain exclusion
+                industry_context=industry_context,
+                website_analysis_data=website_analysis_data
+            )
+            
+            if not competitor_results["success"]:
+                logger.error(f"Competitor discovery failed: {competitor_results.get('error')}")
+                return competitor_results
+            
+            # Process and enhance competitor data
+            enhanced_competitors = await self._enhance_competitor_data(
+                competitor_results["competitors"],
+                user_url,
+                industry_context
+            )
+            
+            # Store research data in database
+            await self._store_research_data(
+                session_id=session_id,
+                user_url=user_url,
+                competitors=enhanced_competitors,
+                industry_context=industry_context,
+                analysis_metadata={
+                    **competitor_results,
+                    "social_media_data": social_media_results
+                }
+            )
+            
+            # Generate research summary
+            research_summary = self._generate_research_summary(
+                enhanced_competitors,
+                industry_context
+            )
+            
+            logger.info(f"Successfully discovered {len(enhanced_competitors)} competitors for session {session_id}")
+            
+            return {
+                "success": True,
+                "session_id": session_id,
+                "user_url": user_url,
+                "competitors": enhanced_competitors,
+                "social_media_accounts": social_media_results.get("social_media_accounts", {}),
+                "social_media_citations": social_media_results.get("citations", []),
+                "research_summary": research_summary,
+                "total_competitors": len(enhanced_competitors),
+                "industry_context": industry_context,
+                "analysis_timestamp": datetime.utcnow().isoformat(),
+                "api_cost": competitor_results.get("api_cost", 0) + social_media_results.get("api_cost", 0)
+            }
+            
+        except Exception as e:
+            logger.error(f"Error in competitor discovery for onboarding: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "session_id": session_id,
+                "user_url": user_url
+            }
+    
+    async def _enhance_competitor_data(
+        self,
+        competitors: List[Dict[str, Any]],
+        user_url: str,
+        industry_context: Optional[str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Enhance competitor data with additional analysis.
+        
+        Args:
+            competitors: Raw competitor data from Exa API
+            user_url: User's website URL for comparison
+            industry_context: Industry context
+            
+        Returns:
+            List of enhanced competitor data
+        """
+        enhanced_competitors = []
+        
+        for competitor in competitors:
+            try:
+                # Add competitive analysis
+                competitive_analysis = self._analyze_competitor_competitiveness(
+                    competitor,
+                    user_url,
+                    industry_context
+                )
+                
+                # Add content strategy insights
+                content_insights = self._analyze_content_strategy(competitor)
+                
+                # Add market positioning
+                market_positioning = self._analyze_market_positioning(competitor)
+                
+                enhanced_competitor = {
+                    **competitor,
+                    "competitive_analysis": competitive_analysis,
+                    "content_insights": content_insights,
+                    "market_positioning": market_positioning,
+                    "enhanced_timestamp": datetime.utcnow().isoformat()
+                }
+                
+                enhanced_competitors.append(enhanced_competitor)
+                
+            except Exception as e:
+                logger.warning(f"Error enhancing competitor data: {str(e)}")
+                enhanced_competitors.append(competitor)
+        
+        return enhanced_competitors
+    
+    def _analyze_competitor_competitiveness(
+        self,
+        competitor: Dict[str, Any],
+        user_url: str,
+        industry_context: Optional[str]
+    ) -> Dict[str, Any]:
+        """
+        Analyze competitor competitiveness.
+        
+        Args:
+            competitor: Competitor data
+            user_url: User's website URL
+            industry_context: Industry context
+            
+        Returns:
+            Dictionary of competitive analysis
+        """
+        analysis = {
+            "threat_level": "medium",
+            "competitive_strengths": [],
+            "competitive_weaknesses": [],
+            "market_share_estimate": "unknown",
+            "differentiation_opportunities": []
+        }
+        
+        # Analyze threat level based on relevance score
+        relevance_score = competitor.get("relevance_score", 0)
+        if relevance_score > 0.8:
+            analysis["threat_level"] = "high"
+        elif relevance_score < 0.4:
+            analysis["threat_level"] = "low"
+        
+        # Analyze competitive strengths from content
+        summary = competitor.get("summary", "").lower()
+        highlights = competitor.get("highlights", [])
+        
+        # Extract strengths from content analysis
+        if "innovative" in summary or "cutting-edge" in summary:
+            analysis["competitive_strengths"].append("Innovation leadership")
+        
+        if "comprehensive" in summary or "complete" in summary:
+            analysis["competitive_strengths"].append("Comprehensive solution")
+        
+        if any("enterprise" in highlight.lower() for highlight in highlights):
+            analysis["competitive_strengths"].append("Enterprise focus")
+        
+        # Generate differentiation opportunities
+        if not any("saas" in summary for summary in [summary]):
+            analysis["differentiation_opportunities"].append("SaaS platform differentiation")
+        
+        return analysis
+    
+    def _analyze_content_strategy(self, competitor: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Analyze competitor's content strategy.
+        
+        Args:
+            competitor: Competitor data
+            
+        Returns:
+            Dictionary of content strategy analysis
+        """
+        strategy = {
+            "content_focus": "general",
+            "target_audience": "unknown",
+            "content_types": [],
+            "publishing_frequency": "unknown",
+            "content_quality": "medium"
+        }
+        
+        summary = competitor.get("summary", "").lower()
+        title = competitor.get("title", "").lower()
+        
+        # Analyze content focus
+        if "technical" in summary or "developer" in summary:
+            strategy["content_focus"] = "technical"
+        elif "business" in summary or "enterprise" in summary:
+            strategy["content_focus"] = "business"
+        elif "marketing" in summary or "seo" in summary:
+            strategy["content_focus"] = "marketing"
+        
+        # Analyze target audience
+        if "startup" in summary or "small business" in summary:
+            strategy["target_audience"] = "startups_small_business"
+        elif "enterprise" in summary or "large" in summary:
+            strategy["target_audience"] = "enterprise"
+        elif "developer" in summary or "technical" in summary:
+            strategy["target_audience"] = "developers"
+        
+        # Analyze content quality
+        if len(summary) > 300:
+            strategy["content_quality"] = "high"
+        elif len(summary) < 100:
+            strategy["content_quality"] = "low"
+        
+        return strategy
+    
+    def _analyze_market_positioning(self, competitor: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Analyze competitor's market positioning.
+        
+        Args:
+            competitor: Competitor data
+            
+        Returns:
+            Dictionary of market positioning analysis
+        """
+        positioning = {
+            "market_tier": "unknown",
+            "pricing_position": "unknown",
+            "brand_positioning": "unknown",
+            "competitive_advantage": "unknown"
+        }
+        
+        summary = competitor.get("summary", "").lower()
+        title = competitor.get("title", "").lower()
+        
+        # Analyze market tier
+        if "enterprise" in summary or "enterprise" in title:
+            positioning["market_tier"] = "enterprise"
+        elif "startup" in summary or "small" in summary:
+            positioning["market_tier"] = "startup_small_business"
+        elif "premium" in summary or "professional" in summary:
+            positioning["market_tier"] = "premium"
+        
+        # Analyze brand positioning
+        if "innovative" in summary or "cutting-edge" in summary:
+            positioning["brand_positioning"] = "innovator"
+        elif "reliable" in summary or "trusted" in summary:
+            positioning["brand_positioning"] = "trusted_leader"
+        elif "affordable" in summary or "cost-effective" in summary:
+            positioning["brand_positioning"] = "value_leader"
+        
+        return positioning
+    
+    def _generate_research_summary(
+        self,
+        competitors: List[Dict[str, Any]],
+        industry_context: Optional[str]
+    ) -> Dict[str, Any]:
+        """
+        Generate a summary of the research findings.
+        
+        Args:
+            competitors: List of enhanced competitor data
+            industry_context: Industry context
+            
+        Returns:
+            Dictionary containing research summary
+        """
+        if not competitors:
+            return {
+                "total_competitors": 0,
+                "market_insights": "No competitors found",
+                "key_findings": [],
+                "recommendations": []
+            }
+        
+        # Analyze market landscape
+        threat_levels = [comp.get("competitive_analysis", {}).get("threat_level", "medium") for comp in competitors]
+        high_threat_count = threat_levels.count("high")
+        
+        # Extract common themes
+        content_focuses = [comp.get("content_insights", {}).get("content_focus", "general") for comp in competitors]
+        content_focus_distribution = {focus: content_focuses.count(focus) for focus in set(content_focuses)}
+        
+        # Generate key findings
+        key_findings = []
+        if high_threat_count > len(competitors) * 0.3:
+            key_findings.append("Highly competitive market with multiple strong players")
+        
+        if "technical" in content_focus_distribution:
+            key_findings.append("Technical content is a key differentiator in this market")
+        
+        # Generate recommendations
+        recommendations = []
+        if high_threat_count > 0:
+            recommendations.append("Focus on unique value proposition to differentiate from strong competitors")
+        
+        if "technical" in content_focus_distribution and content_focus_distribution["technical"] > 2:
+            recommendations.append("Consider developing technical content strategy")
+        
+        return {
+            "total_competitors": len(competitors),
+            "high_threat_competitors": high_threat_count,
+            "content_focus_distribution": content_focus_distribution,
+            "market_insights": f"Found {len(competitors)} competitors in {industry_context or 'the market'}",
+            "key_findings": key_findings,
+            "recommendations": recommendations,
+            "competitive_landscape": "moderate" if high_threat_count < len(competitors) * 0.5 else "high"
+        }
+    
+    async def _store_research_data(
+        self,
+        session_id: str,
+        user_url: str,
+        competitors: List[Dict[str, Any]],
+        industry_context: Optional[str],
+        analysis_metadata: Dict[str, Any]
+    ) -> bool:
+        """
+        Store research data in the database.
+        
+        Args:
+            session_id: Onboarding session ID
+            user_url: User's website URL
+            competitors: Competitor data
+            industry_context: Industry context
+            analysis_metadata: Analysis metadata
+            
+        Returns:
+            Boolean indicating success
+        """
+        try:
+            with get_db_session() as db:
+                # Get or create onboarding session
+                session = db.query(OnboardingSession).filter(
+                    OnboardingSession.id == session_id
+                ).first()
+                
+                if not session:
+                    logger.error(f"Onboarding session {session_id} not found")
+                    return False
+                
+                # Update session with research data
+                research_data = {
+                    "step3_research_data": {
+                        "user_url": user_url,
+                        "competitors": competitors,
+                        "industry_context": industry_context,
+                        "analysis_metadata": analysis_metadata,
+                        "completed_at": datetime.utcnow().isoformat()
+                    }
+                }
+                
+                # Merge with existing data
+                if session.step_data:
+                    session.step_data.update(research_data)
+                else:
+                    session.step_data = research_data
+                
+                db.commit()
+                logger.info(f"Research data stored for session {session_id}")
+                return True
+                
+        except Exception as e:
+            logger.error(f"Error storing research data: {str(e)}")
+            return False
+    
+    async def get_research_data(self, session_id: str) -> Dict[str, Any]:
+        """
+        Retrieve research data for a session.
+        
+        Args:
+            session_id: Onboarding session ID
+            
+        Returns:
+            Dictionary containing research data
+        """
+        try:
+            with get_db_session() as db:
+                session = db.query(OnboardingSession).filter(
+                    OnboardingSession.id == session_id
+                ).first()
+                
+                if not session:
+                    return {
+                        "success": False,
+                        "error": "Session not found"
+                    }
+                
+                research_data = session.step_data.get("step3_research_data") if session.step_data else None
+                
+                if not research_data:
+                    return {
+                        "success": False,
+                        "error": "No research data found for this session"
+                    }
+                
+                return {
+                    "success": True,
+                    "research_data": research_data,
+                    "session_id": session_id
+                }
+                
+        except Exception as e:
+            logger.error(f"Error retrieving research data: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def _extract_domain(self, url: str) -> str:
+        """
+        Extract domain from URL.
+        
+        Args:
+            url: Website URL
+            
+        Returns:
+            Domain name
+        """
+        try:
+            from urllib.parse import urlparse
+            parsed = urlparse(url)
+            return parsed.netloc
+        except Exception:
+            return url
+    
+    async def health_check(self) -> Dict[str, Any]:
+        """
+        Check the health of the Step 3 Research Service.
+        
+        Returns:
+            Dictionary containing service health status
+        """
+        try:
+            exa_health = await self.exa_service.health_check()
+            
+            return {
+                "status": "healthy" if exa_health["status"] == "healthy" else "degraded",
+                "service": self.service_name,
+                "exa_service_status": exa_health["status"],
+                "timestamp": datetime.utcnow().isoformat()
+            }
+            
+        except Exception as e:
+            return {
+                "status": "error",
+                "service": self.service_name,
+                "error": str(e),
+                "timestamp": datetime.utcnow().isoformat()
+            }
--- a/backend/api/onboarding_utils/step3_routes.py
+++ b/backend/api/onboarding_utils/step3_routes.py
@@ -0,0 +1,309 @@
+"""
+Step 3 Research Routes for Onboarding
+
+FastAPI routes for Step 3 research phase of onboarding,
+including competitor discovery and research data management.
+
+Author: ALwrity Team
+Version: 1.0
+Last Updated: January 2025
+"""
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends
+from pydantic import BaseModel, HttpUrl, Field
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+import traceback
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user
+from .step3_research_service import Step3ResearchService
+
+router = APIRouter(prefix="/api/onboarding/step3", tags=["Onboarding Step 3 - Research"])
+
+# Request/Response Models
+class CompetitorDiscoveryRequest(BaseModel):
+    """Request model for competitor discovery."""
+    session_id: Optional[str] = Field(None, description="Deprecated - user identification comes from auth token")
+    user_url: str = Field(..., description="User's website URL")
+    industry_context: Optional[str] = Field(None, description="Industry context for better discovery")
+    num_results: int = Field(25, ge=1, le=100, description="Number of competitors to discover")
+    website_analysis_data: Optional[Dict[str, Any]] = Field(None, description="Website analysis data from Step 2 for better targeting")
+
+class CompetitorDiscoveryResponse(BaseModel):
+    """Response model for competitor discovery."""
+    success: bool
+    message: str
+    session_id: str
+    user_url: str
+    competitors: Optional[List[Dict[str, Any]]] = None
+    social_media_accounts: Optional[Dict[str, str]] = None
+    social_media_citations: Optional[List[Dict[str, Any]]] = None
+    research_summary: Optional[Dict[str, Any]] = None
+    total_competitors: Optional[int] = None
+    industry_context: Optional[str] = None
+    analysis_timestamp: Optional[str] = None
+    api_cost: Optional[float] = None
+    error: Optional[str] = None
+
+class ResearchDataRequest(BaseModel):
+    """Request model for retrieving research data."""
+    session_id: str = Field(..., description="Onboarding session ID")
+
+class ResearchDataResponse(BaseModel):
+    """Response model for research data retrieval."""
+    success: bool
+    message: str
+    session_id: Optional[str] = None
+    research_data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+class ResearchHealthResponse(BaseModel):
+    """Response model for research service health check."""
+    success: bool
+    message: str
+    service_status: Optional[Dict[str, Any]] = None
+    timestamp: Optional[str] = None
+
+# Initialize service
+step3_research_service = Step3ResearchService()
+
+@router.post("/discover-competitors", response_model=CompetitorDiscoveryResponse)
+async def discover_competitors(
+    request: CompetitorDiscoveryRequest,
+    background_tasks: BackgroundTasks,
+    current_user: dict = Depends(get_current_user)
+) -> CompetitorDiscoveryResponse:
+    """
+    Discover competitors for the user's website using Exa API with user isolation.
+    
+    This endpoint performs neural search to find semantically similar websites
+    and analyzes their content for competitive intelligence.
+    """
+    try:
+        # Get Clerk user ID for user isolation
+        clerk_user_id = str(current_user.get('id'))
+        
+        logger.info(f"Starting competitor discovery for authenticated user {clerk_user_id}, URL: {request.user_url}")
+        logger.info(f"Request data - user_url: '{request.user_url}', industry_context: '{request.industry_context}', num_results: {request.num_results}")
+        
+        # Validate URL format
+        if not request.user_url.startswith(('http://', 'https://')):
+            request.user_url = f"https://{request.user_url}"
+        
+        # Perform competitor discovery with Clerk user ID
+        result = await step3_research_service.discover_competitors_for_onboarding(
+            user_url=request.user_url,
+            session_id=clerk_user_id,  # Use Clerk user ID for isolation
+            industry_context=request.industry_context,
+            num_results=request.num_results,
+            website_analysis_data=request.website_analysis_data
+        )
+        
+        if result["success"]:
+            logger.info(f"✅ Successfully discovered {result['total_competitors']} competitors for user {clerk_user_id}")
+            
+            return CompetitorDiscoveryResponse(
+                success=True,
+                message=f"Successfully discovered {result['total_competitors']} competitors and social media accounts",
+                session_id=result["session_id"],
+                user_url=result["user_url"],
+                competitors=result["competitors"],
+                social_media_accounts=result.get("social_media_accounts"),
+                social_media_citations=result.get("social_media_citations"),
+                research_summary=result["research_summary"],
+                total_competitors=result["total_competitors"],
+                industry_context=result["industry_context"],
+                analysis_timestamp=result["analysis_timestamp"],
+                api_cost=result["api_cost"]
+            )
+        else:
+            logger.error(f"❌ Competitor discovery failed for user {clerk_user_id}: {result.get('error')}")
+            
+            return CompetitorDiscoveryResponse(
+                success=False,
+                message="Competitor discovery failed",
+                session_id=clerk_user_id,
+                user_url=result.get("user_url", request.user_url),
+                error=result.get("error", "Unknown error occurred")
+            )
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"❌ Error in competitor discovery endpoint: {str(e)}")
+        logger.error(traceback.format_exc())
+        
+        # Return error response with Clerk user ID
+        clerk_user_id = str(current_user.get('id', 'unknown'))
+        return CompetitorDiscoveryResponse(
+            success=False,
+            message="Internal server error during competitor discovery",
+            session_id=clerk_user_id,
+            user_url=request.user_url,
+            error=str(e)
+        )
+
+@router.post("/research-data", response_model=ResearchDataResponse)
+async def get_research_data(request: ResearchDataRequest) -> ResearchDataResponse:
+    """
+    Retrieve research data for a specific onboarding session.
+    
+    This endpoint returns the stored research data including competitor analysis
+    and research summary for the given session.
+    """
+    try:
+        logger.info(f"Retrieving research data for session {request.session_id}")
+        
+        # Validate session ID
+        if not request.session_id or len(request.session_id) < 10:
+            raise HTTPException(
+                status_code=400,
+                detail="Invalid session ID"
+            )
+        
+        # Retrieve research data
+        result = await step3_research_service.get_research_data(request.session_id)
+        
+        if result["success"]:
+            logger.info(f"Successfully retrieved research data for session {request.session_id}")
+            
+            return ResearchDataResponse(
+                success=True,
+                message="Research data retrieved successfully",
+                session_id=result["session_id"],
+                research_data=result["research_data"]
+            )
+        else:
+            logger.warning(f"No research data found for session {request.session_id}")
+            
+            return ResearchDataResponse(
+                success=False,
+                message="No research data found for this session",
+                session_id=request.session_id,
+                error=result.get("error", "Research data not found")
+            )
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error retrieving research data: {str(e)}")
+        logger.error(traceback.format_exc())
+        
+        return ResearchDataResponse(
+            success=False,
+            message="Internal server error while retrieving research data",
+            session_id=request.session_id,
+            error=str(e)
+        )
+
+@router.get("/health", response_model=ResearchHealthResponse)
+async def health_check() -> ResearchHealthResponse:
+    """
+    Check the health of the Step 3 research service.
+    
+    This endpoint provides health status information for the research service
+    including Exa API connectivity and service status.
+    """
+    try:
+        logger.info("Performing Step 3 research service health check")
+        
+        health_status = await step3_research_service.health_check()
+        
+        if health_status["status"] == "healthy":
+            return ResearchHealthResponse(
+                success=True,
+                message="Step 3 research service is healthy",
+                service_status=health_status,
+                timestamp=health_status["timestamp"]
+            )
+        else:
+            return ResearchHealthResponse(
+                success=False,
+                message=f"Step 3 research service is {health_status['status']}",
+                service_status=health_status,
+                timestamp=health_status["timestamp"]
+            )
+            
+    except Exception as e:
+        logger.error(f"Error in health check: {str(e)}")
+        logger.error(traceback.format_exc())
+        
+        return ResearchHealthResponse(
+            success=False,
+            message="Health check failed",
+            error=str(e),
+            timestamp=datetime.utcnow().isoformat()
+        )
+
+@router.post("/validate-session")
+async def validate_session(session_id: str) -> Dict[str, Any]:
+    """
+    Validate that a session exists and is ready for Step 3.
+    
+    This endpoint checks if the session exists and has completed previous steps.
+    """
+    try:
+        logger.info(f"Validating session {session_id} for Step 3")
+        
+        # Basic validation
+        if not session_id or len(session_id) < 10:
+            raise HTTPException(
+                status_code=400,
+                detail="Invalid session ID format"
+            )
+        
+        # Check if session has completed Step 2 (website analysis)
+        # This would integrate with the existing session validation logic
+        
+        return {
+            "success": True,
+            "message": "Session is valid for Step 3",
+            "session_id": session_id,
+            "ready_for_step3": True
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error validating session: {str(e)}")
+        
+        return {
+            "success": False,
+            "message": "Session validation failed",
+            "error": str(e)
+        }
+
+@router.get("/cost-estimate")
+async def get_cost_estimate(
+    num_results: int = 25,
+    include_content: bool = True
+) -> Dict[str, Any]:
+    """
+    Get cost estimate for competitor discovery.
+    
+    This endpoint provides cost estimates for Exa API usage
+    to help users understand the cost of competitor discovery.
+    """
+    try:
+        logger.info(f"Getting cost estimate for {num_results} results, content: {include_content}")
+        
+        cost_estimate = step3_research_service.exa_service.get_cost_estimate(
+            num_results=num_results,
+            include_content=include_content
+        )
+        
+        return {
+            "success": True,
+            "cost_estimate": cost_estimate,
+            "message": "Cost estimate calculated successfully"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error calculating cost estimate: {str(e)}")
+        
+        return {
+            "success": False,
+            "message": "Failed to calculate cost estimate",
+            "error": str(e)
+        }
--- a/backend/api/onboarding_utils/step_management_service.py
+++ b/backend/api/onboarding_utils/step_management_service.py
@@ -0,0 +1,217 @@
+"""
+Step Management Service
+Handles onboarding step operations and progress tracking.
+"""
+
+from typing import Dict, Any, List, Optional
+from fastapi import HTTPException
+from loguru import logger
+
+from services.api_key_manager import get_onboarding_progress_for_user, StepStatus
+from services.progressive_setup_service import ProgressiveSetupService
+from services.database import get_db_session
+
+class StepManagementService:
+    """Service for handling onboarding step management."""
+    
+    def __init__(self):
+        pass
+    
+    async def get_onboarding_status(self, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Get the current onboarding status (per user)."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            
+            # Safety check: if all steps are completed, ensure is_completed is True
+            all_steps_completed = all(s.status in [StepStatus.COMPLETED, StepStatus.SKIPPED] for s in progress.steps)
+            if all_steps_completed and not progress.is_completed:
+                logger.info(f"[get_onboarding_status] All steps completed but is_completed was False, fixing...")
+                progress.is_completed = True
+                progress.completed_at = progress.started_at  # Use started_at as fallback
+                progress.current_step = len(progress.steps)
+                progress.save_progress()
+            
+            return {
+                "is_completed": progress.is_completed,
+                "current_step": progress.current_step,
+                "completion_percentage": progress.get_completion_percentage(),
+                "next_step": progress.get_next_incomplete_step(),
+                "started_at": progress.started_at,
+                "completed_at": progress.completed_at,
+                "can_proceed_to_final": progress.can_complete_onboarding()
+            }
+        except Exception as e:
+            logger.error(f"Error getting onboarding status: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_onboarding_progress_full(self, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Get the full onboarding progress data."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            
+            # Convert StepData objects to dictionaries
+            step_data = []
+            for step in progress.steps:
+                step_data.append({
+                    "step_number": step.step_number,
+                    "title": step.title,
+                    "description": step.description,
+                    "status": step.status.value,
+                    "completed_at": step.completed_at,
+                    "data": step.data,
+                    "validation_errors": step.validation_errors or []
+                })
+            
+            return {
+                "steps": step_data,
+                "current_step": progress.current_step,
+                "started_at": progress.started_at,
+                "last_updated": progress.last_updated,
+                "is_completed": progress.is_completed,
+                "completed_at": progress.completed_at,
+                "completion_percentage": progress.get_completion_percentage()
+            }
+        except Exception as e:
+            logger.error(f"Error getting onboarding progress: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def get_step_data(self, step_number: int, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Get data for a specific step."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            step = progress.get_step_data(step_number)
+            
+            if not step:
+                raise HTTPException(status_code=404, detail=f"Step {step_number} not found")
+            
+            return {
+                "step_number": step.step_number,
+                "title": step.title,
+                "description": step.description,
+                "status": step.status.value,
+                "completed_at": step.completed_at,
+                "data": step.data,
+                "validation_errors": step.validation_errors or []
+            }
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error getting step data: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def complete_step(self, step_number: int, request_data: Dict[str, Any], current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Mark a step as completed."""
+        try:
+            logger.info(f"[complete_step] Completing step {step_number}")
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            step = progress.get_step_data(step_number)
+            
+            if not step:
+                logger.error(f"[complete_step] Step {step_number} not found")
+                raise HTTPException(status_code=404, detail=f"Step {step_number} not found")
+            
+            # Validate step data before marking as completed
+            from services.validation import validate_step_data
+            logger.info(f"[complete_step] Validating step {step_number} with data: {request_data}")
+            validation_errors = validate_step_data(step_number, request_data)
+            
+            if validation_errors:
+                logger.warning(f"[complete_step] Step {step_number} validation failed: {validation_errors}")
+                raise HTTPException(status_code=400, detail=f"Step validation failed: {'; '.join(validation_errors)}")
+            
+            # Mark step as completed
+            progress.mark_step_completed(step_number, request_data)
+            logger.info(f"[complete_step] Step {step_number} completed successfully")
+            
+            # If this is step 1 (API keys), also save to global .env file
+            if step_number == 1 and request_data and 'api_keys' in request_data:
+                try:
+                    from services.api_key_manager import APIKeyManager
+                    api_manager = APIKeyManager()
+                    
+                    # Save each API key to the global .env file
+                    api_keys = request_data['api_keys']
+                    for provider, api_key in api_keys.items():
+                        if api_key:  # Only save non-empty keys
+                            api_manager.save_api_key(provider, api_key)
+                            logger.info(f"[complete_step] Saved {provider} API key to global .env file")
+                except Exception as env_error:
+                    logger.warning(f"Could not save API keys to global .env file: {env_error}")
+                    # Don't fail the step completion for .env file issues
+            
+            # Initialize/upgrade user environment based on new step
+            try:
+                db_session = get_db_session()
+                if db_session:
+                    setup_service = ProgressiveSetupService(db_session)
+                    
+                    # Initialize environment if first time, or upgrade if progressing
+                    if step_number == 1:
+                        setup_service.initialize_user_environment(user_id)
+                    else:
+                        setup_service.upgrade_user_environment(user_id, step_number)
+                    
+                    db_session.close()
+            except Exception as env_error:
+                logger.warning(f"Could not set up user environment: {env_error}")
+                # Don't fail the step completion for environment setup issues
+            
+            return {
+                "message": f"Step {step_number} completed successfully",
+                "step_number": step_number,
+                "data": request_data
+            }
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error completing step: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def skip_step(self, step_number: int, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Skip a step (for optional steps)."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            step = progress.get_step_data(step_number)
+            
+            if not step:
+                raise HTTPException(status_code=404, detail=f"Step {step_number} not found")
+            
+            # Mark step as skipped
+            progress.mark_step_skipped(step_number)
+            
+            return {
+                "message": f"Step {step_number} skipped successfully",
+                "step_number": step_number
+            }
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error skipping step: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+    
+    async def validate_step_access(self, step_number: int, current_user: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate if user can access a specific step."""
+        try:
+            user_id = str(current_user.get('id'))
+            progress = get_onboarding_progress_for_user(user_id)
+            
+            if not progress.can_proceed_to_step(step_number):
+                return {
+                    "can_proceed": False,
+                    "validation_errors": [f"Cannot proceed to step {step_number}. Complete previous steps first."],
+                    "step_status": "locked"
+                }
+            
+            return {
+                "can_proceed": True,
+                "validation_errors": [],
+                "step_status": "available"
+            }
+        except Exception as e:
+            logger.error(f"Error validating step access: {str(e)}")
+            raise HTTPException(status_code=500, detail="Internal server error")