kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c87f27e56de564d7d6b796b8352b5fcdc94a9b06
ALwrity/SETUP_GUIDE.md
ajaysi 32f97fa6b3 ALwrity Version 0.5.0 (Fastapi + React )
2025-08-06 12:48:02 +05:30

383 lines
10 KiB
Markdown
Raw Blame History

# 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)**
```bash
# 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**
```bash
cd backend
pip install -r requirements.txt
python main.py
```
**Backend will be available at:** http://localhost:8000
### **2. Frontend Setup**
```bash
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**
```bash
# From project root
python run_backend.py
```
### **Terminal 2: Frontend**
```bash
cd frontend
npm start
```
---
## 🧪 **Testing the Setup**
### **1. Test Backend Health**
```bash
curl http://localhost:8000/health
```
**Expected Response:**
```json
{"status":"healthy","timestamp":"2025-07-28T18:14:35.749581"}
```
### **2. Test Onboarding Check**
```bash
curl http://localhost:8000/api/check-onboarding
```
**Expected Response:**
```json
{"onboarding_required":false,"onboarding_complete":true}
```
### **3. Test Component Logic Endpoints**
```bash
# 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)**
```python
# 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)**
```python
# 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**
```bash
# If you get "No module named 'backend'" error:
# Use the run_backend.py script from project root
python run_backend.py
```
#### **Missing Dependencies**
```bash
cd backend
pip install -r requirements.txt
```
#### **Port Already in Use**
```bash
# Find and kill process using port 8000
lsof -ti:8000 | xargs kill -9
```
#### **Database Issues**
```bash
# Remove and recreate database
rm backend/onboarding.db
# Restart backend - database will be recreated automatically
```
### **Frontend Issues**
#### **Build Errors**
```bash
cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build
```
#### **Port Conflicts**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# Build and run with gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
```
### **Frontend**
```bash
cd frontend
npm run build
# Serve build/ folder with nginx or similar
```
### **Environment Variables**
```bash
# 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](API_DOCUMENTATION.md)** - Complete FastAPI backend documentation
- **[Migration Guide](ALWRITY_MIGRATION_FINAL.md)** - Complete migration documentation
- **[README.md](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
Reference in New Issue View Git Blame Copy Permalink