ALwrity/SETUP_GUIDE.md

ALwrity Setup Guide

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• npm or yarn

---

📋 Complete Setup Steps

1. Backend Setup

Option A: Run from project root (Recommended)

# Install backend dependencies
cd backend
pip install -r requirements.txt

# Run backend from project root
cd ..
python run_backend.py

Option B: Run from backend directory

cd backend
pip install -r requirements.txt
python main.py

Backend will be available at: http://localhost:8000

2. Frontend Setup

cd frontend
npm install
npm start

Frontend will be available at: http://localhost:3000

---

🏗️ New Architecture Overview

Project Structure

alwrity/
├── backend/                    # FastAPI Backend
│   ├── main.py                # Main FastAPI application
│   ├── api/
│   │   ├── onboarding.py      # Core onboarding endpoints
│   │   └── component_logic.py # Advanced component endpoints
│   ├── services/
│   │   ├── api_key_manager.py # API key management service
│   │   ├── validation.py      # Validation services
│   │   └── component_logic/   # Component logic services
│   │       ├── ai_research_logic.py
│   │       ├── personalization_logic.py
│   │       └── research_utilities.py
│   ├── models/
│   │   ├── onboarding.py      # Database models
│   │   └── component_logic.py # Component logic models
│   └── requirements.txt       # Python dependencies
│
├── frontend/                   # React Frontend
│   ├── src/
│   │   ├── App.tsx            # Main app with onboarding check
│   │   ├── components/
│   │   │   ├── OnboardingWizard/  # Complete onboarding flow
│   │   │   │   ├── common/        # Design system components
│   │   │   │   │   ├── useOnboardingStyles.ts
│   │   │   │   │   ├── onboardingUtils.ts
│   │   │   │   │   ├── OnboardingStepLayout.tsx
│   │   │   │   │   ├── OnboardingCard.tsx
│   │   │   │   │   └── OnboardingButton.tsx
│   │   │   │   ├── ApiKeyStep.tsx
│   │   │   │   ├── WebsiteStep.tsx
│   │   │   │   ├── ResearchStep.tsx
│   │   │   │   ├── PersonalizationStep.tsx
│   │   │   │   ├── IntegrationsStep.tsx
│   │   │   │   ├── FinalStep.tsx
│   │   │   │   └── ResearchTestStep.tsx
│   │   │   └── MainApp.tsx        # Main application
│   │   └── api/
│   │       ├── onboarding.ts      # Onboarding API integration
│   │       └── componentLogic.ts  # Component logic API integration
│   └── package.json           # Node.js dependencies
│
└── lib/utils/api_key_manager/ # Legacy Streamlit (reference only)
    ├── onboarding_progress.py # Migrated to backend
    ├── components/            # Migrated to React
    └── ...

---

🔧 Development Mode

Terminal 1: Backend

# From project root
python run_backend.py

Terminal 2: Frontend

cd frontend
npm start

---

🧪 Testing the Setup

1. Test Backend Health

curl http://localhost:8000/health

Expected Response:

{"status":"healthy","timestamp":"2025-07-28T18:14:35.749581"}

2. Test Onboarding Check

curl http://localhost:8000/api/check-onboarding

Expected Response:

{"onboarding_required":false,"onboarding_complete":true}

3. Test Component Logic Endpoints

# Test AI Research endpoint
curl -X POST http://localhost:8000/api/onboarding/ai-research/validate-user \
  -H "Content-Type: application/json" \
  -d '{"full_name": "John Doe", "email": "john@example.com", "company": "Test Corp", "role": "Developer"}'

# Test Personalization endpoint
curl -X POST http://localhost:8000/api/onboarding/personalization/validate-style \
  -H "Content-Type: application/json" \
  -d '{"writing_style": "Professional", "tone": "Formal", "content_length": "Standard"}'

4. Test Frontend

• Open http://localhost:3000 in your browser
• You should see the ALwrity application with modern React interface

---

📊 API Endpoints Overview

Core Endpoints (12 Total)

# Health and Status
GET /health                    # Health check
GET /api/status               # Application status

# Onboarding Endpoints
GET /api/onboarding/status    # Get onboarding status
GET /api/onboarding/progress  # Get full progress data
GET /api/onboarding/step/{n}  # Get step data
POST /api/onboarding/step/{n}/complete  # Complete step
POST /api/onboarding/step/{n}/skip      # Skip step
GET /api/onboarding/api-keys  # Get API keys
POST /api/onboarding/api-keys # Save API key
GET /api/onboarding/resume    # Get resume info

