kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Subscription Guard and Installation Guide

Browse Source
This commit is contained in:
ajaysi
2025-10-13 15:27:48 +05:30
parent c38812b6c5
commit b6debd80b7
13 changed files with 1176 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
.github/INSTALLATION.md vendored Normal file
View File

@@ -0,0 +1,286 @@
# ALwrity Quick Start Guide
Complete setup guide for running ALwrity locally after cloning from GitHub.
## 🎯 **Prerequisites**
Before you begin, ensure you have:
- **Node.js** 16+ and npm installed ([Download](https://nodejs.org/))
- **Python** 3.8+ installed ([Download](https://www.python.org/downloads/))
- **Git** installed ([Download](https://git-scm.com/downloads))
- **Clerk Account** ([Sign up](https://clerk.com/))
- **API Keys** (Gemini, CopilotKit, etc.)
## 🚀 **Quick Setup (Automated)**
### **Option A: Windows**
```powershell
# 1. Clone the repository
git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity
# 2. Run automated setup
.\setup_alwrity.bat
```
### **Option B: macOS/Linux**
```bash
# 1. Clone the repository
git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity
# 2. Make script executable and run
chmod +x setup_alwrity.sh
./setup_alwrity.sh
```
## 📝 **Manual Setup (Step-by-Step)**
### **Step 1: Clone Repository**
```bash
git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity
```
### **Step 2: Backend Setup**
```bash
# Navigate to backend
cd backend
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Create .env file
cp env_template.txt .env
# Edit .env and add your API keys:
# - CLERK_SECRET_KEY
# - CLERK_PUBLISHABLE_KEY
# - GEMINI_API_KEY (optional, can be provided in UI)
# Initialize database
python scripts/create_subscription_tables.py
python scripts/cleanup_alpha_plans.py
# Return to root
cd ..
```
### **Step 3: Frontend Setup**
```bash
# Navigate to frontend
cd frontend
# Clean install (important!)
rm -rf node_modules package-lock.json # macOS/Linux
# OR for Windows PowerShell:
# Remove-Item -Recurse -Force node_modules, package-lock.json -ErrorAction SilentlyContinue
# Install dependencies (THIS IS CRITICAL - DO NOT SKIP!)
npm install
# Create .env file
cp env_template.txt .env
# Edit .env and add:
# REACT_APP_CLERK_PUBLISHABLE_KEY=<your-clerk-publishable-key>
# REACT_APP_API_BASE_URL=http://localhost:8000
# Build the project (validates everything compiles)
npm run build
# Return to root
cd ..
```
### **Step 4: Start the Application**
**Terminal 1 - Backend:**
```bash
cd backend
python app.py
```
**Terminal 2 - Frontend:**
```bash
cd frontend
npm start
```
### **Step 5: Access the Application**
- **Frontend UI**: http://localhost:3000
- **Backend API Docs**: http://localhost:8000/api/docs
- **Health Check**: http://localhost:8000/health
## 🐛 **Troubleshooting Common Issues**
### **Issue 1: "CopilotSidebar is not exported" Error**
**Cause**: Did not run `npm install` in frontend directory
**Fix:**
```bash
cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build
npm start
```
### **Issue 2: "Module not found" (Python)**
**Cause**: Did not install Python dependencies or activate virtual environment
**Fix:**
```bash
cd backend
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
```
### **Issue 3: "CORS Error" in Browser**
**Cause**: Backend not running or frontend connecting to wrong URL
**Fix:**
1. Ensure backend is running on `http://localhost:8000`
2. Check `frontend/.env` has `REACT_APP_API_BASE_URL=http://localhost:8000`
3. Restart both frontend and backend
### **Issue 4: "Clerk Publishable Key Missing"**
**Cause**: Frontend `.env` file not configured
**Fix:**
```bash
cd frontend
# Edit .env file and add:
# REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_xxx...
```
### **Issue 5: "Database Error" or "Subscription Plans Not Found"**
**Cause**: Database tables not created
**Fix:**
```bash
cd backend
python scripts/create_subscription_tables.py
python scripts/cleanup_alpha_plans.py
```
### **Issue 6: "Port Already in Use"**
**Backend (8000):**
```bash
# Find and kill process using port 8000
# Windows:
netstat -ano | findstr :8000
taskkill /PID <process_id> /F
# macOS/Linux:
lsof -ti:8000 | xargs kill -9
```
**Frontend (3000):**
```bash
# Find and kill process using port 3000
# Windows:
netstat -ano | findstr :3000
taskkill /PID <process_id> /F
# macOS/Linux:
lsof -ti:3000 | xargs kill -9
```
## ✅ **Verification Checklist**
After setup, verify:
- [ ] Backend health check returns 200 OK: `curl http://localhost:8000/health`
- [ ] Frontend loads without errors
- [ ] Can sign in with Clerk authentication
- [ ] Pricing page loads with 4 subscription tiers (Free, Basic, Pro, Enterprise)
- [ ] Can navigate to onboarding after selecting a plan
## 📚 **Environment Variables Required**
### **Backend (.env)**
```bash
# Required for authentication
CLERK_SECRET_KEY=sk_test_xxx...
CLERK_PUBLISHABLE_KEY=pk_test_xxx...
# Optional (can be provided via UI in Step 1 of onboarding)
GEMINI_API_KEY=AIzaSy...
EXA_API_KEY=xxx...
COPILOTKIT_API_KEY=xxx...
# Development settings
DISABLE_AUTH=false
DEPLOY_ENV=local
```
### **Frontend (.env)**
```bash
# Required
REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_xxx...
# Optional
REACT_APP_API_BASE_URL=http://localhost:8000
REACT_APP_COPILOTKIT_API_KEY=xxx...
```
## 🎯 **First-Time User Flow**
After setup:
1. **Start both servers** (backend + frontend)
2. **Navigate to** http://localhost:3000
3. **Sign in** with Clerk
4. **Select subscription plan** (Free or Basic for alpha testing)
5. **Complete onboarding** (6 steps):
- Step 1: API Keys
- Step 2: Website Analysis
- Step 3: Competitor Research
- Step 4: Persona Generation
- Step 5: Research Preferences
- Step 6: Final Review
6. **Access dashboard** with all features unlocked
## 🆘 **Getting Help**
If you encounter issues:
1. **Check logs**: Both terminal windows show detailed error messages
2. **GitHub Issues**: https://github.com/AJaySi/ALwrity/issues
3. **Documentation**: See `docs/` directory for detailed guides
4. **Common Issues**: See `docs/GITHUB_ISSUE_291_FIX.md` for CopilotSidebar error
## 📖 **Additional Documentation**
- **Onboarding System**: `docs/API_KEY_MANAGEMENT_ARCHITECTURE.md`
- **Subscription System**: `docs/Billing_Subscription/SUBSCRIPTION_IMPLEMENTATION_SUMMARY.md`
- **Deployment Guide**: `DEPLOY_ENV_REFERENCE.md`
- **API Key Management**: `docs/API_KEY_INJECTION_EXPLAINED.md`
---
**Need help? Open an issue on GitHub: https://github.com/AJaySi/ALwrity/issues**

171
.github/TROUBLESHOOTING.md vendored Normal file
View File

@@ -0,0 +1,171 @@
# Fix for GitHub Issue #291: CopilotSidebar Import Error
## 🐛 **Issue**
User encounters error: `'CopilotSidebar' is not exported from '@copilotkit/react-ui'`
## 🔍 **Root Cause**
The user **did not run `npm install`** after cloning/pulling the repository, causing missing or outdated CopilotKit dependencies.
## ✅ **Solution**
### **Step 1: Clean Install Dependencies**
```bash
cd frontend
rm -rf node_modules package-lock.json
npm install
```
**For Windows PowerShell:**
```powershell
cd frontend
Remove-Item -Recurse -Force node_modules, package-lock.json -ErrorAction SilentlyContinue
npm install
```
### **Step 2: Verify CopilotKit Installation**
Check that the following packages are installed:
```bash
npm list @copilotkit/react-core @copilotkit/react-ui @copilotkit/shared
```
Expected output:
```
@copilotkit/react-core@1.10.3
@copilotkit/react-ui@1.10.3
@copilotkit/shared@1.10.3
```
### **Step 3: Build the Frontend**
```bash
npm run build
```
### **Step 4: Start Development Server**
```bash
npm start
```
## 📋 **Complete Setup Instructions for New Users**
### **Frontend Setup:**
```bash
# Navigate to frontend directory
cd frontend
# Install dependencies
npm install
# Create .env file from template
cp env_template.txt .env
# Add your environment variables to .env:
# REACT_APP_CLERK_PUBLISHABLE_KEY=<your-clerk-key>
# REACT_APP_COPILOTKIT_API_KEY=<your-copilotkit-key>
# Build the project
npm run build
# Start development server
npm start
```
### **Backend Setup:**
```bash
# Navigate to backend directory
cd backend
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Create .env file from template
cp env_template.txt .env
# Add your environment variables to .env
# Initialize database tables
python scripts/create_subscription_tables.py
# Start backend server
python app.py
```
## 🎯 **Why This Happens**
1. **Missing `node_modules`**: Package dependencies not installed
2. **Outdated packages**: Old version of CopilotKit that doesn't export `CopilotSidebar`
3. **Skipped installation**: Running `npm start` before `npm install`
## ✅ **Verification**
After following the steps above, you should see:
- ✅ No import errors for `CopilotSidebar`
- ✅ Frontend compiles successfully
- ✅ Development server starts on `http://localhost:3000`
- ✅ Backend API accessible on `http://localhost:8000`
## 📚 **Reference**
- [CopilotKit UI Components Documentation](https://docs.copilotkit.ai/crewai-crews/custom-look-and-feel/built-in-ui-components)
- CopilotKit exports: `CopilotChat`, `CopilotSidebar`, `CopilotPopup` from `@copilotkit/react-ui`
## 🚨 **Common Mistakes to Avoid**
1. ❌ Running `npm start` without `npm install` first
2. ❌ Using outdated `package-lock.json`
3. ❌ Missing environment variables in `.env` files
4. ❌ Not running database migration scripts for backend
## 💡 **Pro Tip**
Always run these commands after pulling new code:
```bash
# Frontend
cd frontend && npm install && npm run build
# Backend
cd backend && pip install -r requirements.txt
```
---
## 🐛 **Issue: "Failed to process subscription" (500 Error)**
**Symptoms:**
- User selects Free or Basic plan on Pricing page
- Clicks "Subscribe to [Plan]"
- Gets error: "Failed to process subscription"
- Backend logs: `name 'UsageStatus' is not defined`
**Root Cause:**
Missing `UsageStatus` import in `backend/api/subscription_api.py`
**Fix:**
✅ Already fixed in latest version. Update to latest code:
```bash
git pull origin main
cd backend
python app.py # Restart backend
```
**Verify Fix:**
Check that `backend/api/subscription_api.py` line 18 includes:
```python
from models.subscription_models import (
..., UsageStatus # <-- This should be present
)
```

103
.github/setup_alwrity.bat vendored Normal file
View File

@@ -0,0 +1,103 @@
@echo off
REM ALwrity Complete Setup Script for Windows
REM This script sets up both frontend and backend for local development
echo ================================
echo 🚀 ALwrity Setup Script (Windows)
echo ================================
echo.
REM Check if we're in the project root
if not exist "frontend\" (
echo ❌ Error: frontend directory not found
echo Please navigate to the AI-Writer directory and try again.
exit /b 1
)
if not exist "backend\" (
echo ❌ Error: backend directory not found
echo Please navigate to the AI-Writer directory and try again.
exit /b 1
)
echo 📋 Step 1: Setting up Backend
echo --------------------------------
REM Setup Backend
cd backend
echo Creating Python virtual environment...
python -m venv .venv
echo Activating virtual environment...
call .venv\Scripts\activate.bat
echo Installing Python dependencies...
pip install -r requirements.txt
REM Create .env file if it doesn't exist
if not exist ".env" (
echo Creating .env file from template...
copy env_template.txt .env
echo ⚠️ Please update backend\.env with your API keys
)
echo Creating subscription tables...
python scripts\create_subscription_tables.py 2>nul || echo ⚠️ Subscription tables may already exist
echo Updating subscription plans...
python scripts\cleanup_alpha_plans.py 2>nul || echo ⚠️ Plans may already be updated
cd ..
echo ✅ Backend setup complete!
echo.
echo 📋 Step 2: Setting up Frontend
echo --------------------------------
REM Setup Frontend
cd frontend
REM Clean install
if exist "node_modules\" (
echo Cleaning old node_modules...
rmdir /s /q node_modules 2>nul
del package-lock.json 2>nul
)
echo Installing Node.js dependencies (this may take a few minutes)...
call npm install
REM Create .env file if it doesn't exist
if not exist ".env" (
echo Creating .env file from template...
copy env_template.txt .env
echo ⚠️ Please update frontend\.env with your environment variables
)
echo Building frontend...
call npm run build
cd ..
echo.
echo ================================
echo 🎉 ALwrity Setup Complete!
echo ================================
echo.
echo Next steps:
echo 1. Update backend\.env with your API keys (Clerk, Gemini, etc.)
echo 2. Update frontend\.env with your Clerk publishable key
echo.
echo To start the application:
echo Backend: cd backend ^&^& python app.py
echo Frontend: cd frontend ^&^& npm start
echo.
echo Access points:
echo Frontend: http://localhost:3000
echo Backend API: http://localhost:8000/api/docs
echo.
echo Happy coding! 🚀
pause

105
.github/setup_alwrity.sh vendored Normal file
View File

@@ -0,0 +1,105 @@
#!/bin/bash
# ALwrity Complete Setup Script
# This script sets up both frontend and backend for local development
set -e # Exit on error
echo "🚀 ALwrity Setup Script"
echo "================================"
echo ""
# Color codes for output
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m' # No Color
# Check if we're in the project root
if [ ! -d "frontend" ] || [ ! -d "backend" ]; then
echo -e "${RED}❌ Error: This script must be run from the project root directory${NC}"
echo "Please navigate to the AI-Writer directory and try again."
exit 1
fi
echo -e "${YELLOW}📋 Step 1: Setting up Backend${NC}"
echo "--------------------------------"
# Setup Backend
cd backend
echo "Creating Python virtual environment..."
python -m venv .venv || python3 -m venv .venv
echo "Activating virtual environment..."
source .venv/bin/activate || source .venv/Scripts/activate
echo "Installing Python dependencies..."
pip install -r requirements.txt
# Create .env file if it doesn't exist
if [ ! -f ".env" ]; then
echo "Creating .env file from template..."
cp env_template.txt .env
echo -e "${YELLOW}⚠️ Please update backend/.env with your API keys${NC}"
fi
echo "Creating subscription tables..."
python scripts/create_subscription_tables.py || echo -e "${YELLOW}⚠️ Subscription tables may already exist${NC}"
echo "Updating subscription plans..."
python scripts/cleanup_alpha_plans.py || echo -e "${YELLOW}⚠️ Plans may already be updated${NC}"
cd ..
echo -e "${GREEN}✅ Backend setup complete!${NC}"
echo ""
echo -e "${YELLOW}📋 Step 2: Setting up Frontend${NC}"
echo "--------------------------------"
# Setup Frontend
cd frontend
# Clean install
if [ -d "node_modules" ]; then
echo "Cleaning old node_modules..."
rm -rf node_modules package-lock.json
fi
echo "Installing Node.js dependencies (this may take a few minutes)..."
npm install
# Create .env file if it doesn't exist
if [ ! -f ".env" ]; then
echo "Creating .env file from template..."
cp env_template.txt .env
echo -e "${YELLOW}⚠️ Please update frontend/.env with your environment variables${NC}"
fi
echo "Building frontend..."
npm run build
cd ..
echo -e "${GREEN}✅ Frontend setup complete!${NC}"
echo ""
echo "================================"
echo -e "${GREEN}🎉 ALwrity Setup Complete!${NC}"
echo "================================"
echo ""
echo "Next steps:"
echo "1. Update backend/.env with your API keys (Clerk, Gemini, etc.)"
echo "2. Update frontend/.env with your Clerk publishable key"
echo ""
echo "To start the application:"
echo " Backend: cd backend && python app.py"
echo " Frontend: cd frontend && npm start"
echo ""
echo "Access points:"
echo " Frontend: http://localhost:3000"
echo " Backend API: http://localhost:8000/api/docs"
echo ""
echo -e "${GREEN}Happy coding! 🚀${NC}"