194 lines
5.6 KiB
Markdown
194 lines
5.6 KiB
Markdown
# Alwrity Migration Guide: From Streamlit to React + FastAPI
|
|
|
|
## Overview
|
|
This guide explains how to migrate from the current Streamlit-based `alwrity.py` to the new React + FastAPI architecture while maintaining all present functionality.
|
|
|
|
---
|
|
|
|
## Architecture Changes
|
|
|
|
### Before (Streamlit)
|
|
```
|
|
alwrity.py (Streamlit app)
|
|
├── Onboarding (API key setup)
|
|
├── Main UI (sidebar navigation)
|
|
└── All features (AI writers, SEO tools, etc.)
|
|
```
|
|
|
|
### After (React + FastAPI)
|
|
```
|
|
Backend (FastAPI)
|
|
├── backend/main.py (replaces alwrity.py)
|
|
├── backend/api/onboarding.py (onboarding endpoints)
|
|
├── backend/services/api_key_manager.py (API key management)
|
|
└── backend/models/onboarding.py (database models)
|
|
|
|
Frontend (React)
|
|
├── frontend/src/App.tsx (main app with onboarding check)
|
|
├── frontend/src/components/OnboardingWizard/ (onboarding flow)
|
|
└── frontend/src/components/MainApp.tsx (main application)
|
|
```
|
|
|
|
---
|
|
|
|
## Key Changes
|
|
|
|
### 1. **alwrity.py → backend/main.py**
|
|
- **Before**: Single Streamlit file handling everything
|
|
- **After**: FastAPI backend with separate React frontend
|
|
- **Maintained**: All environment setup, API key checking, logging
|
|
|
|
### 2. **Onboarding Flow**
|
|
- **Before**: Streamlit-based onboarding in `alwrity.py`
|
|
- **After**: React wizard with FastAPI backend
|
|
- **Maintained**: Same onboarding steps and validation logic
|
|
|
|
### 3. **Application Flow**
|
|
- **Before**: Direct access to all features after onboarding
|
|
- **After**: Onboarding check → React wizard (first-time) → Main app (returning users)
|
|
- **Maintained**: All existing functionality preserved
|
|
|
|
---
|
|
|
|
## How to Run the New Architecture
|
|
|
|
### Option 1: Development Mode
|
|
```bash
|
|
# Terminal 1: Start FastAPI backend
|
|
cd backend
|
|
python main.py
|
|
# Backend runs on http://localhost:8000
|
|
|
|
# Terminal 2: Start React frontend
|
|
cd frontend
|
|
npm start
|
|
# Frontend runs on http://localhost:3000
|
|
```
|
|
|
|
### Option 2: Production Mode
|
|
```bash
|
|
# Build React app
|
|
cd frontend
|
|
npm run build
|
|
|
|
# Serve with FastAPI
|
|
cd backend
|
|
python main.py
|
|
# Both frontend and backend served from http://localhost:8000
|
|
```
|
|
|
|
---
|
|
|
|
## Migration Steps
|
|
|
|
### Phase 1: Backend Setup ✅
|
|
1. ✅ Extract API key management to `backend/services/api_key_manager.py`
|
|
2. ✅ Create FastAPI onboarding endpoints in `backend/api/onboarding.py`
|
|
3. ✅ Set up database models in `backend/models/onboarding.py`
|
|
4. ✅ Create main FastAPI app in `backend/main.py`
|
|
|
|
### Phase 2: Frontend Setup ✅
|
|
1. ✅ Create React onboarding wizard
|
|
2. ✅ Implement API integration
|
|
3. ✅ Create main app structure
|
|
4. ✅ Set up onboarding flow
|
|
|
|
### Phase 3: Feature Migration (Next Steps)
|
|
1. **Migrate AI Writers**: Wrap existing AI writer modules as FastAPI endpoints
|
|
2. **Migrate SEO Tools**: Create API endpoints for SEO functionality
|
|
3. **Migrate UI Components**: Convert Streamlit UI to React components
|
|
4. **Add Authentication**: Implement user management and sessions
|
|
|
|
---
|
|
|
|
## Maintaining Present Functionality
|
|
|
|
### ✅ Preserved Features
|
|
- **API Key Management**: Same validation and storage logic
|
|
- **Onboarding Flow**: Same steps, improved UI
|
|
- **Environment Setup**: All paths and configurations preserved
|
|
- **Logging**: Same logging configuration
|
|
- **Error Handling**: Enhanced with better user feedback
|
|
|
|
### 🔄 Enhanced Features
|
|
- **UI/UX**: Modern React interface with Material-UI
|
|
- **Performance**: Faster loading and better responsiveness
|
|
- **Scalability**: Backend can handle multiple users
|
|
- **Maintainability**: Separated concerns, easier to extend
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### Onboarding Endpoints
|
|
- `GET /api/check-onboarding` - Check if onboarding is required
|
|
- `POST /api/onboarding/start` - Start onboarding session
|
|
- `GET /api/onboarding/step` - Get current step
|
|
- `POST /api/onboarding/step` - Set current step
|
|
- `GET /api/onboarding/api-keys` - Get saved API keys
|
|
- `POST /api/onboarding/api-keys` - Save API key
|
|
- `GET /api/onboarding/progress` - Get onboarding progress
|
|
- `POST /api/onboarding/progress` - Set onboarding progress
|
|
|
|
### Application Endpoints
|
|
- `GET /api/status` - Get application status
|
|
- `GET /health` - Health check
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### For First-Time Users
|
|
1. User visits application
|
|
2. `App.tsx` checks onboarding status via `/api/check-onboarding`
|
|
3. If onboarding required → Show `Wizard.tsx`
|
|
4. User completes 6-step onboarding process
|
|
5. On completion → Switch to `MainApp.tsx`
|
|
|
|
### For Returning Users
|
|
1. User visits application
|
|
2. `App.tsx` checks onboarding status
|
|
3. If onboarding complete → Show `MainApp.tsx` directly
|
|
4. User accesses all features
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
### Immediate
|
|
1. **Test the onboarding flow** end-to-end
|
|
2. **Install dependencies** for React and FastAPI
|
|
3. **Configure development environment**
|
|
|
|
### Short-term
|
|
1. **Migrate AI Writers** to FastAPI endpoints
|
|
2. **Create React components** for main features
|
|
3. **Add authentication** and user management
|
|
|
|
### Long-term
|
|
1. **Add enterprise features** (SSO, multi-user, audit)
|
|
2. **Optimize performance** and scalability
|
|
3. **Add advanced features** (real-time collaboration, etc.)
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
1. **CORS errors**: Ensure CORS middleware is configured
|
|
2. **API connection errors**: Check backend is running on correct port
|
|
3. **Database errors**: Ensure SQLite database is created
|
|
4. **React build errors**: Install all required dependencies
|
|
|
|
### Dependencies Required
|
|
```bash
|
|
# Backend
|
|
pip install fastapi uvicorn sqlalchemy python-dotenv
|
|
|
|
# Frontend
|
|
npm install react @mui/material @mui/icons-material axios
|
|
```
|
|
|
|
---
|
|
|
|
**The migration maintains all present functionality while providing a modern, scalable foundation for enterprise features.** |