# Provider Information
GET /api/onboarding/providers                    # Get all providers
GET /api/onboarding/providers/{provider}/setup   # Get setup info
POST /api/onboarding/providers/{provider}/validate # Validate key
GET /api/onboarding/validation/enhanced          # Enhanced validation

Component Logic Endpoints (15 Total)

# AI Research Endpoints (4)
POST /api/onboarding/ai-research/validate-user
POST /api/onboarding/ai-research/configure-preferences
POST /api/onboarding/ai-research/process-research
GET /api/onboarding/ai-research/configuration-options

# Personalization Endpoints (6)
POST /api/onboarding/personalization/validate-style
POST /api/onboarding/personalization/configure-brand
POST /api/onboarding/personalization/process-settings
GET /api/onboarding/personalization/configuration-options
POST /api/onboarding/personalization/generate-guidelines

# Research Utilities Endpoints (5)
POST /api/onboarding/research/process-topic
POST /api/onboarding/research/process-results
POST /api/onboarding/research/validate-request
GET /api/onboarding/research/providers-info
POST /api/onboarding/research/generate-report

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

---

🎯 Application Flow

First-Time Users

1. Visit http://localhost:3000
2. System checks onboarding status
3. Shows React onboarding wizard with 6 steps:
   • Step 1: API Key Management
   • Step 2: Website Setup
   • Step 3: Research Configuration
   • Step 4: Personalization Settings
   • Step 5: Integrations
   • Step 6: Final Setup
4. Complete setup with modern UI
5. Redirects to main application

Returning Users

1. Visit http://localhost:3000
2. System checks onboarding status
3. Shows main application directly

---

🐛 Troubleshooting

Backend Issues

Import Errors

# If you get "No module named 'backend'" error:
# Use the run_backend.py script from project root
python run_backend.py

Missing Dependencies

cd backend
pip install -r requirements.txt

Port Already in Use

# Find and kill process using port 8000
lsof -ti:8000 | xargs kill -9

Database Issues

# Remove and recreate database
rm backend/onboarding.db
# Restart backend - database will be recreated automatically

Frontend Issues

Build Errors

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

Port Conflicts

# Change port in package.json or use different port
npm start -- --port 3001

CORS Issues

• Ensure backend CORS is configured correctly
• Check that frontend is making requests to correct backend URL
• Verify proxy configuration in package.json

Component Logic Issues

API Key Validation

# Test API key validation
curl -X POST http://localhost:8000/api/onboarding/providers/openai/validate \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-your-openai-key"}'

Research Utilities

# Test research topic processing
curl -X POST http://localhost:8000/api/onboarding/research/process-topic \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI writing tools", "providers": ["tavily"], "depth": "standard"}'

---

🔍 Monitoring & Debugging

Backend Logs

• Check terminal where backend is running
• Logs show API requests and errors
• FastAPI provides detailed error messages

Frontend Logs

• Check browser developer console
• React development server logs
• Network tab for API requests

Database

• SQLite database: backend/onboarding.db
• Created automatically on first run
• Can be inspected with SQLite browser

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Interactive testing of all endpoints

---

🚀 Production Deployment

Backend

# Build and run with gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

Frontend

cd frontend
npm run build
# Serve build/ folder with nginx or similar

Environment Variables

# Backend environment variables
export DATABASE_URL="sqlite:///./onboarding.db"
export CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:3000"
export LOG_LEVEL="INFO"

# Frontend environment variables
export REACT_APP_API_URL="http://localhost:8000"
export REACT_APP_ENVIRONMENT="development"

---

📚 Additional Documentation

• API Documentation - Complete FastAPI backend documentation
• Migration Guide - Complete migration documentation
• README.md - Main project documentation

---

🎉 Setup Complete!

✅ The new ALwrity architecture is ready for development and testing.

Key Features Available:

• 27 API Endpoints with comprehensive functionality
• Modern React Frontend with Material-UI components
• Component Logic Services for advanced features
• Design System for consistent UI/UX
• Real-time Validation and error handling
• Complete Onboarding Flow with 6 steps

Next Steps:

1. Test all endpoints using the API documentation
2. Explore the React components and design system
3. Configure API keys for different providers
4. Start developing new features using the established patterns