# Onboarding Services Package

This package contains all onboarding-related services and utilities for ALwrity. All onboarding data is stored in the database with proper user isolation, replacing the previous file-based JSON storage system.

## Architecture

### Database-First Design
- **Primary Storage**: PostgreSQL database with proper foreign keys and relationships
- **User Isolation**: Each user's onboarding data is completely separate
- **No File Storage**: Removed all JSON file operations for production scalability
- **Local Development**: API keys still written to `.env` for developer convenience

### Service Structure

```
backend/services/onboarding/
├── __init__.py                      # Package exports
├── database_service.py              # Core database operations
├── progress_service.py              # Progress tracking and step management
├── data_service.py                  # Data validation and processing
├── api_key_manager.py               # API key management + progress tracking
└── README.md                        # This documentation
```

## Services

### 1. OnboardingDatabaseService (`database_service.py`)
**Purpose**: Core database operations for onboarding data with user isolation.

**Key Features**:
- User-specific session management
- API key storage and retrieval
- Website analysis persistence
- Research preferences management
- Persona data storage
- Brand analysis support (feature-flagged)

**Main Methods**:
- `get_or_create_session(user_id)` - Get or create user session
- `save_api_key(user_id, provider, key)` - Store API keys
- `save_website_analysis(user_id, data)` - Store website analysis
- `save_research_preferences(user_id, prefs)` - Store research settings
- `save_persona_data(user_id, data)` - Store persona information

### 2. OnboardingProgressService (`progress_service.py`)
**Purpose**: High-level progress tracking and step management.

**Key Features**:
- Database-only progress tracking
- Step completion validation
- Progress percentage calculation
- Onboarding completion management

**Main Methods**:
- `get_onboarding_status(user_id)` - Get current status
- `update_step(user_id, step_number)` - Update current step
- `update_progress(user_id, percentage)` - Update progress
- `complete_onboarding(user_id)` - Mark as complete

### 3. OnboardingDataService (`data_service.py`)
**Purpose**: Extract and use onboarding data for AI personalization.

**Key Features**:
- Personalized AI input generation
- Website analysis data extraction
- Research preferences integration
- Default fallback data

**Main Methods**:
- `get_personalized_ai_inputs(user_id)` - Generate personalized inputs
- `get_user_website_analysis(user_id)` - Get website data
- `get_user_research_preferences(user_id)` - Get research settings

### 4. OnboardingProgress + APIKeyManager (`api_key_manager.py`)
**Purpose**: Combined API key management and progress tracking with database persistence.

**Key Features**:
- Database-only progress persistence (no JSON files)
- API key management with environment integration
- Step-by-step progress tracking
- User-specific progress instances

**Main Classes**:
- `OnboardingProgress` - Progress tracking with database persistence
- `APIKeyManager` - API key management
- `StepData` - Individual step data structure
- `StepStatus` - Step status enumeration

## Database Schema

### Core Tables
- `onboarding_sessions` - User session tracking
- `api_keys` - User-specific API key storage
- `website_analyses` - Website analysis data
- `research_preferences` - User research settings
- `persona_data` - Generated persona information

### Relationships
- All data tables reference `onboarding_sessions.id`
- User isolation via `user_id` foreign key
- Proper cascade deletion and updates

## Usage Examples

### Basic Progress Tracking
```python
from services.onboarding import OnboardingProgress

# Get user-specific progress
progress = OnboardingProgress(user_id="user123")

# Mark step as completed
progress.mark_step_completed(1, {"api_keys": {"openai": "sk-..."}})

# Get progress summary
summary = progress.get_progress_summary()
```

### Database Operations
```python
from services.onboarding import OnboardingDatabaseService
from services.database import SessionLocal

db = SessionLocal()
service = OnboardingDatabaseService(db)

# Save API key
service.save_api_key("user123", "openai", "sk-...")

# Get website analysis
analysis = service.get_website_analysis("user123", db)
```

### Progress Service
```python
from services.onboarding import OnboardingProgressService

service = OnboardingProgressService()

# Get status
status = service.get_onboarding_status("user123")

# Update progress
service.update_step("user123", 2)
service.update_progress("user123", 50.0)
```

## Migration from File-Based Storage

### What Was Removed
- JSON file operations (`.onboarding_progress*.json`)
- File-based progress persistence
- Dual persistence system (file + database)

### What Was Kept
- Database persistence (enhanced)
- Local development `.env` API key writing
- All existing functionality and APIs

### Benefits
- **Production Ready**: No ephemeral file storage
- **Scalable**: Database-backed with proper indexing
- **User Isolated**: Complete data separation
- **Maintainable**: Single source of truth

## Environment Variables

### Required
- Database connection (via `services.database`)
- User authentication system

### Optional
- `ENABLE_WEBSITE_BRAND_COLUMNS=true` - Enable brand analysis features
- `DEPLOY_ENV=local` - Enable local `.env` API key writing

## Error Handling

All services include comprehensive error handling:
- Database connection failures
- User not found scenarios
- Invalid data validation
- Graceful fallbacks to defaults

## Performance Considerations

- Database queries are optimized with proper indexing
- User-specific caching where appropriate
- Minimal database calls through efficient service design
- Connection pooling via SQLAlchemy

## Testing

Each service can be tested independently:
- Unit tests for individual methods
- Integration tests with database
- Mock database sessions for isolated testing

## Future Enhancements

- Real-time progress updates via WebSocket
- Progress analytics and reporting
- Bulk user operations
- Advanced validation rules
- Progress recovery mechanisms