ALwrity Version 0.5.1 (Fastapi + React)
This commit is contained in:
ajaysi
@@ -1,524 +0,0 @@
|
||||
# ALwrity API Documentation
|
||||
|
||||
## 🚀 **FastAPI Backend Overview**
|
||||
|
||||
ALwrity's backend is built with **FastAPI**, providing high-performance, async API endpoints with automatic OpenAPI documentation, comprehensive validation, and enterprise-ready architecture.
|
||||
|
||||
---
|
||||
|
||||
## 📊 **API Endpoints Summary**
|
||||
|
||||
### **Total Endpoints: 31**
|
||||
- **Core Onboarding**: 12 endpoints
|
||||
- **Component Logic**: 19 endpoints (including new Style Detection)
|
||||
- **Health & Status**: 2 endpoints
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Core API Endpoints**
|
||||
|
||||
### **Health & Status**
|
||||
```python
|
||||
GET /health # Health check
|
||||
GET /api/status # Application status
|
||||
```
|
||||
|
||||
### **Onboarding Endpoints (12 Total)**
|
||||
```python
|
||||
# Progress Management
|
||||
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
|
||||
|
||||
# API Key Management
|
||||
GET /api/onboarding/api-keys # Get API keys
|
||||
POST /api/onboarding/api-keys # Save API key
|
||||
|
||||
# Resume Functionality
|
||||
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 (19 Total)**
|
||||
|
||||
#### **AI Research Endpoints (4)**
|
||||
```python
|
||||
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)**
|
||||
```python
|
||||
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)**
|
||||
```python
|
||||
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
|
||||
```
|
||||
|
||||
#### **Style Detection Endpoints (4) - NEW**
|
||||
```python
|
||||
POST /api/onboarding/style-detection/analyze # Analyze content style
|
||||
POST /api/onboarding/style-detection/crawl # Crawl website content
|
||||
POST /api/onboarding/style-detection/complete # Complete workflow
|
||||
GET /api/onboarding/style-detection/configuration-options # Get configuration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **Backend Architecture**
|
||||
|
||||
### **Project Structure**
|
||||
```
|
||||
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
|
||||
│ ├── style_detection_logic.py # NEW
|
||||
│ └── web_crawler_logic.py # NEW
|
||||
├── models/
|
||||
│ ├── onboarding.py # Database models
|
||||
│ └── component_logic.py # Component logic models
|
||||
└── requirements.txt # Python dependencies
|
||||
```
|
||||
|
||||
### **Service Architecture**
|
||||
```python
|
||||
# Core Services
|
||||
backend/services/
|
||||
├── api_key_manager.py # API key management (migrated from legacy)
|
||||
├── validation.py # Validation services (enhanced from legacy)
|
||||
└── component_logic/ # Component logic services (new)
|
||||
├── ai_research_logic.py # AI Research business logic
|
||||
├── personalization_logic.py # Personalization business logic
|
||||
├── research_utilities.py # Research utilities business logic
|
||||
├── style_detection_logic.py # Style Detection business logic (NEW)
|
||||
└── web_crawler_logic.py # Web Crawler business logic (NEW)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Data Models**
|
||||
|
||||
### **Core Models (Migrated from Legacy)**
|
||||
```python
|
||||
# Onboarding Models
|
||||
class OnboardingStatus(BaseModel):
|
||||
onboarding_required: bool
|
||||
onboarding_complete: bool
|
||||
current_step: Optional[int] = None
|
||||
|
||||
class OnboardingProgress(BaseModel):
|
||||
steps_completed: List[int]
|
||||
current_step: int
|
||||
total_steps: int = 6
|
||||
|
||||
class APIKeyData(BaseModel):
|
||||
provider: str
|
||||
key: str
|
||||
is_valid: bool = False
|
||||
|
||||
class StepData(BaseModel):
|
||||
step_number: int
|
||||
completed: bool
|
||||
data: Optional[Dict[str, Any]] = None
|
||||
```
|
||||
|
||||
### **Component Logic Models (New)**
|
||||
```python
|
||||
# AI Research Models
|
||||
class UserInfoRequest(BaseModel):
|
||||
full_name: str
|
||||
email: str
|
||||
company: str
|
||||
role: str
|
||||
|
||||
class ResearchPreferencesRequest(BaseModel):
|
||||
research_depth: str
|
||||
content_types: List[str]
|
||||
auto_research: bool
|
||||
|
||||
# Personalization Models
|
||||
class ContentStyleRequest(BaseModel):
|
||||
writing_style: str
|
||||
tone: str
|
||||
content_length: str
|
||||
|
||||
class BrandVoiceRequest(BaseModel):
|
||||
personality_traits: List[str]
|
||||
voice_description: Optional[str]
|
||||
keywords: Optional[str]
|
||||
|
||||
class PersonalizationSettingsRequest(BaseModel):
|
||||
content_style: ContentStyleRequest
|
||||
brand_voice: BrandVoiceRequest
|
||||
advanced_settings: Dict[str, Any]
|
||||
|
||||
# Research Utilities Models
|
||||
class ResearchTopicRequest(BaseModel):
|
||||
topic: str
|
||||
providers: List[str]
|
||||
depth: str = "standard"
|
||||
|
||||
class ResearchResultResponse(BaseModel):
|
||||
summary: str
|
||||
insights: List[str]
|
||||
trends: List[str]
|
||||
metadata: Dict[str, Any]
|
||||
|
||||
# Style Detection Models (NEW)
|
||||
class StyleAnalysisRequest(BaseModel):
|
||||
content: Dict[str, Any]
|
||||
analysis_type: str = "comprehensive"
|
||||
|
||||
class StyleAnalysisResponse(BaseModel):
|
||||
success: bool
|
||||
analysis: Optional[Dict[str, Any]] = None
|
||||
patterns: Optional[Dict[str, Any]] = None
|
||||
guidelines: Optional[Dict[str, Any]] = None
|
||||
error: Optional[str] = None
|
||||
timestamp: str
|
||||
|
||||
class WebCrawlRequest(BaseModel):
|
||||
url: Optional[str] = None
|
||||
text_sample: Optional[str] = None
|
||||
|
||||
class WebCrawlResponse(BaseModel):
|
||||
success: bool
|
||||
content: Optional[Dict[str, Any]] = None
|
||||
metrics: Optional[Dict[str, Any]] = None
|
||||
error: Optional[str] = None
|
||||
timestamp: str
|
||||
|
||||
class StyleDetectionRequest(BaseModel):
|
||||
url: Optional[str] = None
|
||||
text_sample: Optional[str] = None
|
||||
include_patterns: bool = True
|
||||
include_guidelines: bool = True
|
||||
|
||||
class StyleDetectionResponse(BaseModel):
|
||||
success: bool
|
||||
crawl_result: Optional[Dict[str, Any]] = None
|
||||
style_analysis: Optional[Dict[str, Any]] = None
|
||||
style_patterns: Optional[Dict[str, Any]] = None
|
||||
style_guidelines: Optional[Dict[str, Any]] = None
|
||||
error: Optional[str] = None
|
||||
timestamp: str
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **Style Detection Features (NEW)**
|
||||
|
||||
### **Core Functionality**
|
||||
- **Content Analysis**: AI-powered analysis of writing style, tone, and characteristics
|
||||
- **Web Crawling**: Extract content from websites for style analysis
|
||||
- **Text Processing**: Analyze provided text samples
|
||||
- **Pattern Recognition**: Identify writing patterns and rhetorical devices
|
||||
- **Guidelines Generation**: Create personalized content guidelines
|
||||
|
||||
### **Analysis Capabilities**
|
||||
```python
|
||||
# Writing Style Analysis
|
||||
{
|
||||
"writing_style": {
|
||||
"tone": "formal/casual/technical/etc",
|
||||
"voice": "active/passive",
|
||||
"complexity": "simple/moderate/complex",
|
||||
"engagement_level": "low/medium/high"
|
||||
},
|
||||
"content_characteristics": {
|
||||
"sentence_structure": "description",
|
||||
"vocabulary_level": "basic/intermediate/advanced",
|
||||
"paragraph_organization": "description",
|
||||
"content_flow": "description"
|
||||
},
|
||||
"target_audience": {
|
||||
"demographics": ["list"],
|
||||
"expertise_level": "beginner/intermediate/advanced",
|
||||
"industry_focus": "primary industry",
|
||||
"geographic_focus": "primary region"
|
||||
},
|
||||
"recommended_settings": {
|
||||
"writing_tone": "recommended tone",
|
||||
"target_audience": "recommended audience",
|
||||
"content_type": "recommended type",
|
||||
"creativity_level": "low/medium/high",
|
||||
"geographic_location": "recommended location"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **Web Crawling Features**
|
||||
- **Content Extraction**: Extract main content, titles, descriptions
|
||||
- **Metadata Analysis**: Analyze meta tags, headings, links
|
||||
- **Metrics Calculation**: Word count, readability, content density
|
||||
- **Error Handling**: Comprehensive error handling for failed crawls
|
||||
|
||||
### **Integration Benefits**
|
||||
- **Personalization**: Enhanced personalization based on style analysis
|
||||
- **Content Generation**: Better content generation matching user's style
|
||||
- **Brand Consistency**: Maintain brand voice across all content
|
||||
- **User Experience**: Improved user experience with style-aware features
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Technical Implementation**
|
||||
|
||||
### **FastAPI Features Used**
|
||||
- **Async/Await**: All endpoints are async for better performance
|
||||
- **Pydantic Validation**: Automatic request/response validation
|
||||
- **OpenAPI Documentation**: Auto-generated API docs
|
||||
- **CORS Configuration**: Cross-origin resource sharing
|
||||
- **Error Handling**: Comprehensive error management
|
||||
- **Logging**: Detailed request/response logging
|
||||
|
||||
### **Database Integration**
|
||||
```python
|
||||
# SQLAlchemy Models
|
||||
class OnboardingStatus(Base):
|
||||
__tablename__ = "onboarding_status"
|
||||
id = Column(Integer, primary_key=True)
|
||||
onboarding_required = Column(Boolean, default=True)
|
||||
onboarding_complete = Column(Boolean, default=False)
|
||||
current_step = Column(Integer, default=1)
|
||||
|
||||
class APIKey(Base):
|
||||
__tablename__ = "api_keys"
|
||||
id = Column(Integer, primary_key=True)
|
||||
provider = Column(String, nullable=False)
|
||||
key = Column(String, nullable=False)
|
||||
is_valid = Column(Boolean, default=False)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
```
|
||||
|
||||
### **Validation Logic**
|
||||
```python
|
||||
# Provider-specific validation
|
||||
def validate_openai_key(api_key: str) -> bool:
|
||||
return api_key.startswith("sk-") and len(api_key) >= 20
|
||||
|
||||
def validate_gemini_key(api_key: str) -> bool:
|
||||
return api_key.startswith("AIza") and len(api_key) >= 30
|
||||
|
||||
# Comprehensive validation
|
||||
def validate_all_api_keys(api_keys: Dict[str, str]) -> Dict[str, Any]:
|
||||
results = {}
|
||||
for provider, key in api_keys.items():
|
||||
results[provider] = {
|
||||
"valid": validate_provider_key(provider, key),
|
||||
"message": get_validation_message(provider, key)
|
||||
}
|
||||
return results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 **Testing & Quality Assurance**
|
||||
|
||||
### **API Testing**
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# Onboarding status
|
||||
curl http://localhost:8000/api/onboarding/status
|
||||
|
||||
# API keys
|
||||
curl http://localhost:8000/api/onboarding/api-keys
|
||||
|
||||
# Component logic
|
||||
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"}'
|
||||
|
||||
# Style Detection (NEW)
|
||||
curl -X POST http://localhost:8000/api/onboarding/style-detection/complete \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"url": "https://example.com", "include_patterns": true, "include_guidelines": true}'
|
||||
```
|
||||
|
||||
### **Documentation Access**
|
||||
- **Swagger UI**: http://localhost:8000/docs
|
||||
- **ReDoc**: http://localhost:8000/redoc
|
||||
- **OpenAPI JSON**: http://localhost:8000/openapi.json
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Performance Features**
|
||||
|
||||
### **Async Processing**
|
||||
```python
|
||||
@app.post("/api/onboarding/research/process-topic")
|
||||
async def process_research_topic(request: ResearchTopicRequest):
|
||||
"""Process research topic asynchronously"""
|
||||
try:
|
||||
# Async research processing
|
||||
results = await research_utilities.research_topic(
|
||||
request.topic,
|
||||
request.providers
|
||||
)
|
||||
return ResearchResultResponse(**results)
|
||||
except Exception as e:
|
||||
raise HTTPException(status_code=500, detail=str(e))
|
||||
```
|
||||
|
||||
### **Caching Strategy**
|
||||
```python
|
||||
# Redis caching for frequently accessed data
|
||||
@lru_cache(maxsize=128)
|
||||
def get_provider_setup_info(provider: str) -> Dict[str, Any]:
|
||||
"""Cache provider setup information"""
|
||||
return PROVIDER_SETUP_INSTRUCTIONS.get(provider, {})
|
||||
```
|
||||
|
||||
### **Error Handling**
|
||||
```python
|
||||
# Comprehensive error handling
|
||||
@app.exception_handler(ValidationError)
|
||||
async def validation_exception_handler(request: Request, exc: ValidationError):
|
||||
return JSONResponse(
|
||||
status_code=422,
|
||||
content={"detail": "Validation error", "errors": exc.errors()}
|
||||
)
|
||||
|
||||
@app.exception_handler(Exception)
|
||||
async def general_exception_handler(request: Request, exc: Exception):
|
||||
return JSONResponse(
|
||||
status_code=500,
|
||||
content={"detail": "Internal server error"}
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 **Security Features**
|
||||
|
||||
### **API Key Management**
|
||||
- **Encryption**: API keys are encrypted at rest
|
||||
- **Validation**: Real-time validation of API keys
|
||||
- **Masking**: Keys are masked in responses
|
||||
- **Rotation**: Support for key rotation (future feature)
|
||||
|
||||
### **Input Validation**
|
||||
```python
|
||||
# Comprehensive input validation
|
||||
def validate_email(email: str) -> bool:
|
||||
"""Validate email format"""
|
||||
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
|
||||
return bool(re.match(pattern, email))
|
||||
|
||||
def validate_url(url: str) -> bool:
|
||||
"""Validate URL format"""
|
||||
try:
|
||||
result = urlparse(url)
|
||||
return all([result.scheme, result.netloc])
|
||||
except:
|
||||
return False
|
||||
```
|
||||
|
||||
### **CORS Configuration**
|
||||
```python
|
||||
# CORS settings for frontend integration
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
|
||||
allow_credentials=True,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Monitoring & Logging**
|
||||
|
||||
### **Request Logging**
|
||||
```python
|
||||
# Comprehensive request logging
|
||||
@app.middleware("http")
|
||||
async def log_requests(request: Request, call_next):
|
||||
start_time = time.time()
|
||||
response = await call_next(request)
|
||||
process_time = time.time() - start_time
|
||||
|
||||
logger.info(
|
||||
f"{request.method} {request.url.path} - "
|
||||
f"Status: {response.status_code} - "
|
||||
f"Time: {process_time:.3f}s"
|
||||
)
|
||||
return response
|
||||
```
|
||||
|
||||
### **Performance Metrics**
|
||||
- **Response Time**: Average < 100ms for most endpoints
|
||||
- **Throughput**: 1000+ requests/second
|
||||
- **Error Rate**: < 0.1% for production endpoints
|
||||
- **Uptime**: 99.9% availability
|
||||
|
||||
---
|
||||
|
||||
## 🔮 **Future Enhancements**
|
||||
|
||||
### **Planned API Features**
|
||||
1. **Authentication**: JWT token-based authentication
|
||||
2. **Rate Limiting**: API rate limiting and throttling
|
||||
3. **Webhooks**: Real-time notifications
|
||||
4. **GraphQL**: Alternative to REST for complex queries
|
||||
5. **WebSocket**: Real-time communication
|
||||
|
||||
### **AI Writers Integration**
|
||||
1. **AI Writer Endpoints**: Content generation APIs
|
||||
2. **SEO Tools**: SEO analysis and optimization
|
||||
3. **Analytics**: Usage analytics and reporting
|
||||
4. **Chatbot**: AI-powered customer support
|
||||
|
||||
### **Style Detection Enhancements**
|
||||
1. **Advanced Pattern Recognition**: More sophisticated writing pattern analysis
|
||||
2. **Multi-language Support**: Style analysis for multiple languages
|
||||
3. **Industry-specific Analysis**: Specialized analysis for different industries
|
||||
4. **Real-time Style Adaptation**: Dynamic style adjustment during content generation
|
||||
|
||||
---
|
||||
|
||||
## 📚 **API Documentation Access**
|
||||
|
||||
### **Development**
|
||||
- **Swagger UI**: http://localhost:8000/docs
|
||||
- **ReDoc**: http://localhost:8000/redoc
|
||||
- **OpenAPI JSON**: http://localhost:8000/openapi.json
|
||||
|
||||
### **Production**
|
||||
- **API Documentation**: https://api.alwrity.com/docs
|
||||
- **Health Check**: https://api.alwrity.com/health
|
||||
- **Status Page**: https://status.alwrity.com
|
||||
|
||||
---
|
||||
|
||||
**This API documentation provides comprehensive details about ALwrity's FastAPI backend implementation, including all endpoints, data models, security features, and performance optimizations. The new Style Detection functionality enhances the platform's personalization capabilities significantly.**
|
||||
@@ -1,325 +0,0 @@
|
||||
# Comprehensive SEO Analyzer Integration
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the comprehensive SEO analyzer that combines all features from the three original modules (CGPT SEO Analyzer, On-Page SEO Analyzer, and WebURL SEO Checker) into a single, powerful solution for the React SEO Dashboard.
|
||||
|
||||
## Combined Features Analysis
|
||||
|
||||
### Original Modules Features:
|
||||
|
||||
#### 1. CGPT SEO Analyzer
|
||||
- ✅ Keyword density analysis
|
||||
- ✅ Keyword presence in title, image alt text
|
||||
- ✅ Headings analysis
|
||||
- ✅ Internal/external links counting
|
||||
- ✅ Readability scoring
|
||||
- ✅ Spelling/grammar error detection
|
||||
- ✅ Basic SEO scoring
|
||||
- ✅ Suggestions for improvement
|
||||
|
||||
#### 2. On-Page SEO Analyzer
|
||||
- ✅ Meta data extraction (title, description, robots, viewport, charset)
|
||||
- ✅ Headings structure analysis
|
||||
- ✅ Content analysis (text length, word count)
|
||||
- ✅ Image analysis with alt text
|
||||
- ✅ Link analysis (internal/external)
|
||||
- ✅ Schema markup detection
|
||||
- ✅ Open Graph and social tags
|
||||
- ✅ Canonical and hreflang detection
|
||||
- ✅ HTTP headers analysis
|
||||
- ✅ Mobile usability
|
||||
- ✅ Page speed analysis
|
||||
- ✅ Enhanced keyword density with advertools
|
||||
- ✅ URL structure analysis
|
||||
- ✅ CTA detection
|
||||
|
||||
#### 3. WebURL SEO Checker
|
||||
- ✅ HTTPS security check
|
||||
- ✅ URL length analysis
|
||||
- ✅ Hyphen usage check
|
||||
- ✅ File extension analysis
|
||||
- ✅ HTTP headers analysis
|
||||
- ✅ Robots.txt and sitemap detection
|
||||
- ✅ Enhanced URL structure analysis
|
||||
- ✅ Security headers analysis
|
||||
|
||||
## Comprehensive SEO Analyzer Features
|
||||
|
||||
### 🎯 Core Analysis Categories
|
||||
|
||||
#### 1. URL Structure & Security (20% weight)
|
||||
- **HTTPS Implementation**: Critical security and SEO factor
|
||||
- **URL Length**: Optimal length for user experience and SEO
|
||||
- **URL Depth**: Proper site structure hierarchy
|
||||
- **Special Characters**: Clean, readable URLs
|
||||
- **File Extensions**: Proper content type indication
|
||||
- **Security Headers**: X-Frame-Options, CSP, HSTS, etc.
|
||||
|
||||
#### 2. Meta Data & Technical SEO (25% weight)
|
||||
- **Title Tags**: Length, keyword presence, uniqueness
|
||||
- **Meta Descriptions**: Length, compelling content, keyword inclusion
|
||||
- **Viewport & Mobile**: Mobile-friendly meta tags
|
||||
- **Charset Declaration**: Proper encoding
|
||||
- **Schema Markup**: Structured data implementation
|
||||
- **Canonical Tags**: Duplicate content prevention
|
||||
- **Hreflang Tags**: International SEO
|
||||
- **Open Graph & Social**: Social media optimization
|
||||
|
||||
#### 3. Content Quality & Structure (25% weight)
|
||||
- **Content Length**: Minimum 300 words for comprehensive coverage
|
||||
- **Headings Structure**: H1, H2, H3 hierarchy
|
||||
- **Image Optimization**: Alt text, file sizes, formats
|
||||
- **Internal Linking**: Site structure and user navigation
|
||||
- **External Linking**: Authority and relevance
|
||||
- **Readability**: Flesch Reading Ease score
|
||||
- **Spelling & Grammar**: Content quality indicators
|
||||
|
||||
#### 4. Keyword Analysis (15% weight)
|
||||
- **Keyword Density**: Optimal 1-3% range
|
||||
- **Keyword Placement**: Title, headings, alt text, meta description
|
||||
- **Keyword Stuffing Detection**: Over-optimization prevention
|
||||
- **Long-tail Keywords**: Natural language optimization
|
||||
|
||||
#### 5. Technical Performance (10% weight)
|
||||
- **Page Load Speed**: Under 2 seconds optimal
|
||||
- **Compression**: GZIP/Brotli implementation
|
||||
- **Caching**: Proper cache headers
|
||||
- **HTTP Status Codes**: Proper response codes
|
||||
|
||||
#### 6. Accessibility & UX (5% weight)
|
||||
- **Alt Text**: Image accessibility
|
||||
- **Form Labels**: Form accessibility
|
||||
- **ARIA Attributes**: Screen reader support
|
||||
- **Mobile Responsiveness**: Mobile-friendly design
|
||||
- **Call-to-Actions**: User engagement elements
|
||||
- **Contact Information**: User trust signals
|
||||
|
||||
## Data Points & Actionable Insights
|
||||
|
||||
### 📊 Key Metrics for Dashboard
|
||||
|
||||
#### Overall Health Score (0-100)
|
||||
- **90-100**: Excellent - Minimal improvements needed
|
||||
- **70-89**: Good - Some optimizations recommended
|
||||
- **50-69**: Needs Improvement - Several areas need attention
|
||||
- **0-49**: Poor - Significant improvements required
|
||||
|
||||
#### Category Scores
|
||||
1. **URL Structure Score**: Security and technical foundation
|
||||
2. **Meta Data Score**: On-page SEO fundamentals
|
||||
3. **Content Score**: Content quality and structure
|
||||
4. **Technical SEO Score**: Advanced technical elements
|
||||
5. **Performance Score**: Speed and optimization
|
||||
6. **Accessibility Score**: User experience and compliance
|
||||
7. **User Experience Score**: Engagement and usability
|
||||
8. **Security Score**: Protection and trust signals
|
||||
|
||||
### 🎯 Actionable Insights for Non-Technical Users
|
||||
|
||||
#### Critical Issues (Must Fix)
|
||||
- 🚨 **Not using HTTPS**: "Your website is not secure. This severely hurts your search rankings and user trust."
|
||||
- 🚨 **Missing title tag**: "Your page has no title. This is critical for SEO and user experience."
|
||||
- 🚨 **Missing H1 tag**: "Your page lacks a main heading. This confuses search engines and users."
|
||||
- 🚨 **Content too short**: "Your content is too brief. Aim for at least 300 words for better rankings."
|
||||
|
||||
#### Warnings (Should Fix)
|
||||
- ⚠️ **Title too long/short**: "Your page title should be 30-60 characters for optimal display."
|
||||
- ⚠️ **Missing meta description**: "Add a compelling description to improve click-through rates."
|
||||
- ⚠️ **Images missing alt text**: "Add descriptions to images for better accessibility and SEO."
|
||||
- ⚠️ **No internal links**: "Add links to other pages on your site to improve navigation."
|
||||
|
||||
#### Recommendations (Could Improve)
|
||||
- 💡 **Add schema markup**: "Help search engines understand your content better."
|
||||
- 💡 **Optimize page speed**: "Faster pages rank better and provide better user experience."
|
||||
- 💡 **Add social media tags**: "Improve how your content appears when shared online."
|
||||
- 💡 **Create XML sitemap**: "Help search engines discover all your pages."
|
||||
|
||||
## Enhanced Prompts for Better Results
|
||||
|
||||
### 🎨 User-Friendly Language
|
||||
|
||||
The analyzer uses enhanced prompts to make technical SEO concepts accessible to non-technical users:
|
||||
|
||||
```python
|
||||
ENHANCED_PROMPTS = {
|
||||
"critical_issue": "🚨 CRITICAL: This issue is severely impacting your SEO performance and must be fixed immediately.",
|
||||
"warning": "⚠️ WARNING: This could be improved to boost your search rankings.",
|
||||
"recommendation": "💡 RECOMMENDATION: Implement this to improve your SEO score.",
|
||||
"excellent": "🎉 EXCELLENT: Your SEO is performing very well in this area!",
|
||||
"good": "✅ GOOD: Your SEO is performing well, with room for minor improvements.",
|
||||
"needs_improvement": "🔧 NEEDS IMPROVEMENT: Several areas need attention to boost your SEO.",
|
||||
"poor": "❌ POOR: Significant improvements needed across multiple areas."
|
||||
}
|
||||
```
|
||||
|
||||
### 📝 Example Enhanced Output
|
||||
|
||||
Instead of: "Missing title tag"
|
||||
The analyzer outputs: "🚨 CRITICAL: This issue is severely impacting your SEO performance and must be fixed immediately. Missing title tag"
|
||||
|
||||
## React Dashboard Integration
|
||||
|
||||
### 🔄 API Endpoints
|
||||
|
||||
#### 1. `/analyze-seo` (POST)
|
||||
- **Purpose**: Full comprehensive analysis
|
||||
- **Input**: URL + optional target keywords
|
||||
- **Output**: Complete analysis with all metrics
|
||||
|
||||
#### 2. `/seo-metrics/{url}` (GET)
|
||||
- **Purpose**: Dashboard-specific metrics
|
||||
- **Input**: URL path parameter
|
||||
- **Output**: Optimized data structure for React dashboard
|
||||
|
||||
#### 3. `/analysis-summary/{url}` (GET)
|
||||
- **Purpose**: Quick overview
|
||||
- **Input**: URL path parameter
|
||||
- **Output**: Summary with top issues and recommendations
|
||||
|
||||
#### 4. `/batch-analyze` (POST)
|
||||
- **Purpose**: Multiple URL analysis
|
||||
- **Input**: List of URLs
|
||||
- **Output**: Batch results for comparison
|
||||
|
||||
### 📊 Dashboard Data Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"metrics": {
|
||||
"overall_score": 75,
|
||||
"health_status": "good",
|
||||
"url_structure_score": 85,
|
||||
"meta_data_score": 70,
|
||||
"content_score": 80,
|
||||
"technical_score": 65,
|
||||
"performance_score": 90,
|
||||
"accessibility_score": 75,
|
||||
"user_experience_score": 80,
|
||||
"security_score": 95
|
||||
},
|
||||
"critical_issues": [
|
||||
"🚨 CRITICAL: Missing title tag - critical for SEO"
|
||||
],
|
||||
"warnings": [
|
||||
"⚠️ WARNING: Title length (25 chars) should be 30-60 characters"
|
||||
],
|
||||
"recommendations": [
|
||||
"💡 RECOMMENDATION: Add compelling meta descriptions (70-160 characters)"
|
||||
],
|
||||
"detailed_analysis": {
|
||||
"url_structure": { /* detailed data */ },
|
||||
"meta_data": { /* detailed data */ },
|
||||
"content_analysis": { /* detailed data */ },
|
||||
"technical_seo": { /* detailed data */ },
|
||||
"performance": { /* detailed data */ },
|
||||
"accessibility": { /* detailed data */ },
|
||||
"user_experience": { /* detailed data */ },
|
||||
"security_headers": { /* detailed data */ },
|
||||
"keyword_analysis": { /* detailed data */ }
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"url": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 🎨 Dashboard Components Integration
|
||||
|
||||
#### 1. Health Score Component
|
||||
- Uses `overall_score` and `health_status`
|
||||
- Color-coded based on score ranges
|
||||
- Shows trend indicators
|
||||
|
||||
#### 2. Metrics Cards
|
||||
- Display individual category scores
|
||||
- Progress bars with color coding
|
||||
- Quick insights for each category
|
||||
|
||||
#### 3. Issues Panel
|
||||
- Prioritized list of critical issues
|
||||
- Collapsible warnings section
|
||||
- Actionable recommendations
|
||||
|
||||
#### 4. Detailed Analysis Tabs
|
||||
- Expandable sections for each category
|
||||
- Technical details for advanced users
|
||||
- Visual charts and graphs
|
||||
|
||||
#### 5. Recommendations Engine
|
||||
- Prioritized action items
|
||||
- Difficulty levels (Easy, Medium, Hard)
|
||||
- Estimated impact on SEO score
|
||||
|
||||
## Benefits for Non-Technical Users
|
||||
|
||||
### 🎯 Simplified Understanding
|
||||
- **Plain Language**: Technical concepts explained simply
|
||||
- **Visual Indicators**: Emojis and colors for quick understanding
|
||||
- **Priority Levels**: Clear distinction between critical, warning, and recommendation
|
||||
- **Actionable Steps**: Specific, implementable advice
|
||||
|
||||
### 📈 Progress Tracking
|
||||
- **Score Improvements**: Track SEO score over time
|
||||
- **Issue Resolution**: Mark issues as fixed
|
||||
- **Goal Setting**: Set target scores for different categories
|
||||
- **Competitor Comparison**: Compare against industry benchmarks
|
||||
|
||||
### 🔧 Implementation Guidance
|
||||
- **Step-by-Step Instructions**: Detailed how-to guides
|
||||
- **Resource Links**: Helpful tools and tutorials
|
||||
- **Priority Order**: Most impactful changes first
|
||||
- **Time Estimates**: How long each fix might take
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### 🏗️ Architecture
|
||||
```
|
||||
React Dashboard ←→ FastAPI Backend ←→ Comprehensive SEO Analyzer
|
||||
↑ ↑ ↑
|
||||
Zustand Store Pydantic Models BeautifulSoup + Advertools
|
||||
```
|
||||
|
||||
### 🔧 Dependencies
|
||||
- **FastAPI**: REST API framework
|
||||
- **BeautifulSoup**: HTML parsing
|
||||
- **Advertools**: Professional SEO analysis
|
||||
- **Textstat**: Readability scoring
|
||||
- **Spellchecker**: Content quality
|
||||
- **Requests**: HTTP client
|
||||
- **Pandas**: Data manipulation
|
||||
|
||||
### 🚀 Performance Optimizations
|
||||
- **Async Processing**: Non-blocking analysis
|
||||
- **Caching**: Store results for repeated analysis
|
||||
- **Batch Processing**: Multiple URLs simultaneously
|
||||
- **Error Handling**: Graceful failure recovery
|
||||
- **Rate Limiting**: Prevent API abuse
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 🔮 Planned Features
|
||||
1. **AI-Powered Insights**: Machine learning for better recommendations
|
||||
2. **Competitor Analysis**: Compare against top-ranking pages
|
||||
3. **Historical Tracking**: Monitor improvements over time
|
||||
4. **Custom Scoring**: Adjust weights based on industry/niche
|
||||
5. **Real-time Monitoring**: Continuous SEO health tracking
|
||||
6. **Integration APIs**: Connect with Google Search Console, Analytics
|
||||
|
||||
### 📊 Advanced Analytics
|
||||
- **Trend Analysis**: SEO performance over time
|
||||
- **Predictive Scoring**: Estimate future ranking potential
|
||||
- **Industry Benchmarks**: Compare against competitors
|
||||
- **ROI Calculator**: Estimate traffic improvements from fixes
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Comprehensive SEO Analyzer successfully combines all features from the three original modules while providing:
|
||||
|
||||
✅ **Complete Coverage**: All major SEO factors analyzed
|
||||
✅ **User-Friendly Output**: Non-technical language with clear guidance
|
||||
✅ **Actionable Insights**: Specific, implementable recommendations
|
||||
✅ **Dashboard Integration**: Optimized data structure for React components
|
||||
✅ **Scalable Architecture**: FastAPI backend with async processing
|
||||
✅ **Enhanced Prompts**: Better results through improved user communication
|
||||
|
||||
This unified solution provides a powerful, user-friendly SEO analysis tool that guides non-technical users toward significant improvements in their search engine rankings and overall website performance.
|
||||
@@ -1,248 +0,0 @@
|
||||
## Easy Installation Guide for Content Creators
|
||||
|
||||
### Step 1: Install Python 3.11
|
||||
1. Download Python 3.11 installer:
|
||||
- Visit [Python 3.11.6 Download Page](https://www.python.org/downloads/release/python-3116/)
|
||||
- Scroll down and click on "Windows installer (64-bit)"
|
||||
- Save the file to your computer
|
||||
|
||||
2. Run the installer:
|
||||
- Double click the downloaded file
|
||||
- ✅ IMPORTANT: Check "Add Python 3.11 to PATH"
|
||||
- Click "Install Now"
|
||||
- Wait for installation to complete
|
||||
- Click "Close"
|
||||
|
||||
### Step 2: Install ALwrity
|
||||
1. Download this project:
|
||||
- Click the green "Code" button above
|
||||
- Select "Download ZIP"
|
||||
- Extract the ZIP file to your desired location
|
||||
|
||||
2. Open Command Prompt:
|
||||
- Press Windows + R
|
||||
- Type "cmd" and press Enter
|
||||
- Navigate to the extracted folder:
|
||||
```
|
||||
cd path\to\ALwrity
|
||||
```
|
||||
|
||||
3. Run the automatic installer:
|
||||
```
|
||||
python setup.py install
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
If you encounter any issues:
|
||||
1. Make sure Python 3.11 is installed correctly:
|
||||
- Open Command Prompt
|
||||
- Type: `python --version`
|
||||
- Should show: `Python 3.11.x`
|
||||
|
||||
2. Common Issues:
|
||||
- If you see "Python is not recognized": Restart your computer
|
||||
- If you get package errors: Run `pip install --upgrade pip` first
|
||||
|
||||
Need help? [Open an issue](../../issues) and we'll assist you!
|
||||
|
||||
## For Developers
|
||||
If you're a developer or want to contribute:
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/ALwrity.git
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
|
||||
# Activate virtual environment
|
||||
# On Windows:
|
||||
.\venv\Scripts\activate
|
||||
# On Mac/Linux:
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
# ALwrity - AI Content Writing Assistant
|
||||
|
||||
## Quick Start Guide for Non-Technical Users
|
||||
|
||||
### Option 1: One-Click Installation (Recommended)
|
||||
1. Download this project:
|
||||
- Click the green "Code" button above
|
||||
- Select "Download ZIP"
|
||||
- Extract the ZIP file to your desired location (e.g., Desktop)
|
||||
|
||||
2. Run the installer:
|
||||
- Double-click `install.bat` in the extracted folder
|
||||
- If Windows asks for permission, click "Yes"
|
||||
- Follow the on-screen instructions
|
||||
- Wait for the installation to complete
|
||||
|
||||
3. Start ALwrity:
|
||||
- Open Command Prompt (Windows + R, type "cmd", press Enter)
|
||||
- Navigate to the ALwrity folder:
|
||||
```
|
||||
cd path\to\ALwrity
|
||||
```
|
||||
- Type `alwrity` and press Enter
|
||||
|
||||
### Option 2: Manual Installation
|
||||
If the one-click installer doesn't work, follow these steps:
|
||||
|
||||
1. Install Python 3.11:
|
||||
- Visit [Python 3.11.6 Download Page](https://www.python.org/downloads/release/python-3116/)
|
||||
- Click "Windows installer (64-bit)"
|
||||
- Run the installer
|
||||
- ✅ IMPORTANT: Check "Add Python 3.11 to PATH"
|
||||
- Click "Install Now"
|
||||
- Wait for installation to complete
|
||||
|
||||
2. Install ALwrity:
|
||||
- Open Command Prompt (Windows + R, type "cmd", press Enter)
|
||||
- Navigate to the ALwrity folder:
|
||||
```
|
||||
cd path\to\ALwrity
|
||||
```
|
||||
- Run the installation:
|
||||
```
|
||||
python setup.py install
|
||||
```
|
||||
- Follow any on-screen instructions
|
||||
|
||||
3. Start ALwrity:
|
||||
- In the same Command Prompt window, type:
|
||||
```
|
||||
alwrity
|
||||
```
|
||||
- Press Enter
|
||||
|
||||
### Troubleshooting Guide
|
||||
|
||||
#### Common Issues and Solutions:
|
||||
|
||||
1. "Python is not recognized"
|
||||
- Solution: Restart your computer after installing Python
|
||||
- Make sure you checked "Add Python 3.11 to PATH" during installation
|
||||
|
||||
2. "Visual C++ Build Tools not found"
|
||||
- Solution: Run this command in an administrative PowerShell:
|
||||
```
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools --silent --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
|
||||
```
|
||||
|
||||
3. "Rust compiler not found"
|
||||
- Solution: Run these commands in PowerShell:
|
||||
```
|
||||
Invoke-WebRequest -Uri https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe -OutFile rustup-init.exe
|
||||
./rustup-init.exe -y
|
||||
```
|
||||
|
||||
4. Installation Errors
|
||||
- Check the `install_errors.log` file in the ALwrity folder
|
||||
- Share the error message with our support team
|
||||
|
||||
#### Need Help?
|
||||
- Open an issue on GitHub
|
||||
- Join our support community
|
||||
- Contact our support team
|
||||
|
||||
### System Requirements
|
||||
- Windows 10 or later
|
||||
- Python 3.11.x
|
||||
- At least 4GB RAM
|
||||
- 2GB free disk space
|
||||
|
||||
### First-Time Setup
|
||||
After installation:
|
||||
1. The first time you run ALwrity, it will ask for your API keys
|
||||
2. Follow the on-screen instructions to enter your keys
|
||||
3. Your keys will be saved securely for future use
|
||||
|
||||
### Updating ALwrity
|
||||
To update to the latest version:
|
||||
1. Download the latest release
|
||||
2. Run `install.bat` again
|
||||
3. Follow the on-screen instructions
|
||||
|
||||
# ALwrity Windows Installer Guide (`install_alwrity.bat`)
|
||||
|
||||
---
|
||||
|
||||
## What is `install_alwrity.bat`?
|
||||
`install_alwrity.bat` is a fully automated installer for ALwrity on Windows. It is designed for non-technical users and will set up everything you need with minimal input.
|
||||
|
||||
---
|
||||
|
||||
## What Does It Do?
|
||||
- Checks for administrator rights and guides you if not running as admin.
|
||||
- Checks if Python 3.11 is installed. If not, it downloads and launches the installer for you.
|
||||
- Checks for Visual C++ Build Tools and Rust compiler. If missing, it downloads and launches their installers.
|
||||
- Creates a virtual environment for ALwrity.
|
||||
- Activates the environment and upgrades pip.
|
||||
- Installs all required Python packages and ALwrity itself.
|
||||
- Shows you how to start ALwrity after installation.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
- **Windows 10 or later**
|
||||
- **Internet connection** (to download Python and dependencies)
|
||||
- **At least 4GB RAM**
|
||||
- **2GB free disk space**
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Instructions
|
||||
|
||||
### 1. Download ALwrity
|
||||
- Download the ALwrity ZIP file from GitHub.
|
||||
- Right-click the ZIP file and select "Extract All..." to unzip it.
|
||||
- Open the extracted folder.
|
||||
|
||||
### 2. Run the Installer
|
||||
- Right-click `install_alwrity.bat` in the `Getting Started` folder and select "Run as administrator".
|
||||
- If Windows asks for permission, click "Yes".
|
||||
- Follow the on-screen instructions:
|
||||
- If Python 3.11, Visual C++ Build Tools, or Rust are missing, the installer will download and launch their installers for you. Complete each installation, then re-run `install_alwrity.bat`.
|
||||
- The installer will set up everything automatically. This may take a few minutes.
|
||||
|
||||
### 3. Start ALwrity
|
||||
- After installation, open a new Command Prompt window.
|
||||
- Type:
|
||||
```
|
||||
alwrity
|
||||
```
|
||||
- Press Enter. ALwrity will start!
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
- **Not running as administrator:**
|
||||
- Right-click `install_alwrity.bat` and select "Run as administrator".
|
||||
- **Python not found:**
|
||||
- Make sure you installed Python 3.11 and checked "Add Python 3.11 to PATH".
|
||||
- Restart your computer after installing Python.
|
||||
- **Permission errors:**
|
||||
- Make sure you are running as administrator.
|
||||
- **Other errors:**
|
||||
- Take a screenshot of the error and [open an issue on GitHub](https://github.com/AJaySi/AI-Writer/issues).
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
- **Do I need to install anything else?**
|
||||
- No, `install_alwrity.bat` will handle everything for you.
|
||||
- **Can I run this on Mac or Linux?**
|
||||
- No, this installer is for Windows only. See the Docker or manual instructions for other systems.
|
||||
- **Is it safe?**
|
||||
- Yes, the script only installs ALwrity and its dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Need More Help?
|
||||
- [Open an issue on GitHub](https://github.com/AJaySi/AI-Writer/issues)
|
||||
- Join our support community
|
||||
|
||||
---
|
||||
@@ -1,122 +0,0 @@
|
||||
@echo off
|
||||
setlocal enabledelayedexpansion
|
||||
|
||||
s :: Set colors for better visibility
|
||||
color 0A
|
||||
|
||||
:: Set the Python version requirement
|
||||
set MIN_PYTHON_VERSION=3.9
|
||||
|
||||
echo ===============================================
|
||||
echo ALwrity Installation Setup
|
||||
echo ===============================================
|
||||
echo.
|
||||
|
||||
echo [1/5] Checking Python installation...
|
||||
python --version > nul 2>&1
|
||||
if errorlevel 1 (
|
||||
color 0C
|
||||
echo [ERROR] Python is not installed!
|
||||
echo Please install Python %MIN_PYTHON_VERSION% or higher from python.org
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
:: Get Python version
|
||||
for /f "tokens=2" %%V in ('python --version 2^>^&1') do set PYTHON_VERSION=%%V
|
||||
for /f "tokens=1,2 delims=." %%a in ("%PYTHON_VERSION%") do (
|
||||
set PYTHON_MAJOR=%%a
|
||||
set PYTHON_MINOR=%%b
|
||||
)
|
||||
|
||||
:: Check Python version
|
||||
set /a PYTHON_VER=%PYTHON_MAJOR%*100 + %PYTHON_MINOR%
|
||||
set /a MIN_VER=309
|
||||
if %PYTHON_VER% LSS %MIN_VER% (
|
||||
color 0C
|
||||
echo [ERROR] Python version %MIN_PYTHON_VERSION% or higher is required!
|
||||
echo Current version: %PYTHON_VERSION%
|
||||
echo Please upgrade Python from python.org
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
echo [✓] Python %PYTHON_VERSION% detected
|
||||
echo.
|
||||
|
||||
echo [2/5] Creating virtual environment...
|
||||
python -m venv "%~dp0..\..\venv"
|
||||
if errorlevel 1 (
|
||||
color 0C
|
||||
echo [ERROR] Failed to create virtual environment!
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
echo [✓] Virtual environment created
|
||||
echo.
|
||||
|
||||
echo [3/5] Activating virtual environment...
|
||||
call "%~dp0..\..\venv\Scripts\activate.bat"
|
||||
if errorlevel 1 (
|
||||
color 0C
|
||||
echo [ERROR] Failed to activate virtual environment!
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
echo [✓] Virtual environment activated
|
||||
echo.
|
||||
|
||||
echo [4/5] Upgrading pip...
|
||||
python -m pip install --upgrade pip
|
||||
if errorlevel 1 (
|
||||
color 0C
|
||||
echo [ERROR] Failed to upgrade pip!
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
echo [✓] Pip upgraded
|
||||
echo.
|
||||
|
||||
echo [5/5] Installing requirements...
|
||||
pip install -r "%~dp0..\..\requirements.txt"
|
||||
if errorlevel 1 (
|
||||
color 0C
|
||||
echo [ERROR] Failed to install requirements!
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
exit /b 1
|
||||
)
|
||||
echo [✓] Requirements installed
|
||||
echo.
|
||||
|
||||
color 0A
|
||||
echo ===============================================
|
||||
echo Installation Completed Successfully!
|
||||
echo ===============================================
|
||||
echo.
|
||||
echo Next steps to run ALwrity:
|
||||
echo.
|
||||
echo 1. Open a new Command Prompt window
|
||||
echo 2. Navigate to the ALwrity root directory by copying and pasting this command:
|
||||
echo cd /d "%~dp0..\.."
|
||||
echo.
|
||||
echo 3. Activate the virtual environment by copying and pasting this command:
|
||||
echo "%~dp0..\..\venv\Scripts\activate.bat"
|
||||
echo.
|
||||
echo 4. Run ALwrity with Streamlit by copying and pasting this command:
|
||||
echo streamlit run "%~dp0..\..\alwrity.py"
|
||||
echo.
|
||||
echo Note: You'll need to activate the virtual environment (step 3)
|
||||
echo each time you want to run ALwrity.
|
||||
echo.
|
||||
echo Troubleshooting:
|
||||
echo - If you see any errors, make sure Python is in your PATH
|
||||
echo - For help, visit: https://github.com/yourusername/ALwrity
|
||||
echo.
|
||||
echo Press any key to exit...
|
||||
pause > nul
|
||||
@@ -1,27 +0,0 @@
|
||||
# ALwrity Installation Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Install Python**
|
||||
- Download and install Python from [python.org](https://www.python.org/downloads/)
|
||||
- During installation, check "Add Python to PATH"
|
||||
|
||||
2. **Install ALwrity**
|
||||
- Download this project
|
||||
- Open the 'Getting Started' folder
|
||||
- Double-click `setup.py`
|
||||
- Follow the on-screen instructions
|
||||
|
||||
## Running ALwrity
|
||||
|
||||
1. Open Command Prompt/Terminal in the 'Getting Started' folder
|
||||
2. Run: `venv\Scripts\activate` (Windows) or `source venv/bin/activate` (Mac/Linux)
|
||||
3. Run: `streamlit run alwrity.py`
|
||||
|
||||
## Need Help?
|
||||
|
||||
- If you see "pip not found": Re-install Python and check "Add Python to PATH"
|
||||
- For other issues: [Open a support ticket](https://github.com/AJaySi/AI-Writer/issues)
|
||||
- Join our support community
|
||||
|
||||
---
|
||||
@@ -1,170 +0,0 @@
|
||||
import sys
|
||||
import os
|
||||
import platform
|
||||
import subprocess
|
||||
import shutil
|
||||
import datetime
|
||||
import socket
|
||||
import traceback
|
||||
import pkg_resources
|
||||
from setuptools import setup, find_packages
|
||||
|
||||
def log_error(error_type, details):
|
||||
"""
|
||||
Logs installation errors to a file with timestamp and system information.
|
||||
"""
|
||||
log_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'install_errors.log')
|
||||
timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
system_info = {
|
||||
"OS": platform.system(),
|
||||
"OS Version": platform.version(),
|
||||
"Architecture": platform.machine(),
|
||||
"Python Version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
|
||||
"Hostname": socket.gethostname()
|
||||
}
|
||||
|
||||
log_entry = f"[{timestamp}] ERROR: {error_type}\n"
|
||||
log_entry += f"Details: {details}\n"
|
||||
log_entry += "System Information:\n"
|
||||
for key, value in system_info.items():
|
||||
log_entry += f" {key}: {value}\n"
|
||||
log_entry += "-" * 80 + "\n"
|
||||
|
||||
with open(log_file, 'a') as f:
|
||||
f.write(log_entry)
|
||||
|
||||
print(f"Error logged to {log_file}")
|
||||
|
||||
def check_system_dependencies():
|
||||
"""Check for required system dependencies."""
|
||||
print("Checking system dependencies...")
|
||||
all_checks_passed = True
|
||||
|
||||
# User message about system dependencies
|
||||
print("\nNOTE: Some dependencies like Rust, Visual C++ Build Tools, or Python itself cannot be installed automatically by this script.")
|
||||
print("This is because installing system-level packages requires admin rights and can differ across operating systems.")
|
||||
print("For your safety and system stability, please follow the on-screen instructions to install any missing prerequisites manually.\n")
|
||||
|
||||
# Check Python version
|
||||
print("Checking Python version...")
|
||||
if sys.version_info < (3, 11) or sys.version_info >= (3, 12):
|
||||
error_msg = "ALwrity requires Python 3.11.x"
|
||||
print(f"Error: {error_msg}")
|
||||
log_error("Python Version Check", error_msg)
|
||||
all_checks_passed = False
|
||||
else:
|
||||
print(f"✓ Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} found")
|
||||
|
||||
# Check Visual C++ Build Tools on Windows
|
||||
if platform.system() == "Windows":
|
||||
print("Checking for Visual C++ Build Tools...")
|
||||
if not shutil.which("cl"):
|
||||
error_msg = "Visual C++ Build Tools not found"
|
||||
print("❌ Visual C++ Build Tools not found")
|
||||
print("\nTo install Visual C++ Build Tools, run in an administrative PowerShell:")
|
||||
print("winget install Microsoft.VisualStudio.2022.BuildTools --silent --override \"--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended\"")
|
||||
log_error("Visual C++ Build Tools Check", error_msg)
|
||||
all_checks_passed = False
|
||||
else:
|
||||
print("✓ Visual C++ Build Tools found")
|
||||
|
||||
# Check Rust compiler
|
||||
print("Checking for Rust compiler...")
|
||||
if not shutil.which("rustc"):
|
||||
error_msg = "Rust compiler not found"
|
||||
print("❌ Rust compiler not found")
|
||||
if platform.system() == "Windows":
|
||||
print("\nTo install Rust on Windows, run:")
|
||||
print("Invoke-WebRequest -Uri https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe -OutFile rustup-init.exe")
|
||||
print("./rustup-init.exe -y")
|
||||
else:
|
||||
print("\nTo install Rust on Linux/macOS, run:")
|
||||
print("curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y")
|
||||
print("source $HOME/.cargo/env")
|
||||
log_error("Rust Compiler Check", error_msg)
|
||||
all_checks_passed = False
|
||||
else:
|
||||
print("✓ Rust compiler found")
|
||||
|
||||
return all_checks_passed
|
||||
|
||||
def get_requirements():
|
||||
"""Read requirements from requirements.txt."""
|
||||
with open('requirements.txt') as f:
|
||||
requirements = [line.strip() for line in f if line.strip() and not line.startswith('#')]
|
||||
return requirements
|
||||
|
||||
def install_requirements(requirements):
|
||||
"""Install each requirement, showing progress."""
|
||||
print("Installing required packages...")
|
||||
for requirement in requirements:
|
||||
try:
|
||||
print(f"Installing {requirement}...")
|
||||
subprocess.check_call([sys.executable, "-m", "pip", "install", requirement])
|
||||
except subprocess.CalledProcessError as e:
|
||||
error_msg = f"Error installing {requirement}: {e}"
|
||||
print(error_msg)
|
||||
log_error("Package Installation", error_msg)
|
||||
sys.exit(1)
|
||||
|
||||
def main():
|
||||
"""Main installation function."""
|
||||
print("ALwrity Installation\n")
|
||||
|
||||
# Check system dependencies
|
||||
if not check_system_dependencies():
|
||||
print("\nPlease install the missing dependencies and try again.")
|
||||
print("Check the install_errors.log file for detailed error information.")
|
||||
sys.exit(1)
|
||||
|
||||
# Create virtual environment if it doesn't exist
|
||||
if not os.path.exists("venv"):
|
||||
print("\nCreating virtual environment...")
|
||||
try:
|
||||
subprocess.check_call([sys.executable, "-m", "venv", "venv"])
|
||||
except subprocess.CalledProcessError as e:
|
||||
error_msg = f"Failed to create virtual environment: {e}"
|
||||
print(error_msg)
|
||||
log_error("Virtual Environment Creation", error_msg)
|
||||
sys.exit(1)
|
||||
|
||||
# Activate virtual environment automatically (Linux/macOS only)
|
||||
if platform.system() != "Windows":
|
||||
activate_script = os.path.join("venv", "bin", "activate_this.py")
|
||||
if os.path.exists(activate_script):
|
||||
with open(activate_script) as f:
|
||||
exec(f.read(), {'__file__': activate_script})
|
||||
|
||||
# Install requirements
|
||||
requirements = get_requirements()
|
||||
install_requirements(requirements)
|
||||
|
||||
# Run setup
|
||||
setup(
|
||||
name="alwrity",
|
||||
version="1.0.0",
|
||||
description="AI-powered content writing assistant",
|
||||
author="Your Name",
|
||||
packages=find_packages(),
|
||||
python_requires=">=3.11, <3.12",
|
||||
install_requires=requirements,
|
||||
entry_points={
|
||||
'console_scripts': [
|
||||
'alwrity=alwrity:main',
|
||||
],
|
||||
},
|
||||
)
|
||||
|
||||
print("\nInstallation complete! To start ALwrity:")
|
||||
print("1. Activate the virtual environment:")
|
||||
if platform.system() == "Windows":
|
||||
print(" .\\venv\\Scripts\\activate")
|
||||
else:
|
||||
print(" source venv/bin/activate")
|
||||
print("2. Run the application:")
|
||||
print(" streamlit run alwrity.py")
|
||||
print("\nYou can now use the 'alwrity' command as well.")
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -1,83 +0,0 @@
|
||||
# =====================================================================
|
||||
# ALwrity Automated Dockerfile - Best Practices & Full Functionality
|
||||
# =====================================================================
|
||||
# This Dockerfile is designed for cache efficiency, security, and ease of use.
|
||||
# It uses multi-stage builds for smaller images and leverages Docker layer caching.
|
||||
# =====================================================================
|
||||
|
||||
# 1. Use official Python 3.12 image (builder stage)
|
||||
FROM python:3.12
|
||||
|
||||
# 2. Set environment variables for Python
|
||||
ENV PYTHONDONTWRITEBYTECODE=1 \
|
||||
PYTHONUNBUFFERED=1
|
||||
|
||||
# 3. Install build dependencies first (for cache efficiency)
|
||||
RUN apt-get update && \
|
||||
apt-get install -y --no-install-recommends \
|
||||
build-essential \
|
||||
gcc \
|
||||
git \
|
||||
curl \
|
||||
wget \
|
||||
libffi-dev \
|
||||
libssl-dev \
|
||||
rustc \
|
||||
cargo \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 4. Set work directory
|
||||
WORKDIR /app
|
||||
|
||||
# 5. Copy only requirements.txt first (for better caching)
|
||||
COPY ../requirements.txt ./
|
||||
|
||||
# 6. Install Python dependencies in builder
|
||||
RUN pip install --upgrade pip && \
|
||||
pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
# === Start runtime stage ===
|
||||
FROM python:3.12-slim AS runtime
|
||||
|
||||
# 7. Install build tools needed for wordcloud
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends gcc build-essential && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 8. Set work directory
|
||||
WORKDIR /app
|
||||
|
||||
# 9. Copy app source code, requirements, and .env to runtime image
|
||||
COPY ../requirements.txt ./
|
||||
COPY ../alwrity.py /app/
|
||||
COPY ../lib /app/lib
|
||||
|
||||
# Create the .env file with default values
|
||||
RUN echo "# Default environment variables for ALwrity\n" > /app/.env
|
||||
|
||||
# 10. Install Python dependencies
|
||||
RUN pip install --upgrade pip && \
|
||||
pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
# 11. Create a non-root user for security
|
||||
RUN useradd -m alwrityuser
|
||||
|
||||
# 12. Change ownership of /app and .env to the non-root user
|
||||
RUN chown -R alwrityuser:alwrityuser /app
|
||||
|
||||
# 13. Set environment variable for Streamlit (optional: disables telemetry)
|
||||
ENV STREAMLIT_TELEMETRY=0
|
||||
|
||||
# 14. Expose Streamlit's default port
|
||||
EXPOSE 8501
|
||||
|
||||
# 15. Switch to non-root user
|
||||
USER alwrityuser
|
||||
|
||||
# 16. Add user local bin to PATH
|
||||
ENV PATH="/home/alwrityuser/.local/bin:$PATH"
|
||||
|
||||
# 17. Default command: run ALwrity with Streamlit
|
||||
CMD ["streamlit", "run", "alwrity.py", "--server.port=8501", "--server.address=0.0.0.0"]
|
||||
|
||||
# =====================================================================
|
||||
# END OF DOCKERFILE
|
||||
# =====================================================================
|
||||
@@ -1,67 +0,0 @@
|
||||
cd "Getting Started/Option_3_Docker_Install"
|
||||
docker-compose up --build---
|
||||
|
||||
## Using ALwrity with Docker (Recommended for All Users)
|
||||
|
||||
### What is Docker?
|
||||
Docker lets you run ALwrity in a safe, isolated environment on any computer (Windows, Mac, Linux) without worrying about Python or system setup. Think of it as a "ready-to-go" box for the app.
|
||||
|
||||
### Step 1: Install Docker
|
||||
- Go to [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/)
|
||||
- Download and install Docker Desktop for your operating system (Windows/Mac) or follow the Linux instructions.
|
||||
- After installation, restart your computer if prompted.
|
||||
- To check Docker is working, open a terminal and run:
|
||||
```bash
|
||||
docker --version
|
||||
```
|
||||
You should see a version number.
|
||||
|
||||
### Step 2: Build and Run ALwrity with Docker Compose (Recommended)
|
||||
1. Open a terminal.
|
||||
2. Navigate to the **Option_3_Docker_Install** folder:
|
||||
```bash
|
||||
cd "Getting Started/Option_3_Docker_Install"
|
||||
```
|
||||
3. Build and start the app using Docker Compose:
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
4. Wait until you see a message like:
|
||||
```
|
||||
Local URL: http://localhost:8501
|
||||
```
|
||||
5. Open your web browser and go to [http://localhost:8501](http://localhost:8501)
|
||||
6. Follow the on-screen instructions to set up your API keys and start creating content!
|
||||
|
||||
### Stopping ALwrity
|
||||
- To stop the app, press `Ctrl+C` in the terminal where Docker Compose is running.
|
||||
- To remove the containers, run:
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Advanced: Manual Docker Build/Run (Optional)
|
||||
If you prefer not to use Docker Compose, you can build and run manually:
|
||||
```bash
|
||||
cd /workspaces/AI-Writer
|
||||
# Build the image
|
||||
docker build -t alwrity -f "Getting Started/Option_3_Docker_Install/Dockerfile" .
|
||||
# Run the container
|
||||
docker run -p 8501:8501 alwrity
|
||||
```
|
||||
|
||||
### Advanced: Saving Your Work
|
||||
- By default, any files you create inside Docker are lost when the container stops.
|
||||
- To save your work to your computer, use a volume:
|
||||
```bash
|
||||
docker run -p 8501:8501 -v $(pwd)/alwrity_data:/app/your_data_folder alwrity
|
||||
```
|
||||
|
||||
### Advanced: Publishing to Docker Hub
|
||||
To build and push your image to Docker Hub:
|
||||
```bash
|
||||
docker build -t yourdockerhubusername/alwrity:latest -f "Getting Started/Option_3_Docker_Install/Dockerfile" .
|
||||
docker push yourdockerhubusername/alwrity:latest
|
||||
```
|
||||
|
||||
---
|
||||
@@ -1,13 +0,0 @@
|
||||
version: '3.8'
|
||||
services:
|
||||
alwrity:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: Getting Started/Option_3_Docker_Install/Dockerfile
|
||||
ports:
|
||||
- "8501:8501"
|
||||
environment:
|
||||
- STREAMLIT_TELEMETRY=0
|
||||
volumes:
|
||||
- ../../.env:/app/.env
|
||||
restart: unless-stopped
|
||||
@@ -1,26 +0,0 @@
|
||||
# Use Python 3.8 slim image optimized for M1/M2 Macs
|
||||
FROM --platform=linux/arm64 python:3.8-slim
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Install system dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
build-essential \
|
||||
curl \
|
||||
software-properties-common \
|
||||
git \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Clone the repository
|
||||
RUN git clone https://github.com/AJaySi/AI-Writer.git .
|
||||
|
||||
# Install Python dependencies
|
||||
RUN python -m pip install --upgrade pip
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
# Expose Streamlit port
|
||||
EXPOSE 8501
|
||||
|
||||
# Run the application
|
||||
CMD ["streamlit", "run", "alwrity.py"]
|
||||
@@ -1,23 +0,0 @@
|
||||
# ALwrity Installation for Mac Users
|
||||
|
||||
## Prerequisites
|
||||
- macOS 10.15 or later
|
||||
- Terminal access
|
||||
- Internet connection
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Easy Setup (Recommended)
|
||||
1. Open Terminal
|
||||
2. Navigate to this directory
|
||||
3. Run: `python setup.py`
|
||||
4. Follow the on-screen instructions
|
||||
|
||||
### Method 2: Docker Installation
|
||||
1. Install Docker Desktop for Mac
|
||||
- Visit [Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
- Download and install the Apple Silicon (M1/M2) or Intel version
|
||||
2. Build and run:
|
||||
```bash
|
||||
docker build -t alwrity .
|
||||
docker run -p 8501:8501 alwrity
|
||||
@@ -1,78 +0,0 @@
|
||||
import sys
|
||||
import os
|
||||
import subprocess
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
|
||||
def print_step(text):
|
||||
print(f"\n→ {text}")
|
||||
|
||||
def print_error(text):
|
||||
print(f"\nError: {text}", file=sys.stderr)
|
||||
|
||||
def check_homebrew():
|
||||
try:
|
||||
subprocess.run(['brew', '--version'], capture_output=True, check=True)
|
||||
return True
|
||||
except:
|
||||
return False
|
||||
|
||||
def setup_homebrew():
|
||||
print_step("Homebrew is required for some dependencies")
|
||||
print("Please install Homebrew by running this command in Terminal:")
|
||||
print('/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"')
|
||||
print("\nAfter installing Homebrew, run this setup script again.")
|
||||
sys.exit(1)
|
||||
|
||||
def create_virtual_environment(venv_path):
|
||||
try:
|
||||
if venv_path.exists():
|
||||
shutil.rmtree(venv_path)
|
||||
subprocess.run([sys.executable, '-m', 'venv', str(venv_path)], check=True)
|
||||
return True
|
||||
except Exception as e:
|
||||
print_error(f"Failed to create virtual environment: {e}")
|
||||
return False
|
||||
|
||||
def install_requirements(venv_python, requirements_path):
|
||||
try:
|
||||
subprocess.run([str(venv_python), '-m', 'pip', 'install', '--upgrade', 'pip'], check=True)
|
||||
subprocess.run([str(venv_python), '-m', 'pip', 'install', '-r', str(requirements_path)], check=True)
|
||||
return True
|
||||
except Exception as e:
|
||||
print_error(f"Failed to install requirements: {e}")
|
||||
return False
|
||||
|
||||
def main():
|
||||
print("\n=== ALwrity Mac Installation ===\n")
|
||||
|
||||
if not check_homebrew():
|
||||
setup_homebrew()
|
||||
|
||||
current_dir = Path(__file__).parent
|
||||
project_root = current_dir.parent.parent
|
||||
requirements_path = project_root / 'requirements.txt'
|
||||
venv_path = current_dir / 'venv'
|
||||
|
||||
print_step("Creating virtual environment")
|
||||
if not create_virtual_environment(venv_path):
|
||||
return
|
||||
|
||||
print_step("Installing dependencies")
|
||||
venv_python = venv_path / 'bin' / 'python'
|
||||
if not install_requirements(venv_python, requirements_path):
|
||||
return
|
||||
|
||||
print("\n✓ Installation completed successfully!")
|
||||
print("\nTo start ALwrity:")
|
||||
print("1. Open Terminal in this directory")
|
||||
print("2. Run: source venv/bin/activate")
|
||||
print("3. Run: streamlit run alwrity.py")
|
||||
|
||||
if __name__ == '__main__':
|
||||
try:
|
||||
main()
|
||||
except KeyboardInterrupt:
|
||||
print("\nInstallation cancelled")
|
||||
except Exception as e:
|
||||
print_error(f"Unexpected error: {e}")
|
||||
@@ -1,25 +0,0 @@
|
||||
# Getting Started with ALwrity
|
||||
|
||||
Welcome to ALwrity! Choose the installation method that best suits you:
|
||||
|
||||
## Option 1: Quick Install for Windows Users (Recommended for Content Creators)
|
||||
- No technical knowledge required
|
||||
- Automatic Python installation
|
||||
- One-click setup
|
||||
→ [Go to Windows Quick Install](./Option_1_Windows_Quick_Install)
|
||||
|
||||
## Option 2: Setup for Python Users
|
||||
- For users who already have Python installed
|
||||
- More customization options
|
||||
- Manual virtual environment setup
|
||||
→ [Go to Python Setup](./Option_2_Python_Users)
|
||||
|
||||
## Option 3: Docker Installation
|
||||
- For advanced users and developers
|
||||
- Containerized environment
|
||||
- Platform-independent setup
|
||||
→ [Go to Docker Setup](./Option_3_Docker_Install)
|
||||
|
||||
## Need Help?
|
||||
- Visit our [GitHub Issues](https://github.com/AJaySi/AI-Writer/issues) page
|
||||
- Check our [Documentation](../docs)
|
||||
@@ -1,163 +0,0 @@
|
||||
# Zustand Implementation Summary
|
||||
|
||||
## Overview
|
||||
|
||||
After reviewing the MainDashboard and SEODashboard components, I determined that implementing Zustand would provide significant benefits over the current state management approach. The implementation has been completed successfully.
|
||||
|
||||
## Analysis Results
|
||||
|
||||
### Issues with Current State Management
|
||||
|
||||
1. **MainDashboard**: Used a custom `useDashboardState` hook with manual localStorage persistence
|
||||
2. **SEODashboard**: Used local `useState` hooks for loading, error, and data states
|
||||
3. **No shared state**: Each dashboard managed its own state independently
|
||||
4. **Manual localStorage handling**: Favorites were manually persisted
|
||||
5. **No cross-component communication**: States were isolated between components
|
||||
|
||||
### Benefits of Zustand Implementation
|
||||
|
||||
✅ **Centralized state management** across both dashboards
|
||||
✅ **Automatic persistence** with Zustand's persist middleware
|
||||
✅ **Better performance** with selective re-renders
|
||||
✅ **Simpler state updates** with immer-like syntax
|
||||
✅ **Better debugging** with Redux DevTools support
|
||||
✅ **Type safety** with TypeScript interfaces
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### 1. Dashboard Store (`frontend/src/stores/dashboardStore.ts`)
|
||||
|
||||
**Replaces**: `useDashboardState` hook in MainDashboard
|
||||
|
||||
**Features**:
|
||||
- Automatic persistence of favorites and filter preferences
|
||||
- Snackbar management with automatic hiding
|
||||
- Optimized re-renders with selective state subscriptions
|
||||
- Type-safe state management
|
||||
|
||||
**Key Actions**:
|
||||
- `toggleFavorite()` - Add/remove tools from favorites
|
||||
- `setSearchQuery()` - Update search filter
|
||||
- `setSelectedCategory()` - Update category filter
|
||||
- `showSnackbar()` - Display notifications
|
||||
- `clearFilters()` - Reset all filters
|
||||
|
||||
### 2. SEO Dashboard Store (`frontend/src/stores/seoDashboardStore.ts`)
|
||||
|
||||
**Replaces**: Local `useState` hooks in SEODashboard
|
||||
|
||||
**Features**:
|
||||
- Automatic data fetching on component mount
|
||||
- Error handling with retry functionality
|
||||
- Data caching with last updated timestamp
|
||||
- DevTools integration for debugging
|
||||
|
||||
**Key Actions**:
|
||||
- `fetchDashboardData()` - Load dashboard data
|
||||
- `refreshData()` - Refresh dashboard data
|
||||
- `setError()` - Handle error states
|
||||
- `clearError()` - Clear error states
|
||||
|
||||
### 3. Shared Dashboard Store (`frontend/src/stores/sharedDashboardStore.ts`)
|
||||
|
||||
**New**: Common functionality for both dashboards
|
||||
|
||||
**Features**:
|
||||
- Theme switching with system preference detection
|
||||
- Notification management with auto-cleanup
|
||||
- Sidebar state management
|
||||
- Global state for cross-component communication
|
||||
|
||||
**Key Actions**:
|
||||
- `setTheme()` - Switch between light/dark/auto themes
|
||||
- `addNotification()` - Add global notifications
|
||||
- `toggleSidebar()` - Control sidebar visibility
|
||||
|
||||
## Migration Changes
|
||||
|
||||
### MainDashboard Component
|
||||
```typescript
|
||||
// Before
|
||||
const { state, toggleFavorite, setSearchQuery } = useDashboardState();
|
||||
|
||||
// After
|
||||
const { favorites, toggleFavorite, setSearchQuery } = useDashboardStore();
|
||||
```
|
||||
|
||||
### SEODashboard Component
|
||||
```typescript
|
||||
// Before
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [data, setData] = useState<SEODashboardData | null>(null);
|
||||
|
||||
// After
|
||||
const { loading, error, data, fetchDashboardData } = useSEODashboardStore();
|
||||
```
|
||||
|
||||
## Performance Improvements
|
||||
|
||||
1. **Selective Re-renders**: Components only re-render when their specific state changes
|
||||
2. **Automatic Persistence**: No manual localStorage management needed
|
||||
3. **Optimized Updates**: Zustand's internal optimizations reduce unnecessary renders
|
||||
4. **DevTools Integration**: Better debugging and state inspection
|
||||
|
||||
## Code Quality Improvements
|
||||
|
||||
1. **Type Safety**: All stores have TypeScript interfaces
|
||||
2. **Separation of Concerns**: Each store handles specific functionality
|
||||
3. **Reusability**: Stores can be used across multiple components
|
||||
4. **Testability**: Stores can be tested independently
|
||||
5. **Maintainability**: Centralized state management is easier to maintain
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
### New Files
|
||||
- `frontend/src/stores/dashboardStore.ts` - Main dashboard state management
|
||||
- `frontend/src/stores/seoDashboardStore.ts` - SEO dashboard state management
|
||||
- `frontend/src/stores/sharedDashboardStore.ts` - Shared dashboard functionality
|
||||
- `frontend/src/stores/index.ts` - Store exports
|
||||
- `frontend/src/stores/README.md` - Implementation documentation
|
||||
|
||||
### Modified Files
|
||||
- `frontend/src/components/MainDashboard/MainDashboard.tsx` - Updated to use Zustand store
|
||||
- `frontend/src/components/SEODashboard/SEODashboard.tsx` - Updated to use Zustand store
|
||||
|
||||
## Benefits Achieved
|
||||
|
||||
### For Developers
|
||||
- **Simpler Code**: No more manual localStorage management
|
||||
- **Better Debugging**: Redux DevTools integration
|
||||
- **Type Safety**: Full TypeScript support
|
||||
- **Reusability**: Stores can be shared across components
|
||||
|
||||
### For Users
|
||||
- **Better Performance**: Faster re-renders and updates
|
||||
- **Persistent State**: Favorites and preferences are automatically saved
|
||||
- **Consistent Experience**: Shared state across dashboard components
|
||||
- **Reliable Data**: Better error handling and retry mechanisms
|
||||
|
||||
### For Maintenance
|
||||
- **Centralized Logic**: All state management in one place
|
||||
- **Easy Testing**: Stores can be tested independently
|
||||
- **Future-Proof**: Easy to extend with new features
|
||||
- **Documentation**: Comprehensive documentation provided
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Remove Old Code**: The `useDashboardState` hook can be removed after confirming the new implementation works correctly
|
||||
2. **Add Tests**: Implement comprehensive tests for the stores
|
||||
3. **Extend Functionality**: Add more features like real-time updates, offline support
|
||||
4. **Monitor Performance**: Track performance improvements in production
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Zustand implementation successfully addresses all the identified issues with the previous state management approach. The dashboards now have:
|
||||
|
||||
- ✅ Centralized, persistent state management
|
||||
- ✅ Better performance with selective re-renders
|
||||
- ✅ Improved developer experience with DevTools
|
||||
- ✅ Type-safe state management
|
||||
- ✅ Simplified codebase with less boilerplate
|
||||
|
||||
The implementation is production-ready and provides a solid foundation for future enhancements.
|
||||
@@ -1,302 +0,0 @@
|
||||
# Modular Design System: Alwrity Onboarding
|
||||
|
||||
## 🎯 **Overview**
|
||||
|
||||
This document outlines the modular design system for Alwrity's onboarding flow, ensuring **consistency**, **reusability**, and **maintainability** across all onboarding steps while preserving all current functionality and styling.
|
||||
|
||||
---
|
||||
|
||||
## **🏗️ Architecture**
|
||||
|
||||
### **Core Components**
|
||||
```
|
||||
frontend/src/components/OnboardingWizard/
|
||||
├── common/
|
||||
│ ├── useOnboardingStyles.ts # Centralized styling hook
|
||||
│ ├── onboardingUtils.ts # Shared utility functions
|
||||
│ ├── OnboardingStepLayout.tsx # Reusable layout component
|
||||
│ ├── OnboardingCard.tsx # Reusable card component
|
||||
│ └── OnboardingButton.tsx # Reusable button component
|
||||
├── ApiKeyStep.tsx # Refactored to use design system
|
||||
├── WebsiteStep.tsx # Will be refactored
|
||||
├── ResearchStep.tsx # Will be refactored
|
||||
├── PersonalizationStep.tsx # Will be refactored
|
||||
├── IntegrationsStep.tsx # Will be refactored
|
||||
└── FinalStep.tsx # Will be refactored
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **🎨 Design System Components**
|
||||
|
||||
### **1. useOnboardingStyles Hook**
|
||||
**Purpose**: Centralized styling for all onboarding components
|
||||
**Benefits**:
|
||||
- ✅ Consistent styling across all steps
|
||||
- ✅ Easy to maintain and update
|
||||
- ✅ Theme-aware styling
|
||||
- ✅ Reusable style objects
|
||||
|
||||
```typescript
|
||||
// Usage in any step component
|
||||
const styles = useOnboardingStyles();
|
||||
|
||||
// Apply consistent styling
|
||||
<Box sx={styles.container}>
|
||||
<Typography sx={styles.headerTitle}>Title</Typography>
|
||||
<Button sx={styles.primaryButton}>Action</Button>
|
||||
</Box>
|
||||
```
|
||||
|
||||
### **2. onboardingUtils Functions**
|
||||
**Purpose**: Shared utility functions for common operations
|
||||
**Benefits**:
|
||||
- ✅ DRY (Don't Repeat Yourself) principle
|
||||
- ✅ Consistent validation logic
|
||||
- ✅ Reusable animation utilities
|
||||
- ✅ Standardized error handling
|
||||
|
||||
```typescript
|
||||
// Validation utilities
|
||||
const isValid = validateApiKey(key, 'openai');
|
||||
const status = getKeyStatus(key, 'openai');
|
||||
|
||||
// Animation utilities
|
||||
const delay = getAnimationDelay(index);
|
||||
const direction = getSlideDirection(current, target);
|
||||
|
||||
// Form utilities
|
||||
const isValid = isFormValid(formValues);
|
||||
const progress = calculateProgress(current, total);
|
||||
```
|
||||
|
||||
### **3. OnboardingStepLayout Component**
|
||||
**Purpose**: Consistent layout structure for all steps
|
||||
**Benefits**:
|
||||
- ✅ Standardized header structure
|
||||
- ✅ Consistent spacing and typography
|
||||
- ✅ Reusable animations
|
||||
- ✅ Flexible content area
|
||||
|
||||
```typescript
|
||||
<OnboardingStepLayout
|
||||
icon={<Key />}
|
||||
title="Connect Your AI Services"
|
||||
subtitle="Add your API keys to enable AI-powered content creation"
|
||||
>
|
||||
{/* Step-specific content */}
|
||||
</OnboardingStepLayout>
|
||||
```
|
||||
|
||||
### **4. OnboardingCard Component**
|
||||
**Purpose**: Consistent card styling with status indicators
|
||||
**Benefits**:
|
||||
- ✅ Standardized card appearance
|
||||
- ✅ Built-in status validation
|
||||
- ✅ Consistent hover effects
|
||||
- ✅ Reusable across all steps
|
||||
|
||||
```typescript
|
||||
<OnboardingCard
|
||||
title="OpenAI API Key"
|
||||
icon={<Security />}
|
||||
status={getKeyStatus(key, 'openai')}
|
||||
saved={!!savedKeys.openai}
|
||||
>
|
||||
<TextField value={key} onChange={handleChange} />
|
||||
</OnboardingCard>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **🔧 Implementation Guidelines**
|
||||
|
||||
### **1. Step Component Structure**
|
||||
Every onboarding step should follow this structure:
|
||||
|
||||
```typescript
|
||||
import { useOnboardingStyles } from './common/useOnboardingStyles';
|
||||
import { relevantUtils } from './common/onboardingUtils';
|
||||
|
||||
const StepComponent: React.FC<StepProps> = ({ onContinue }) => {
|
||||
const styles = useOnboardingStyles();
|
||||
|
||||
// State management
|
||||
const [formData, setFormData] = useState({});
|
||||
const [loading, setLoading] = useState(false);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
// Validation
|
||||
const isValid = isFormValid(formData);
|
||||
|
||||
// Event handlers
|
||||
const handleSave = async () => {
|
||||
// Implementation
|
||||
};
|
||||
|
||||
return (
|
||||
<Fade in={true} timeout={500}>
|
||||
<Box sx={styles.container}>
|
||||
{/* Header */}
|
||||
<Box sx={styles.header}>
|
||||
<Zoom in={true} timeout={600}>
|
||||
{/* Header content */}
|
||||
</Zoom>
|
||||
</Box>
|
||||
|
||||
{/* Form content */}
|
||||
<Box sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
|
||||
{/* Cards and form elements */}
|
||||
</Box>
|
||||
|
||||
{/* Alerts */}
|
||||
{/* Action buttons */}
|
||||
{/* Skip section */}
|
||||
</Box>
|
||||
</Fade>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### **2. Styling Guidelines**
|
||||
- **Use the styles hook**: Always use `useOnboardingStyles()` for styling
|
||||
- **Consistent spacing**: Use the predefined spacing values
|
||||
- **Theme integration**: Leverage Material-UI theme for colors
|
||||
- **Responsive design**: Use the responsive breakpoints
|
||||
|
||||
### **3. Animation Guidelines**
|
||||
- **Fade in**: Use `Fade` component for step transitions
|
||||
- **Zoom effects**: Use `Zoom` for important elements
|
||||
- **Slide transitions**: Use `Slide` for step navigation
|
||||
- **Consistent timing**: Use predefined timeouts (300ms, 500ms, 700ms)
|
||||
|
||||
### **4. Validation Guidelines**
|
||||
- **Real-time validation**: Use debounced validation for better UX
|
||||
- **Visual feedback**: Show status chips and border colors
|
||||
- **Error handling**: Use `formatErrorMessage` for consistent error messages
|
||||
- **Form validation**: Use `isFormValid` for form completeness
|
||||
|
||||
---
|
||||
|
||||
## **📋 Component Checklist**
|
||||
|
||||
### **For Each Step Component**
|
||||
- [ ] **Import design system**: Use `useOnboardingStyles` and relevant utilities
|
||||
- [ ] **Consistent structure**: Follow the standard component structure
|
||||
- [ ] **Proper animations**: Use `Fade`, `Zoom`, and `Slide` components
|
||||
- [ ] **Form validation**: Implement real-time validation with visual feedback
|
||||
- [ ] **Error handling**: Use `formatErrorMessage` for error display
|
||||
- [ ] **Loading states**: Show loading indicators during async operations
|
||||
- [ ] **Auto-save**: Implement auto-save functionality where appropriate
|
||||
- [ ] **Skip options**: Provide skip functionality for optional steps
|
||||
- [ ] **Help sections**: Include collapsible help content
|
||||
- [ ] **Responsive design**: Ensure mobile-friendly layout
|
||||
|
||||
### **For New Components**
|
||||
- [ ] **Reusable design**: Make components generic and reusable
|
||||
- [ ] **Props interface**: Define clear TypeScript interfaces
|
||||
- [ ] **Default values**: Provide sensible defaults
|
||||
- [ ] **Documentation**: Add JSDoc comments
|
||||
- [ ] **Testing**: Include unit tests for utilities
|
||||
|
||||
---
|
||||
|
||||
## **🎯 Benefits of This System**
|
||||
|
||||
### **1. Consistency**
|
||||
- ✅ **Visual consistency**: All steps look and feel the same
|
||||
- ✅ **Behavior consistency**: Same interactions across all steps
|
||||
- ✅ **Animation consistency**: Standardized transitions and effects
|
||||
- ✅ **Error handling**: Consistent error messages and recovery
|
||||
|
||||
### **2. Reusability**
|
||||
- ✅ **Shared components**: Common components used across steps
|
||||
- ✅ **Shared utilities**: Validation, animation, and form utilities
|
||||
- ✅ **Shared styles**: Centralized styling system
|
||||
- ✅ **Shared logic**: Common business logic extracted to utilities
|
||||
|
||||
### **3. Maintainability**
|
||||
- ✅ **Single source of truth**: Styles and utilities in one place
|
||||
- ✅ **Easy updates**: Change once, affects all components
|
||||
- ✅ **Clear structure**: Consistent file and component organization
|
||||
- ✅ **Type safety**: Full TypeScript support with proper interfaces
|
||||
|
||||
### **4. Performance**
|
||||
- ✅ **Optimized animations**: Efficient animation utilities
|
||||
- ✅ **Debounced operations**: Prevent excessive API calls
|
||||
- ✅ **Lazy loading**: Components load only when needed
|
||||
- ✅ **Memory management**: Proper cleanup in useEffect hooks
|
||||
|
||||
---
|
||||
|
||||
## **🚀 Migration Strategy**
|
||||
|
||||
### **Phase 1: Foundation (Complete)**
|
||||
- ✅ Create design system components
|
||||
- ✅ Implement utility functions
|
||||
- ✅ Create styling hook
|
||||
- ✅ Refactor ApiKeyStep as example
|
||||
|
||||
### **Phase 2: Component Migration**
|
||||
- [ ] Refactor WebsiteStep
|
||||
- [ ] Refactor ResearchStep
|
||||
- [ ] Refactor PersonalizationStep
|
||||
- [ ] Refactor IntegrationsStep
|
||||
- [ ] Refactor FinalStep
|
||||
|
||||
### **Phase 3: Enhancement**
|
||||
- [ ] Add more utility functions as needed
|
||||
- [ ] Create additional reusable components
|
||||
- [ ] Implement advanced animations
|
||||
- [ ] Add accessibility features
|
||||
|
||||
### **Phase 4: Testing & Optimization**
|
||||
- [ ] Add unit tests for utilities
|
||||
- [ ] Add integration tests for components
|
||||
- [ ] Performance optimization
|
||||
- [ ] Accessibility audit
|
||||
|
||||
---
|
||||
|
||||
## **📚 Usage Examples**
|
||||
|
||||
### **Creating a New Step**
|
||||
```typescript
|
||||
// 1. Import design system
|
||||
import { useOnboardingStyles } from './common/useOnboardingStyles';
|
||||
import { validateRequired, formatErrorMessage } from './common/onboardingUtils';
|
||||
|
||||
// 2. Use the styles hook
|
||||
const styles = useOnboardingStyles();
|
||||
|
||||
// 3. Implement consistent structure
|
||||
const NewStep: React.FC<StepProps> = ({ onContinue }) => {
|
||||
// State and logic
|
||||
return (
|
||||
<Fade in={true} timeout={500}>
|
||||
<Box sx={styles.container}>
|
||||
{/* Header */}
|
||||
{/* Content */}
|
||||
{/* Actions */}
|
||||
</Box>
|
||||
</Fade>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### **Adding New Utilities**
|
||||
```typescript
|
||||
// Add to onboardingUtils.ts
|
||||
export const validateEmail = (email: string): boolean => {
|
||||
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
|
||||
return emailRegex.test(email);
|
||||
};
|
||||
|
||||
export const formatPhoneNumber = (phone: string): string => {
|
||||
// Implementation
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This modular design system ensures that all onboarding steps are consistent, maintainable, and provide an excellent user experience while reducing development time and improving code quality.**
|
||||
@@ -1,194 +0,0 @@
|
||||
# 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.**
|
||||
@@ -1,127 +0,0 @@
|
||||
AI Writers
|
||||
=========
|
||||
|
||||
This section documents the AI writer modules that provide specialized content generation for different platforms.
|
||||
|
||||
LinkedIn Writer
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Post Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.post_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Article Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.article_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
LinkedIn Profile Optimizer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.linkedin_writer.modules.profile_optimizer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Twitter Writer
|
||||
------------
|
||||
|
||||
.. automodule:: lib.ai_writers.twitter_writers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Tweet Generator
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.twitter_writers.tweet_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Writer
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Ad Copy Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer.modules.ad_copy_generator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Facebook Carousel Generator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_facebook_writer.modules.facebook_carousel
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
YouTube Writers
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_writers.youtube_writers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Story Writer
|
||||
----------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_story_writer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Copywriter
|
||||
---------
|
||||
|
||||
.. automodule:: lib.ai_writers.ai_copywriter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Blog Writers
|
||||
----------
|
||||
|
||||
GitHub Blogs
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.github_blogs
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Scholar Blogs
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.scholar_blogs
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Speech to Blog
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.ai_writers.speech_to_blog
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,12 +0,0 @@
|
||||
Analytics
|
||||
=========
|
||||
|
||||
This section documents the analytics modules that provide content performance tracking and visualization.
|
||||
|
||||
Analytics Engine
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.analytics
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,51 +0,0 @@
|
||||
Core API
|
||||
========
|
||||
|
||||
This section documents the core modules of the AI-Writer platform.
|
||||
|
||||
Main Application
|
||||
--------------
|
||||
|
||||
.. automodule:: alwrity
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
GPT Providers
|
||||
-----------
|
||||
|
||||
Text Generation
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.gemini_pro_text
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.mistral_chat_completion
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_generation.deepseek_text_gen
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Image Generation
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.main_generate_image_from_prompt
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.gen_gemini_images
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.gpt_providers.text_to_image_generation.gen_dali3_images
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,22 +0,0 @@
|
||||
Database
|
||||
========
|
||||
|
||||
This section documents the database modules that handle content storage, retrieval, and vector search capabilities.
|
||||
|
||||
Database Models
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.database
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Vector Database
|
||||
-------------
|
||||
|
||||
The vector database provides semantic search capabilities for content retrieval.
|
||||
|
||||
.. automodule:: lib.workspace.alwrity_data.vectordb
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,83 +0,0 @@
|
||||
.. _api-reference:
|
||||
|
||||
API Reference
|
||||
============
|
||||
|
||||
This section provides detailed documentation for the AI-Writer API, including module references, class hierarchies, and function specifications.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: API Documentation:
|
||||
|
||||
core
|
||||
ai_writers
|
||||
database
|
||||
utils
|
||||
analytics
|
||||
web_crawlers
|
||||
|
||||
Core Modules
|
||||
-----------
|
||||
|
||||
.. automodule:: alwrity
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
AI Writers
|
||||
---------
|
||||
|
||||
The AI Writers modules provide specialized content generation for different platforms and content types.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ai_writers/linkedin
|
||||
ai_writers/twitter
|
||||
ai_writers/blog
|
||||
ai_writers/email
|
||||
|
||||
Database
|
||||
-------
|
||||
|
||||
The database modules handle content storage, retrieval, and vector search capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
database/models
|
||||
database/vector_store
|
||||
database/relational_store
|
||||
|
||||
Utilities
|
||||
--------
|
||||
|
||||
Utility modules provide supporting functionality across the application.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
utils/api_key_manager
|
||||
utils/ui_setup
|
||||
utils/seo_tools
|
||||
|
||||
Analytics
|
||||
--------
|
||||
|
||||
Analytics modules provide content performance tracking and visualization.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
analytics/content_analyzer
|
||||
analytics/analytics_ui
|
||||
|
||||
Web Crawlers
|
||||
-----------
|
||||
|
||||
Web crawler modules provide research capabilities by extracting information from the web.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
web_crawlers/async_web_crawler
|
||||
@@ -1,78 +0,0 @@
|
||||
Utilities
|
||||
=========
|
||||
|
||||
This section documents the utility modules that provide supporting functionality across the application.
|
||||
|
||||
API Key Manager
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.utils.api_key_manager
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Website Analyzer
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.utils.website_analyzer
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
UI Components
|
||||
-----------
|
||||
|
||||
.. automodule:: lib.alwrity_ui
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
SEO Tools
|
||||
--------
|
||||
|
||||
.. automodule:: lib.ai_seo_tools
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Marketing Tools
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.ai_marketing_tools
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Blog Processing
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.blog_metadata
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.blog_postprocessing
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: lib.blog_sections
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Content Planning
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.content_planning_calender
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Personalization
|
||||
-------------
|
||||
|
||||
.. automodule:: lib.personalization
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,28 +0,0 @@
|
||||
Web Crawlers
|
||||
============
|
||||
|
||||
This section documents the web crawler modules that provide research capabilities by extracting information from the web.
|
||||
|
||||
Web Researcher
|
||||
------------
|
||||
|
||||
.. automodule:: lib.ai_web_researcher
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Web Crawlers
|
||||
----------
|
||||
|
||||
.. automodule:: lib.web_crawlers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Research Storage
|
||||
--------------
|
||||
|
||||
.. automodule:: lib.workspace.alwrity_web_research
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -1,449 +0,0 @@
|
||||
API Design
|
||||
=========
|
||||
|
||||
This document outlines the API design principles and specifications for the AI-Writer platform.
|
||||
|
||||
API Design Principles
|
||||
-------------------
|
||||
|
||||
The AI-Writer API follows these core design principles:
|
||||
|
||||
1. **RESTful Architecture**
|
||||
|
||||
* Resource-oriented design
|
||||
* Standard HTTP methods (GET, POST, PUT, DELETE)
|
||||
* Consistent URL structure
|
||||
* Stateless interactions
|
||||
|
||||
2. **Consistent Response Format**
|
||||
|
||||
* JSON as the primary data format
|
||||
* Standard error response structure
|
||||
* Pagination for list endpoints
|
||||
* Hypermedia links where appropriate
|
||||
|
||||
3. **Versioning**
|
||||
|
||||
* API versioning in URL path (e.g., `/api/v1/`)
|
||||
* Backward compatibility within major versions
|
||||
* Deprecation notices before removing features
|
||||
|
||||
4. **Security**
|
||||
|
||||
* Authentication via API keys or OAuth 2.0
|
||||
* Rate limiting to prevent abuse
|
||||
* Input validation to prevent injection attacks
|
||||
* HTTPS for all communications
|
||||
|
||||
5. **Documentation**
|
||||
|
||||
* OpenAPI/Swagger specification
|
||||
* Interactive documentation
|
||||
* Code examples for common operations
|
||||
* Changelog for API updates
|
||||
|
||||
API Endpoints
|
||||
-----------
|
||||
|
||||
Content Management
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create content
|
||||
POST /api/v1/content
|
||||
|
||||
# Get content by ID
|
||||
GET /api/v1/content/{content_id}
|
||||
|
||||
# Update content
|
||||
PUT /api/v1/content/{content_id}
|
||||
|
||||
# Delete content
|
||||
DELETE /api/v1/content/{content_id}
|
||||
|
||||
# List content with filtering
|
||||
GET /api/v1/content?type={type}&limit={limit}&offset={offset}
|
||||
|
||||
# Get content versions
|
||||
GET /api/v1/content/{content_id}/versions
|
||||
|
||||
# Revert to specific version
|
||||
POST /api/v1/content/{content_id}/revert/{version_id}
|
||||
|
||||
AI Generation
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Generate content from keywords
|
||||
POST /api/v1/generate/content
|
||||
|
||||
# Generate blog post
|
||||
POST /api/v1/generate/blog
|
||||
|
||||
# Generate social media post
|
||||
POST /api/v1/generate/social
|
||||
|
||||
# Generate email
|
||||
POST /api/v1/generate/email
|
||||
|
||||
# Generate outline
|
||||
POST /api/v1/generate/outline
|
||||
|
||||
# Generate image for content
|
||||
POST /api/v1/generate/image
|
||||
|
||||
Web Research
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Perform web research
|
||||
POST /api/v1/research
|
||||
|
||||
# Get research results
|
||||
GET /api/v1/research/{research_id}
|
||||
|
||||
# Search previous research
|
||||
GET /api/v1/research/search?query={query}
|
||||
|
||||
SEO Tools
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Analyze content for SEO
|
||||
POST /api/v1/seo/analyze
|
||||
|
||||
# Generate meta description
|
||||
POST /api/v1/seo/meta-description
|
||||
|
||||
# Generate SEO-friendly title
|
||||
POST /api/v1/seo/title
|
||||
|
||||
# Generate structured data
|
||||
POST /api/v1/seo/structured-data
|
||||
|
||||
# Generate alt text for images
|
||||
POST /api/v1/seo/alt-text
|
||||
|
||||
User Management
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create user
|
||||
POST /api/v1/users
|
||||
|
||||
# Get user profile
|
||||
GET /api/v1/users/{user_id}
|
||||
|
||||
# Update user profile
|
||||
PUT /api/v1/users/{user_id}
|
||||
|
||||
# Delete user
|
||||
DELETE /api/v1/users/{user_id}
|
||||
|
||||
# Get user settings
|
||||
GET /api/v1/users/{user_id}/settings
|
||||
|
||||
# Update user settings
|
||||
PUT /api/v1/users/{user_id}/settings
|
||||
|
||||
API Key Management
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create API key
|
||||
POST /api/v1/api-keys
|
||||
|
||||
# List API keys
|
||||
GET /api/v1/api-keys
|
||||
|
||||
# Revoke API key
|
||||
DELETE /api/v1/api-keys/{key_id}
|
||||
|
||||
Analytics
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Get content analytics
|
||||
GET /api/v1/analytics/content/{content_id}
|
||||
|
||||
# Get user analytics
|
||||
GET /api/v1/analytics/user/{user_id}
|
||||
|
||||
# Get system analytics
|
||||
GET /api/v1/analytics/system
|
||||
|
||||
Request and Response Examples
|
||||
---------------------------
|
||||
|
||||
Create Content
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/content
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "c123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
},
|
||||
"created_at": "2023-01-01T12:00:00Z",
|
||||
"updated_at": "2023-01-01T12:00:00Z",
|
||||
"user_id": "u123e4567-e89b-12d3-a456-426614174000",
|
||||
"links": {
|
||||
"self": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000",
|
||||
"versions": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000/versions",
|
||||
"analytics": "/api/v1/analytics/content/c123e4567-e89b-12d3-a456-426614174000"
|
||||
}
|
||||
}
|
||||
|
||||
Generate Blog Post
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/generate/blog
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"include_research": true,
|
||||
"target_audience": "marketers"
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "g123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"content": "# The Future of Content Creation with AI\n\nArtificial intelligence is revolutionizing...",
|
||||
"metadata": {
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"word_count": 1250,
|
||||
"research_sources": [
|
||||
{
|
||||
"title": "AI in Content Marketing Report 2023",
|
||||
"url": "https://example.com/report",
|
||||
"accessed_at": "2023-01-01T10:30:00Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
"created_at": "2023-01-01T12:05:00Z",
|
||||
"links": {
|
||||
"save": "/api/v1/content",
|
||||
"regenerate": "/api/v1/generate/blog",
|
||||
"edit": "/api/v1/generate/edit"
|
||||
}
|
||||
}
|
||||
|
||||
Error Response
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"error": {
|
||||
"code": "invalid_request",
|
||||
"message": "The request was invalid",
|
||||
"details": [
|
||||
{
|
||||
"field": "keywords",
|
||||
"issue": "required",
|
||||
"description": "The keywords field is required"
|
||||
}
|
||||
]
|
||||
},
|
||||
"request_id": "req_123456",
|
||||
"documentation_url": "https://docs.alwrity.com/api/errors#invalid_request"
|
||||
}
|
||||
|
||||
API Authentication
|
||||
----------------
|
||||
|
||||
The AI-Writer API supports the following authentication methods:
|
||||
|
||||
1. **API Key Authentication**
|
||||
|
||||
* Include the API key in the Authorization header:
|
||||
`Authorization: Bearer {api_key}`
|
||||
* API keys can be generated and managed through the API or web interface
|
||||
* Different permission levels can be assigned to API keys
|
||||
|
||||
2. **OAuth 2.0 (for multi-user deployments)**
|
||||
|
||||
* Standard OAuth 2.0 flow with authorization code
|
||||
* Supports scopes for fine-grained permissions
|
||||
* Refresh token rotation for enhanced security
|
||||
|
||||
Rate Limiting
|
||||
-----------
|
||||
|
||||
To ensure fair usage and system stability, the API implements rate limiting:
|
||||
|
||||
* Rate limits are based on the user's plan
|
||||
* Limits are applied per API key
|
||||
* Rate limit information is included in response headers:
|
||||
* `X-RateLimit-Limit`: Total requests allowed in the current period
|
||||
* `X-RateLimit-Remaining`: Requests remaining in the current period
|
||||
* `X-RateLimit-Reset`: Time when the rate limit resets (Unix timestamp)
|
||||
|
||||
When a rate limit is exceeded, the API returns a 429 Too Many Requests response.
|
||||
|
||||
Pagination
|
||||
---------
|
||||
|
||||
List endpoints support pagination with the following parameters:
|
||||
|
||||
* `limit`: Number of items per page (default: 20, max: 100)
|
||||
* `offset`: Number of items to skip (for offset-based pagination)
|
||||
* `cursor`: Cursor for the next page (for cursor-based pagination)
|
||||
|
||||
Response includes pagination metadata:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"total": 45,
|
||||
"limit": 20,
|
||||
"offset": 0,
|
||||
"next_cursor": "cursor_for_next_page",
|
||||
"has_more": true
|
||||
}
|
||||
}
|
||||
|
||||
Filtering and Sorting
|
||||
-------------------
|
||||
|
||||
List endpoints support filtering and sorting:
|
||||
|
||||
* Filtering: `?field=value&another_field=another_value`
|
||||
* Range filtering: `?created_at_gte=2023-01-01&created_at_lte=2023-01-31`
|
||||
* Sorting: `?sort=field` (ascending) or `?sort=-field` (descending)
|
||||
* Multiple sort fields: `?sort=-created_at,title`
|
||||
|
||||
Versioning Strategy
|
||||
-----------------
|
||||
|
||||
The API uses a versioning strategy to ensure backward compatibility:
|
||||
|
||||
1. **Major Versions**
|
||||
|
||||
* Included in the URL path: `/api/v1/`, `/api/v2/`, etc.
|
||||
* Major versions may introduce breaking changes
|
||||
* Previous major versions are supported for at least 12 months after a new version is released
|
||||
|
||||
2. **Minor Updates**
|
||||
|
||||
* Backward-compatible changes within a major version
|
||||
* New endpoints or parameters may be added
|
||||
* Existing functionality remains unchanged
|
||||
|
||||
3. **Deprecation Process**
|
||||
|
||||
* Features to be removed are marked as deprecated
|
||||
* Deprecation notices are included in response headers
|
||||
* Deprecated features are supported for at least 6 months before removal
|
||||
|
||||
API Changelog
|
||||
-----------
|
||||
|
||||
The API changelog is maintained to track changes:
|
||||
|
||||
* **v1.0.0 (2023-01-01)**
|
||||
|
||||
* Initial release with core content management features
|
||||
* Basic AI generation capabilities
|
||||
* User management and authentication
|
||||
|
||||
* **v1.1.0 (2023-03-15)**
|
||||
|
||||
* Added SEO analysis endpoints
|
||||
* Enhanced content generation with research integration
|
||||
* Improved error handling and validation
|
||||
|
||||
* **v1.2.0 (2023-06-30)**
|
||||
|
||||
* Added analytics endpoints
|
||||
* Introduced cursor-based pagination
|
||||
* Added support for content versioning
|
||||
|
||||
Future API Roadmap
|
||||
----------------
|
||||
|
||||
Planned API enhancements:
|
||||
|
||||
1. **Content Collaboration**
|
||||
|
||||
* Endpoints for collaborative editing
|
||||
* Comment and feedback functionality
|
||||
* Role-based access control
|
||||
|
||||
2. **Advanced Analytics**
|
||||
|
||||
* Predictive performance metrics
|
||||
* Competitive analysis
|
||||
* Content optimization recommendations
|
||||
|
||||
3. **Workflow Automation**
|
||||
|
||||
* Scheduled content generation
|
||||
* Approval workflows
|
||||
* Integration with publishing platforms
|
||||
|
||||
4. **Multi-modal Content**
|
||||
|
||||
* Enhanced image generation
|
||||
* Audio content generation
|
||||
* Video script generation
|
||||
@@ -1,170 +0,0 @@
|
||||
Architecture Overview
|
||||
====================
|
||||
|
||||
This document provides a comprehensive overview of the AI-Writer architecture, explaining the system's components, their interactions, and the design principles behind the implementation.
|
||||
|
||||
High-Level Architecture
|
||||
----------------------
|
||||
|
||||
.. image:: diagrams/high_level_architecture.png
|
||||
:alt: High-level architecture diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The AI-Writer platform consists of several key components:
|
||||
|
||||
1. **User Interface Layer**
|
||||
|
||||
* Streamlit-based web interface
|
||||
* Command-line interface for automation
|
||||
* API endpoints for programmatic access
|
||||
|
||||
2. **Core Services Layer**
|
||||
|
||||
* AI Writers: Various specialized content generation modules
|
||||
* Web Research: Tools for gathering factual information from the internet
|
||||
* SEO Tools: Utilities for optimizing content for search engines
|
||||
* Analytics: Content performance tracking and analysis
|
||||
|
||||
3. **Data Storage Layer**
|
||||
|
||||
* Vector Database (ChromaDB): Stores embeddings for semantic search
|
||||
* Relational Database (SQLite): Stores structured data like user preferences and content metadata
|
||||
|
||||
4. **External Integrations Layer**
|
||||
|
||||
* LLM Providers: OpenAI, Google Gemini, Anthropic, etc.
|
||||
* Search Providers: Tavily, SerperDev, Exa, etc.
|
||||
* Image Generation: Stability AI
|
||||
* Publishing Platforms: WordPress, Jekyll, etc.
|
||||
|
||||
Database Architecture
|
||||
--------------------
|
||||
|
||||
.. image:: diagrams/database_architecture.png
|
||||
:alt: Database architecture diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The database architecture consists of two main components:
|
||||
|
||||
1. **Vector Storage**
|
||||
|
||||
* Uses ChromaDB for storing and retrieving text embeddings
|
||||
* Enables semantic search capabilities
|
||||
* Stores content in collections for efficient retrieval
|
||||
|
||||
2. **Relational Storage**
|
||||
|
||||
* Uses SQLite for structured data storage
|
||||
* Key models include:
|
||||
- User: Stores user preferences and settings
|
||||
- ContentItem: Represents content created by users
|
||||
- ContentVersion: Tracks version history of content
|
||||
- Analytics: Stores performance metrics for content
|
||||
|
||||
Content Generation Workflow
|
||||
--------------------------
|
||||
|
||||
.. image:: diagrams/content_generation_workflow.png
|
||||
:alt: Content generation workflow diagram of AI-Writer
|
||||
:width: 100%
|
||||
|
||||
The content generation process follows these steps:
|
||||
|
||||
1. **Input Phase**
|
||||
|
||||
* User provides keywords, topics, or other input parameters
|
||||
* System configures the generation process based on user preferences
|
||||
|
||||
2. **Research Phase**
|
||||
|
||||
* Web research is conducted using various search providers
|
||||
* Relevant information is gathered and processed
|
||||
* Facts are extracted and organized for use in content generation
|
||||
|
||||
3. **Content Creation Phase**
|
||||
|
||||
* Content outline is generated based on research
|
||||
* Initial draft is created using AI models
|
||||
* Final content is refined and polished
|
||||
|
||||
4. **Enhancement Phase**
|
||||
|
||||
* SEO optimization is applied to improve search visibility
|
||||
* Images are generated or selected to complement the content
|
||||
* Metadata is generated for better categorization and discovery
|
||||
|
||||
5. **Storage Phase**
|
||||
|
||||
* Content is stored in both vector and relational databases
|
||||
* Embeddings are created for semantic search capabilities
|
||||
* Metadata is indexed for efficient retrieval
|
||||
|
||||
6. **Publishing Phase**
|
||||
|
||||
* Content is formatted for the target platform
|
||||
* Publishing options include WordPress, Markdown, and others
|
||||
* Content is delivered to the user or published directly
|
||||
|
||||
Design Principles
|
||||
----------------
|
||||
|
||||
The AI-Writer architecture is built on the following design principles:
|
||||
|
||||
1. **Modularity**
|
||||
|
||||
* Components are designed to be independent and interchangeable
|
||||
* New AI models and services can be added with minimal changes
|
||||
* Functionality is organized into logical modules
|
||||
|
||||
2. **Extensibility**
|
||||
|
||||
* The system is designed to be easily extended with new features
|
||||
* Plugin architecture allows for custom integrations
|
||||
* Configuration options enable customization without code changes
|
||||
|
||||
3. **Reliability**
|
||||
|
||||
* Error handling is implemented throughout the system
|
||||
* Fallback mechanisms ensure continued operation
|
||||
* Logging provides visibility into system behavior
|
||||
|
||||
4. **Performance**
|
||||
|
||||
* Caching is used to improve response times
|
||||
* Asynchronous processing for long-running tasks
|
||||
* Efficient data storage and retrieval mechanisms
|
||||
|
||||
5. **Security**
|
||||
|
||||
* API keys are securely stored and managed
|
||||
* User data is protected with appropriate measures
|
||||
* Input validation prevents common security issues
|
||||
|
||||
Future Architecture Enhancements
|
||||
-------------------------------
|
||||
|
||||
Planned improvements to the architecture include:
|
||||
|
||||
1. **Distributed Processing**
|
||||
|
||||
* Support for distributed content generation
|
||||
* Load balancing for improved scalability
|
||||
* Parallel processing of research and generation tasks
|
||||
|
||||
2. **Advanced Caching**
|
||||
|
||||
* Intelligent caching of common queries and results
|
||||
* Cache invalidation strategies for fresh content
|
||||
* Distributed cache for multi-user environments
|
||||
|
||||
3. **Enhanced Security**
|
||||
|
||||
* Role-based access control
|
||||
* End-to-end encryption for sensitive data
|
||||
* Advanced authentication mechanisms
|
||||
|
||||
4. **Containerization**
|
||||
|
||||
* Docker containers for easier deployment
|
||||
* Kubernetes support for orchestration
|
||||
* Microservices architecture for better scalability
|
||||
@@ -1,171 +0,0 @@
|
||||
Component Diagram
|
||||
================
|
||||
|
||||
This document provides detailed information about the components of the AI-Writer system and their interactions.
|
||||
|
||||
Core Components
|
||||
--------------
|
||||
|
||||
AI Writers
|
||||
~~~~~~~~~~
|
||||
|
||||
The AI Writers component is responsible for generating various types of content using AI models. It includes several specialized writers:
|
||||
|
||||
- **Blog Writer**: Generates blog posts based on keywords and web research
|
||||
- **News Article Writer**: Creates news articles with citations from current events
|
||||
- **Social Media Writer**: Produces content for various social platforms
|
||||
- **Email Writer**: Generates professional and business emails
|
||||
- **Story Writer**: Creates narrative content based on user input
|
||||
- **YouTube Script Writer**: Develops scripts for video content
|
||||
|
||||
Each writer implements a common interface but has specialized logic for its specific content type. The writers interact with LLM providers through a unified API layer that handles authentication, rate limiting, and error handling.
|
||||
|
||||
Web Research
|
||||
~~~~~~~~~~~
|
||||
|
||||
The Web Research component gathers information from the internet to provide factual context for content generation. It includes:
|
||||
|
||||
- **SERP Integration**: Retrieves search engine results
|
||||
- **Tavily Integration**: Uses AI-powered search for relevant information
|
||||
- **Exa Integration**: Performs semantic search for related content
|
||||
- **Web Crawler**: Extracts content from specified URLs
|
||||
- **Content Analyzer**: Processes and summarizes gathered information
|
||||
|
||||
This component ensures that generated content is factually accurate and up-to-date by providing relevant research data to the AI Writers.
|
||||
|
||||
SEO Tools
|
||||
~~~~~~~~~
|
||||
|
||||
The SEO Tools component provides utilities for optimizing content for search engines:
|
||||
|
||||
- **Keyword Analyzer**: Identifies and analyzes target keywords
|
||||
- **Meta Description Generator**: Creates SEO-friendly meta descriptions
|
||||
- **Title Generator**: Produces optimized titles for content
|
||||
- **Structured Data Generator**: Creates schema markup for rich snippets
|
||||
- **Image Optimizer**: Optimizes images for web performance
|
||||
- **On-Page SEO Analyzer**: Evaluates content for SEO best practices
|
||||
|
||||
These tools work together to ensure that generated content has the best chance of ranking well in search engines.
|
||||
|
||||
Analytics
|
||||
~~~~~~~~
|
||||
|
||||
The Analytics component tracks and analyzes content performance:
|
||||
|
||||
- **Content Metrics**: Measures readability, engagement potential, and other metrics
|
||||
- **Performance Tracker**: Monitors content performance over time
|
||||
- **Recommendation Engine**: Suggests improvements based on analytics
|
||||
- **Report Generator**: Creates reports on content effectiveness
|
||||
|
||||
This component helps users understand how their content is performing and how it can be improved.
|
||||
|
||||
Data Storage
|
||||
-----------
|
||||
|
||||
Vector Database
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The Vector Database component uses ChromaDB to store and retrieve text embeddings:
|
||||
|
||||
- **Embedding Generator**: Creates vector representations of text
|
||||
- **Collection Manager**: Organizes embeddings into collections
|
||||
- **Semantic Search**: Performs similarity searches on embeddings
|
||||
- **Metadata Manager**: Associates metadata with embeddings
|
||||
|
||||
This component enables semantic search capabilities, allowing users to find content based on meaning rather than just keywords.
|
||||
|
||||
Relational Database
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Relational Database component uses SQLite to store structured data:
|
||||
|
||||
- **User Manager**: Handles user data and preferences
|
||||
- **Content Repository**: Stores content items and metadata
|
||||
- **Version Control**: Tracks content versions and changes
|
||||
- **Analytics Storage**: Stores performance metrics and analytics data
|
||||
|
||||
This component provides persistent storage for all structured data in the system.
|
||||
|
||||
External Integrations
|
||||
--------------------
|
||||
|
||||
LLM Providers
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The LLM Providers component integrates with various AI models:
|
||||
|
||||
- **OpenAI Integration**: Connects to GPT models
|
||||
- **Google Gemini Integration**: Interfaces with Gemini models
|
||||
- **Anthropic Integration**: Works with Claude models
|
||||
- **Ollama Integration**: Supports local LLM deployment
|
||||
|
||||
This component provides a unified interface to different AI models, allowing the system to use the best model for each task.
|
||||
|
||||
Search Providers
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The Search Providers component connects to external search services:
|
||||
|
||||
- **Tavily Client**: Interfaces with Tavily AI search
|
||||
- **SerperDev Client**: Connects to SerperDev API
|
||||
- **Exa Client**: Integrates with Exa search API
|
||||
- **Google Search Client**: Provides access to Google search results
|
||||
|
||||
These integrations enable the system to gather relevant information from the internet for content generation.
|
||||
|
||||
Image Generation
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The Image Generation component creates images to complement content:
|
||||
|
||||
- **Stability AI Integration**: Connects to Stable Diffusion models
|
||||
- **DALL-E Integration**: Interfaces with OpenAI's DALL-E
|
||||
- **Image Processor**: Optimizes and formats generated images
|
||||
- **Image Repository**: Stores and manages generated images
|
||||
|
||||
This component enhances content with relevant visuals, improving engagement and comprehension.
|
||||
|
||||
Publishing Platforms
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Publishing Platforms component enables content distribution:
|
||||
|
||||
- **WordPress Integration**: Publishes content to WordPress sites
|
||||
- **Markdown Exporter**: Creates Markdown files for static sites
|
||||
- **HTML Exporter**: Generates HTML for web publishing
|
||||
- **API Connectors**: Interfaces with various content platforms
|
||||
|
||||
This component streamlines the process of publishing generated content to various platforms.
|
||||
|
||||
Component Interactions
|
||||
---------------------
|
||||
|
||||
Content Generation Flow
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. User provides input parameters through the UI
|
||||
2. Web Research gathers relevant information
|
||||
3. AI Writers generate content using research data and LLM providers
|
||||
4. SEO Tools optimize the content for search engines
|
||||
5. Content is stored in both Vector and Relational databases
|
||||
6. Analytics evaluates the content quality and potential performance
|
||||
7. Content is prepared for publishing through the Publishing Platforms
|
||||
|
||||
Data Flow
|
||||
~~~~~~~~~
|
||||
|
||||
1. User preferences and settings flow from UI to Relational Database
|
||||
2. Research data flows from Web Research to AI Writers
|
||||
3. Generated content flows from AI Writers to SEO Tools
|
||||
4. Optimized content flows to Data Storage components
|
||||
5. Content metrics flow from Analytics to Relational Database
|
||||
6. Published content flows from Publishing Platforms to external systems
|
||||
|
||||
Error Handling
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. LLM provider errors are handled by fallback mechanisms
|
||||
2. Web Research failures trigger alternative search methods
|
||||
3. Database errors are logged and retried with exponential backoff
|
||||
4. Publishing failures are queued for retry
|
||||
5. All errors are logged for monitoring and debugging
|
||||
@@ -1,442 +0,0 @@
|
||||
Database Schema
|
||||
==============
|
||||
|
||||
This document describes the database schema used in the AI-Writer platform, including both the relational database and vector database components.
|
||||
|
||||
Relational Database Schema
|
||||
------------------------
|
||||
|
||||
AI-Writer uses SQLAlchemy ORM to interact with the relational database. The schema consists of the following main tables:
|
||||
|
||||
User
|
||||
~~~~
|
||||
|
||||
Stores user information and preferences.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class User(Base):
|
||||
__tablename__ = "users"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
username = Column(String, unique=True, nullable=False)
|
||||
email = Column(String, unique=True, nullable=False)
|
||||
password_hash = Column(String, nullable=False)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
api_keys = relationship("ApiKey", back_populates="user")
|
||||
contents = relationship("Content", back_populates="user")
|
||||
settings = relationship("UserSetting", back_populates="user", uselist=False)
|
||||
|
||||
ApiKey
|
||||
~~~~~~
|
||||
|
||||
Stores encrypted API keys for various services.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ApiKey(Base):
|
||||
__tablename__ = "api_keys"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
service_name = Column(String, nullable=False)
|
||||
encrypted_key = Column(String, nullable=False)
|
||||
is_active = Column(Boolean, default=True)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="api_keys")
|
||||
|
||||
Content
|
||||
~~~~~~~
|
||||
|
||||
Stores generated content with metadata.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Content(Base):
|
||||
__tablename__ = "contents"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
title = Column(String, nullable=False)
|
||||
content_type = Column(String, nullable=False) # blog, linkedin, twitter, etc.
|
||||
content_text = Column(Text, nullable=False)
|
||||
metadata = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="contents")
|
||||
versions = relationship("ContentVersion", back_populates="content")
|
||||
analytics = relationship("ContentAnalytics", back_populates="content")
|
||||
|
||||
ContentVersion
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Tracks versions of content for history and rollback.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentVersion(Base):
|
||||
__tablename__ = "content_versions"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_id = Column(Integer, ForeignKey("contents.id"))
|
||||
version_number = Column(Integer, nullable=False)
|
||||
content_text = Column(Text, nullable=False)
|
||||
metadata = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content = relationship("Content", back_populates="versions")
|
||||
|
||||
ContentAnalytics
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Stores analytics data for content performance.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentAnalytics(Base):
|
||||
__tablename__ = "content_analytics"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_id = Column(Integer, ForeignKey("contents.id"))
|
||||
views = Column(Integer, default=0)
|
||||
likes = Column(Integer, default=0)
|
||||
shares = Column(Integer, default=0)
|
||||
comments = Column(Integer, default=0)
|
||||
engagement_rate = Column(Float, default=0.0)
|
||||
last_updated = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content = relationship("Content", back_populates="analytics")
|
||||
|
||||
UserSetting
|
||||
~~~~~~~~~~
|
||||
|
||||
Stores user preferences and settings.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class UserSetting(Base):
|
||||
__tablename__ = "user_settings"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"), unique=True)
|
||||
preferred_ai_provider = Column(String)
|
||||
default_content_type = Column(String)
|
||||
ui_theme = Column(String, default="light")
|
||||
language = Column(String, default="en")
|
||||
settings_json = Column(JSON)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="settings")
|
||||
|
||||
Template
|
||||
~~~~~~~
|
||||
|
||||
Stores reusable content templates.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Template(Base):
|
||||
__tablename__ = "templates"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
name = Column(String, nullable=False)
|
||||
content_type = Column(String, nullable=False)
|
||||
template_text = Column(Text, nullable=False)
|
||||
variables = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User")
|
||||
|
||||
ContentGapAnalysis
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Stores content gap analysis results.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentGapAnalysis(Base):
|
||||
__tablename__ = "content_gap_analyses"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"))
|
||||
website_url = Column(String, nullable=False)
|
||||
industry = Column(String, nullable=False)
|
||||
analysis_date = Column(DateTime, default=datetime.utcnow)
|
||||
status = Column(String, nullable=False) # completed, in_progress, failed
|
||||
metadata = Column(JSON)
|
||||
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="content_gap_analyses")
|
||||
website_analysis = relationship("WebsiteAnalysis", back_populates="content_gap_analysis")
|
||||
competitor_analysis = relationship("CompetitorAnalysis", back_populates="content_gap_analysis")
|
||||
keyword_analysis = relationship("KeywordAnalysis", back_populates="content_gap_analysis")
|
||||
recommendations = relationship("ContentRecommendation", back_populates="content_gap_analysis")
|
||||
|
||||
WebsiteAnalysis
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Stores website analysis results.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class WebsiteAnalysis(Base):
|
||||
__tablename__ = "website_analyses"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_gap_analysis_id = Column(Integer, ForeignKey("content_gap_analyses.id"))
|
||||
content_score = Column(Float)
|
||||
seo_score = Column(Float)
|
||||
structure_score = Column(Float)
|
||||
content_metrics = Column(JSON)
|
||||
seo_metrics = Column(JSON)
|
||||
technical_metrics = Column(JSON)
|
||||
ai_insights = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content_gap_analysis = relationship("ContentGapAnalysis", back_populates="website_analysis")
|
||||
|
||||
CompetitorAnalysis
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Stores competitor analysis results.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class CompetitorAnalysis(Base):
|
||||
__tablename__ = "competitor_analyses"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_gap_analysis_id = Column(Integer, ForeignKey("content_gap_analyses.id"))
|
||||
competitor_url = Column(String, nullable=False)
|
||||
market_position = Column(JSON)
|
||||
content_gaps = Column(JSON)
|
||||
competitive_advantages = Column(JSON)
|
||||
trend_analysis = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content_gap_analysis = relationship("ContentGapAnalysis", back_populates="competitor_analysis")
|
||||
|
||||
KeywordAnalysis
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Stores keyword analysis results.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class KeywordAnalysis(Base):
|
||||
__tablename__ = "keyword_analyses"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_gap_analysis_id = Column(Integer, ForeignKey("content_gap_analyses.id"))
|
||||
top_keywords = Column(JSON)
|
||||
search_intent = Column(JSON)
|
||||
opportunities = Column(JSON)
|
||||
trend_analysis = Column(JSON)
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content_gap_analysis = relationship("ContentGapAnalysis", back_populates="keyword_analysis")
|
||||
|
||||
ContentRecommendation
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Stores content recommendations.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class ContentRecommendation(Base):
|
||||
__tablename__ = "content_recommendations"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_gap_analysis_id = Column(Integer, ForeignKey("content_gap_analyses.id"))
|
||||
recommendation_type = Column(String, nullable=False) # content, seo, technical, etc.
|
||||
priority_score = Column(Float)
|
||||
recommendation = Column(Text, nullable=False)
|
||||
implementation_steps = Column(JSON)
|
||||
expected_impact = Column(JSON)
|
||||
status = Column(String, nullable=False) # pending, in_progress, completed, rejected
|
||||
created_at = Column(DateTime, default=datetime.utcnow)
|
||||
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
|
||||
|
||||
# Relationships
|
||||
content_gap_analysis = relationship("ContentGapAnalysis", back_populates="recommendations")
|
||||
|
||||
AnalysisHistory
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Tracks the history of analysis runs.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class AnalysisHistory(Base):
|
||||
__tablename__ = "analysis_histories"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
content_gap_analysis_id = Column(Integer, ForeignKey("content_gap_analyses.id"))
|
||||
run_date = Column(DateTime, default=datetime.utcnow)
|
||||
status = Column(String, nullable=False) # completed, in_progress, failed
|
||||
metrics = Column(JSON) # Performance metrics for the analysis run
|
||||
error_log = Column(Text) # Any errors encountered during analysis
|
||||
|
||||
# Relationships
|
||||
content_gap_analysis = relationship("ContentGapAnalysis")
|
||||
|
||||
Vector Database Schema
|
||||
--------------------
|
||||
|
||||
AI-Writer uses ChromaDB for vector storage, which enables semantic search and retrieval of content. The vector database stores:
|
||||
|
||||
1. **Content Embeddings**
|
||||
|
||||
* Generated from content text using embedding models
|
||||
* Used for semantic search and content similarity
|
||||
|
||||
2. **Metadata**
|
||||
|
||||
* Content ID (linking to relational database)
|
||||
* Content type
|
||||
* Creation date
|
||||
* Keywords and tags
|
||||
|
||||
3. **Collections**
|
||||
|
||||
ChromaDB organizes embeddings into collections:
|
||||
|
||||
* `content_embeddings`: Main collection for all content
|
||||
* `user_{user_id}_content`: Per-user content collections
|
||||
* `{content_type}_embeddings`: Collections by content type
|
||||
|
||||
Vector Database Operations
|
||||
------------------------
|
||||
|
||||
The vector database supports the following operations:
|
||||
|
||||
1. **Adding Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def add_content_to_vector_db(content_id, content_text, metadata):
|
||||
"""Add content to the vector database.
|
||||
|
||||
Args:
|
||||
content_id: The ID of the content in the relational database.
|
||||
content_text: The text content to embed.
|
||||
metadata: Additional metadata for the content.
|
||||
"""
|
||||
embeddings = get_embeddings(content_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
collection.add(
|
||||
ids=[str(content_id)],
|
||||
embeddings=[embeddings],
|
||||
metadatas=[metadata],
|
||||
documents=[content_text]
|
||||
)
|
||||
|
||||
2. **Searching Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def search_similar_content(query_text, limit=5):
|
||||
"""Search for similar content using vector similarity.
|
||||
|
||||
Args:
|
||||
query_text: The query text to search for.
|
||||
limit: Maximum number of results to return.
|
||||
|
||||
Returns:
|
||||
List of similar content items with their similarity scores.
|
||||
"""
|
||||
query_embedding = get_embeddings(query_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
results = collection.query(
|
||||
query_embeddings=[query_embedding],
|
||||
n_results=limit
|
||||
)
|
||||
return results
|
||||
|
||||
3. **Updating Content**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def update_content_in_vector_db(content_id, new_content_text, metadata):
|
||||
"""Update content in the vector database.
|
||||
|
||||
Args:
|
||||
content_id: The ID of the content to update.
|
||||
new_content_text: The updated text content.
|
||||
metadata: Updated metadata.
|
||||
"""
|
||||
new_embedding = get_embeddings(new_content_text)
|
||||
collection = get_collection("content_embeddings")
|
||||
collection.update(
|
||||
ids=[str(content_id)],
|
||||
embeddings=[new_embedding],
|
||||
metadatas=[metadata],
|
||||
documents=[new_content_text]
|
||||
)
|
||||
|
||||
Database Migrations
|
||||
-----------------
|
||||
|
||||
AI-Writer uses Alembic for database migrations. The migration workflow is:
|
||||
|
||||
1. **Create Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic revision --autogenerate -m "Description of changes"
|
||||
|
||||
2. **Apply Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic upgrade head
|
||||
|
||||
3. **Rollback Migration**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
alembic downgrade -1
|
||||
|
||||
Database Backup and Restore
|
||||
-------------------------
|
||||
|
||||
Regular database backups are recommended:
|
||||
|
||||
1. **SQLite Backup**
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Backup
|
||||
sqlite3 data/alwrity.db .dump > backup.sql
|
||||
|
||||
# Restore
|
||||
sqlite3 data/alwrity.db < backup.sql
|
||||
|
||||
2. **Vector Database Backup**
|
||||
|
||||
ChromaDB data is stored in the specified directory and can be backed up by copying the directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Backup
|
||||
cp -r data/vectordb data/vectordb_backup
|
||||
|
||||
# Restore
|
||||
rm -rf data/vectordb
|
||||
cp -r data/vectordb_backup data/vectordb
|
||||
@@ -1,571 +0,0 @@
|
||||
Deployment Architecture
|
||||
=====================
|
||||
|
||||
This document outlines the deployment architecture for the AI-Writer platform, including deployment models, infrastructure requirements, and operational considerations.
|
||||
|
||||
Deployment Models
|
||||
---------------
|
||||
|
||||
AI-Writer supports multiple deployment models to accommodate different user needs and scale requirements:
|
||||
|
||||
Single-User Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Ideal for individual content creators or small teams:
|
||||
|
||||
1. **Local Installation**
|
||||
|
||||
* Runs on a single machine
|
||||
* SQLite database for data storage
|
||||
* Local file system for content storage
|
||||
* Minimal resource requirements
|
||||
|
||||
2. **Configuration**
|
||||
|
||||
* Simple configuration file
|
||||
* Environment variables for API keys
|
||||
* Local storage paths
|
||||
* Logging configuration
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 2+ cores
|
||||
* RAM: 4GB minimum (8GB recommended)
|
||||
* Storage: 10GB minimum
|
||||
* Python 3.9+ runtime
|
||||
|
||||
Multi-User Deployment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Suitable for teams and organizations:
|
||||
|
||||
1. **Server Deployment**
|
||||
|
||||
* Dedicated server or cloud instance
|
||||
* PostgreSQL database
|
||||
* Shared file storage
|
||||
* Web server (Nginx/Apache) with WSGI/ASGI
|
||||
|
||||
2. **Docker Deployment**
|
||||
|
||||
* Containerized application
|
||||
* Docker Compose for orchestration
|
||||
* Persistent volumes for data
|
||||
* Separate containers for services
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 4+ cores
|
||||
* RAM: 16GB minimum
|
||||
* Storage: 50GB+ SSD
|
||||
* Network: 100Mbps+ bandwidth
|
||||
|
||||
Enterprise Deployment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For large organizations with high volume requirements:
|
||||
|
||||
1. **Kubernetes Deployment**
|
||||
|
||||
* Containerized microservices
|
||||
* Horizontal scaling
|
||||
* Load balancing
|
||||
* High availability configuration
|
||||
|
||||
2. **Database Scaling**
|
||||
|
||||
* Database clustering
|
||||
* Read replicas
|
||||
* Connection pooling
|
||||
* Automated backups
|
||||
|
||||
3. **Resource Requirements**
|
||||
|
||||
* CPU: 8+ cores per node
|
||||
* RAM: 32GB+ per node
|
||||
* Storage: 100GB+ SSD with high IOPS
|
||||
* Network: 1Gbps+ bandwidth
|
||||
|
||||
Infrastructure Components
|
||||
-----------------------
|
||||
|
||||
Core Components
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Application Servers**
|
||||
|
||||
* Runs the AI-Writer application code
|
||||
* Handles HTTP requests
|
||||
* Processes content generation tasks
|
||||
* Manages user sessions
|
||||
|
||||
2. **Database Servers**
|
||||
|
||||
* Stores relational data (SQLite/PostgreSQL)
|
||||
* Stores vector embeddings (ChromaDB)
|
||||
* Handles data persistence
|
||||
* Manages transactions and concurrency
|
||||
|
||||
3. **File Storage**
|
||||
|
||||
* Stores generated content
|
||||
* Stores uploaded files
|
||||
* Manages file versioning
|
||||
* Handles file access control
|
||||
|
||||
4. **Web Servers**
|
||||
|
||||
* Handles HTTP/HTTPS traffic
|
||||
* SSL termination
|
||||
* Static file serving
|
||||
* Request routing
|
||||
|
||||
Optional Components
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Cache Servers**
|
||||
|
||||
* Redis for caching
|
||||
* Session storage
|
||||
* Rate limiting
|
||||
* Task queuing
|
||||
|
||||
2. **Background Workers**
|
||||
|
||||
* Processes asynchronous tasks
|
||||
* Handles long-running operations
|
||||
* Manages scheduled jobs
|
||||
* Processes content generation queue
|
||||
|
||||
3. **Load Balancers**
|
||||
|
||||
* Distributes traffic across servers
|
||||
* Health checking
|
||||
* SSL termination
|
||||
* DDoS protection
|
||||
|
||||
4. **Monitoring Services**
|
||||
|
||||
* Application performance monitoring
|
||||
* Log aggregation
|
||||
* Metrics collection
|
||||
* Alerting
|
||||
|
||||
Deployment Topologies
|
||||
-------------------
|
||||
|
||||
Basic Topology
|
||||
~~~~~~~~~~~~
|
||||
|
||||
For single-user or small team deployments:
|
||||
|
||||
```
|
||||
[User] → [Web Server] → [AI-Writer Application] → [SQLite/PostgreSQL]
|
||||
→ [File Storage]
|
||||
→ [External APIs]
|
||||
```
|
||||
|
||||
Standard Topology
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
For multi-user deployments:
|
||||
|
||||
```
|
||||
[Users] → [Load Balancer] → [Web Servers] → [Application Servers] → [PostgreSQL Cluster]
|
||||
→ [Background Workers] → [File Storage]
|
||||
→ [Redis Cache]
|
||||
→ [External APIs]
|
||||
```
|
||||
|
||||
High-Availability Topology
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For enterprise deployments:
|
||||
|
||||
```
|
||||
[Users] → [CDN] → [Load Balancer] → [Web Servers (Multiple AZs)]
|
||||
→ [Application Servers (Multiple AZs)]
|
||||
→ [Background Workers (Multiple AZs)]
|
||||
→ [PostgreSQL (Primary + Replicas)]
|
||||
→ [Redis Cluster]
|
||||
→ [Distributed File Storage]
|
||||
→ [External APIs with Fallbacks]
|
||||
```
|
||||
|
||||
Deployment Process
|
||||
----------------
|
||||
|
||||
Installation Methods
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Manual Installation**
|
||||
|
||||
* Clone repository
|
||||
* Install dependencies
|
||||
* Configure environment
|
||||
* Initialize database
|
||||
* Start application
|
||||
|
||||
2. **Docker Installation**
|
||||
|
||||
* Pull Docker images
|
||||
* Configure Docker Compose
|
||||
* Start containers
|
||||
* Initialize services
|
||||
* Configure networking
|
||||
|
||||
3. **Kubernetes Installation**
|
||||
|
||||
* Apply Kubernetes manifests
|
||||
* Configure Helm charts
|
||||
* Set up persistent volumes
|
||||
* Configure ingress
|
||||
* Deploy services
|
||||
|
||||
Configuration Management
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Environment Variables**
|
||||
|
||||
* API keys and credentials
|
||||
* Database connection strings
|
||||
* Service endpoints
|
||||
* Feature flags
|
||||
|
||||
2. **Configuration Files**
|
||||
|
||||
* Application settings
|
||||
* Logging configuration
|
||||
* Database settings
|
||||
* Cache settings
|
||||
|
||||
3. **Secrets Management**
|
||||
|
||||
* Kubernetes secrets
|
||||
* Docker secrets
|
||||
* Vault integration
|
||||
* Encrypted configuration
|
||||
|
||||
Continuous Integration/Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **CI Pipeline**
|
||||
|
||||
* Automated testing
|
||||
* Code quality checks
|
||||
* Security scanning
|
||||
* Build artifacts
|
||||
|
||||
2. **CD Pipeline**
|
||||
|
||||
* Automated deployment
|
||||
* Blue/green deployment
|
||||
* Canary releases
|
||||
* Rollback capability
|
||||
|
||||
3. **Infrastructure as Code**
|
||||
|
||||
* Terraform for infrastructure
|
||||
* Ansible for configuration
|
||||
* Helm charts for Kubernetes
|
||||
* Docker Compose for local deployment
|
||||
|
||||
Operational Considerations
|
||||
------------------------
|
||||
|
||||
Monitoring and Logging
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Application Monitoring**
|
||||
|
||||
* Performance metrics
|
||||
* Error tracking
|
||||
* User activity
|
||||
* API usage
|
||||
|
||||
2. **Infrastructure Monitoring**
|
||||
|
||||
* Resource utilization
|
||||
* Network traffic
|
||||
* Database performance
|
||||
* Storage capacity
|
||||
|
||||
3. **Logging Strategy**
|
||||
|
||||
* Centralized log collection
|
||||
* Structured logging
|
||||
* Log retention policy
|
||||
* Log analysis tools
|
||||
|
||||
Backup and Recovery
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Database Backups**
|
||||
|
||||
* Regular automated backups
|
||||
* Point-in-time recovery
|
||||
* Backup verification
|
||||
* Off-site backup storage
|
||||
|
||||
2. **File Storage Backups**
|
||||
|
||||
* Incremental backups
|
||||
* Version history
|
||||
* Disaster recovery
|
||||
* Backup encryption
|
||||
|
||||
3. **Recovery Procedures**
|
||||
|
||||
* Database restoration
|
||||
* File recovery
|
||||
* System rebuild
|
||||
* Disaster recovery testing
|
||||
|
||||
Scaling Strategies
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Vertical Scaling**
|
||||
|
||||
* Increase resources for existing servers
|
||||
* Upgrade database instances
|
||||
* Enhance storage performance
|
||||
* Optimize application code
|
||||
|
||||
2. **Horizontal Scaling**
|
||||
|
||||
* Add application servers
|
||||
* Database read replicas
|
||||
* Distributed caching
|
||||
* Load balancing
|
||||
|
||||
3. **Auto-scaling**
|
||||
|
||||
* Scale based on CPU/memory usage
|
||||
* Scale based on request volume
|
||||
* Scheduled scaling for predictable loads
|
||||
* Scale to zero for development environments
|
||||
|
||||
Security Considerations
|
||||
--------------------
|
||||
|
||||
Network Security
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Firewall Configuration**
|
||||
|
||||
* Restrict access to necessary ports
|
||||
* Implement network segmentation
|
||||
* Configure security groups
|
||||
* DDoS protection
|
||||
|
||||
2. **TLS Configuration**
|
||||
|
||||
* TLS 1.3 support
|
||||
* Strong cipher suites
|
||||
* Certificate management
|
||||
* HSTS implementation
|
||||
|
||||
3. **VPN Access**
|
||||
|
||||
* Secure administrative access
|
||||
* Multi-factor authentication
|
||||
* Access logging
|
||||
* Role-based access control
|
||||
|
||||
Data Security
|
||||
~~~~~~~~~~
|
||||
|
||||
1. **Data Encryption**
|
||||
|
||||
* Encryption in transit
|
||||
* Encryption at rest
|
||||
* Key management
|
||||
* Regular key rotation
|
||||
|
||||
2. **Access Controls**
|
||||
|
||||
* Principle of least privilege
|
||||
* Role-based access
|
||||
* Regular access reviews
|
||||
* Privileged access management
|
||||
|
||||
3. **Compliance**
|
||||
|
||||
* Data residency requirements
|
||||
* Regulatory compliance
|
||||
* Privacy regulations
|
||||
* Security certifications
|
||||
|
||||
Deployment Checklist
|
||||
------------------
|
||||
|
||||
Pre-Deployment
|
||||
~~~~~~~~~~~~
|
||||
|
||||
1. **Environment Preparation**
|
||||
|
||||
* Verify infrastructure requirements
|
||||
* Configure networking
|
||||
* Set up security controls
|
||||
* Prepare databases
|
||||
|
||||
2. **Application Preparation**
|
||||
|
||||
* Verify application version
|
||||
* Check dependencies
|
||||
* Prepare configuration
|
||||
* Test in staging environment
|
||||
|
||||
3. **Documentation**
|
||||
|
||||
* Update deployment documentation
|
||||
* Prepare rollback procedures
|
||||
* Document configuration changes
|
||||
* Update user documentation
|
||||
|
||||
Deployment
|
||||
~~~~~~~~~
|
||||
|
||||
1. **Backup**
|
||||
|
||||
* Backup existing data
|
||||
* Backup configuration
|
||||
* Verify backup integrity
|
||||
* Prepare rollback point
|
||||
|
||||
2. **Deployment Steps**
|
||||
|
||||
* Follow deployment procedure
|
||||
* Monitor deployment progress
|
||||
* Verify service health
|
||||
* Run smoke tests
|
||||
|
||||
3. **Verification**
|
||||
|
||||
* Verify functionality
|
||||
* Check performance
|
||||
* Validate security
|
||||
* Test integrations
|
||||
|
||||
Post-Deployment
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Monitoring**
|
||||
|
||||
* Monitor application performance
|
||||
* Watch for errors
|
||||
* Track user activity
|
||||
* Monitor resource usage
|
||||
|
||||
2. **Communication**
|
||||
|
||||
* Notify users of deployment
|
||||
* Provide release notes
|
||||
* Address initial feedback
|
||||
* Support user questions
|
||||
|
||||
3. **Optimization**
|
||||
|
||||
* Identify performance bottlenecks
|
||||
* Optimize resource usage
|
||||
* Fine-tune configuration
|
||||
* Plan for future improvements
|
||||
|
||||
Deployment Environments
|
||||
---------------------
|
||||
|
||||
Development Environment
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Feature development
|
||||
* Bug fixing
|
||||
* Testing
|
||||
* Integration
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* Minimal resources
|
||||
* Frequent updates
|
||||
* Non-production data
|
||||
* Developer access
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Debug mode enabled
|
||||
* Verbose logging
|
||||
* Test API keys
|
||||
* Local development tools
|
||||
|
||||
Staging Environment
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Pre-production testing
|
||||
* Performance testing
|
||||
* User acceptance testing
|
||||
* Deployment validation
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* Similar to production
|
||||
* Controlled access
|
||||
* Sanitized production data
|
||||
* Regular refreshes
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Production-like settings
|
||||
* Monitoring enabled
|
||||
* Test integrations
|
||||
* Staging API endpoints
|
||||
|
||||
Production Environment
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Purpose**
|
||||
|
||||
* Live user access
|
||||
* Business operations
|
||||
* Customer data
|
||||
* Revenue generation
|
||||
|
||||
2. **Characteristics**
|
||||
|
||||
* High availability
|
||||
* Scalability
|
||||
* Security
|
||||
* Performance
|
||||
|
||||
3. **Configuration**
|
||||
|
||||
* Optimized settings
|
||||
* Minimal logging
|
||||
* Production API keys
|
||||
* Strict access controls
|
||||
|
||||
Future Deployment Enhancements
|
||||
----------------------------
|
||||
|
||||
1. **Containerization Improvements**
|
||||
|
||||
* Optimize container images
|
||||
* Implement container security scanning
|
||||
* Enhance orchestration
|
||||
* Improve container networking
|
||||
|
||||
2. **Infrastructure as Code**
|
||||
|
||||
* Complete IaC implementation
|
||||
* Automated environment provisioning
|
||||
* Configuration management
|
||||
* Compliance as code
|
||||
|
||||
3. **Advanced Deployment Strategies**
|
||||
|
||||
* Feature flags
|
||||
* A/B testing infrastructure
|
||||
* Canary deployments
|
||||
* Progressive delivery
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 142 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 91 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 158 KiB |
@@ -1,156 +0,0 @@
|
||||
System Architecture
|
||||
==================
|
||||
|
||||
This section provides a comprehensive overview of the AI-Writer system architecture, including component interactions, data flow, and design patterns.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Architecture Documentation:
|
||||
|
||||
overview
|
||||
components
|
||||
database_schema
|
||||
api_design
|
||||
security
|
||||
|
||||
Architecture Overview
|
||||
-------------------
|
||||
|
||||
.. include:: overview.rst
|
||||
|
||||
Component Diagram
|
||||
---------------
|
||||
|
||||
.. image:: diagrams/high_level_architecture.png
|
||||
:alt: AI-Writer High-Level Architecture Diagram
|
||||
:width: 800px
|
||||
|
||||
.. image:: diagrams/database_architecture.png
|
||||
:alt: AI-Writer Database Architecture Diagram
|
||||
:width: 800px
|
||||
|
||||
.. image:: diagrams/content_generation_workflow.png
|
||||
:alt: AI-Writer Content Generation Workflow Diagram
|
||||
:width: 800px
|
||||
|
||||
Key Components
|
||||
------------
|
||||
|
||||
The AI-Writer platform consists of several key components:
|
||||
|
||||
1. **User Interface Layer**
|
||||
|
||||
* Streamlit-based web interface
|
||||
* Component-based UI architecture
|
||||
* Responsive design for multiple devices
|
||||
|
||||
2. **Application Layer**
|
||||
|
||||
* Content generation modules
|
||||
* AI provider integrations
|
||||
* Research and analysis tools
|
||||
* Analytics and reporting
|
||||
|
||||
3. **Data Layer**
|
||||
|
||||
* Relational database (SQLite/PostgreSQL)
|
||||
* Vector database (ChromaDB)
|
||||
* File storage for generated content
|
||||
|
||||
4. **Integration Layer**
|
||||
|
||||
* API endpoints for external integration
|
||||
* Authentication and authorization
|
||||
* Rate limiting and caching
|
||||
|
||||
Component Interactions
|
||||
--------------------
|
||||
|
||||
The components interact through well-defined interfaces:
|
||||
|
||||
1. **UI to Application Layer**
|
||||
|
||||
* Event-driven interaction
|
||||
* State management through Streamlit session state
|
||||
* Asynchronous processing for long-running tasks
|
||||
|
||||
2. **Application to Data Layer**
|
||||
|
||||
* Repository pattern for data access
|
||||
* Transaction management
|
||||
* Connection pooling
|
||||
|
||||
3. **Application to External Services**
|
||||
|
||||
* API client abstractions
|
||||
* Retry mechanisms
|
||||
* Circuit breakers for fault tolerance
|
||||
|
||||
Data Flow
|
||||
--------
|
||||
|
||||
The typical data flow in the system:
|
||||
|
||||
1. User submits content generation request through UI
|
||||
2. Application layer validates and processes the request
|
||||
3. AI provider is called to generate content
|
||||
4. Generated content is stored in the database
|
||||
5. Content is returned to the UI for display and editing
|
||||
6. Analytics data is collected and stored
|
||||
|
||||
Deployment Architecture
|
||||
---------------------
|
||||
|
||||
AI-Writer supports multiple deployment models:
|
||||
|
||||
1. **Single-User Deployment**
|
||||
|
||||
* Local installation
|
||||
* SQLite database
|
||||
* Local file storage
|
||||
|
||||
2. **Multi-User Deployment**
|
||||
|
||||
* Docker-based deployment
|
||||
* PostgreSQL database
|
||||
* Shared file storage
|
||||
* Load balancing
|
||||
|
||||
3. **Cloud Deployment**
|
||||
|
||||
* Kubernetes orchestration
|
||||
* Cloud database services
|
||||
* Object storage
|
||||
* Auto-scaling
|
||||
|
||||
Technology Stack
|
||||
--------------
|
||||
|
||||
The AI-Writer platform is built on the following technologies:
|
||||
|
||||
1. **Frontend**
|
||||
|
||||
* Streamlit
|
||||
* HTML/CSS/JavaScript
|
||||
* Plotly for visualizations
|
||||
|
||||
2. **Backend**
|
||||
|
||||
* Python 3.9+
|
||||
* FastAPI for API endpoints
|
||||
* SQLAlchemy for ORM
|
||||
* ChromaDB for vector storage
|
||||
|
||||
3. **AI and ML**
|
||||
|
||||
* OpenAI GPT models
|
||||
* Google Gemini
|
||||
* Hugging Face transformers
|
||||
* Sentence transformers for embeddings
|
||||
|
||||
4. **Infrastructure**
|
||||
|
||||
* Docker
|
||||
* Docker Compose
|
||||
* Kubernetes (for cloud deployment)
|
||||
* GitHub Actions for CI/CD
|
||||
@@ -1,335 +0,0 @@
|
||||
Security Architecture
|
||||
===================
|
||||
|
||||
This document outlines the security architecture of the AI-Writer platform, including authentication, authorization, data protection, and security best practices.
|
||||
|
||||
Authentication and Authorization
|
||||
------------------------------
|
||||
|
||||
User Authentication
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
AI-Writer implements a multi-layered authentication system:
|
||||
|
||||
1. **Password-based Authentication**
|
||||
|
||||
* Passwords are hashed using bcrypt with appropriate work factors
|
||||
* Password complexity requirements are enforced
|
||||
* Account lockout after multiple failed attempts
|
||||
* Password reset via secure email workflow
|
||||
|
||||
2. **API Key Authentication**
|
||||
|
||||
* Unique API keys for programmatic access
|
||||
* Keys are stored using secure hashing
|
||||
* Keys can be scoped to specific permissions
|
||||
* Keys can be revoked at any time
|
||||
|
||||
3. **OAuth 2.0 (for multi-user deployments)**
|
||||
|
||||
* Standard OAuth 2.0 flow with authorization code
|
||||
* JWT tokens with appropriate expiration
|
||||
* Refresh token rotation
|
||||
* PKCE for public clients
|
||||
|
||||
Authorization Model
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The platform uses a role-based access control (RBAC) system:
|
||||
|
||||
1. **User Roles**
|
||||
|
||||
* **Admin**: Full system access
|
||||
* **Editor**: Content creation and editing
|
||||
* **Viewer**: Read-only access to content
|
||||
* **API**: Programmatic access with limited scope
|
||||
|
||||
2. **Permission Scopes**
|
||||
|
||||
* `content:read`: View content
|
||||
* `content:write`: Create and edit content
|
||||
* `content:delete`: Delete content
|
||||
* `user:read`: View user information
|
||||
* `user:write`: Modify user information
|
||||
* `settings:read`: View settings
|
||||
* `settings:write`: Modify settings
|
||||
* `api:manage`: Manage API keys
|
||||
|
||||
3. **Resource-level Permissions**
|
||||
|
||||
* Permissions are checked at the resource level
|
||||
* Users can only access their own content
|
||||
* Sharing functionality with explicit permissions
|
||||
|
||||
Data Protection
|
||||
-------------
|
||||
|
||||
Encryption
|
||||
~~~~~~~~~
|
||||
|
||||
1. **Data in Transit**
|
||||
|
||||
* TLS 1.3 for all communications
|
||||
* Strong cipher suites
|
||||
* HSTS implementation
|
||||
* Certificate pinning for API clients
|
||||
|
||||
2. **Data at Rest**
|
||||
|
||||
* Database encryption
|
||||
* Encrypted file storage
|
||||
* Secure key management
|
||||
* Regular key rotation
|
||||
|
||||
3. **Sensitive Data**
|
||||
|
||||
* API keys and credentials are encrypted
|
||||
* PII is encrypted with separate keys
|
||||
* Encryption keys are properly secured
|
||||
|
||||
API Key Security
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **Key Generation**
|
||||
|
||||
* Keys are generated using cryptographically secure random functions
|
||||
* Sufficient entropy (256 bits)
|
||||
* Keys follow a consistent format for validation
|
||||
|
||||
2. **Key Storage**
|
||||
|
||||
* Only key hashes are stored in the database
|
||||
* Secure comparison for validation
|
||||
* Keys are never logged or exposed in error messages
|
||||
|
||||
3. **Key Management**
|
||||
|
||||
* Keys can be rotated regularly
|
||||
* Unused keys are automatically expired
|
||||
* Key usage is logged for audit purposes
|
||||
|
||||
Secure Development Practices
|
||||
--------------------------
|
||||
|
||||
Input Validation
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **API Input Validation**
|
||||
|
||||
* All input is validated against schemas
|
||||
* Type checking and constraint validation
|
||||
* Protection against injection attacks
|
||||
* Input sanitization where appropriate
|
||||
|
||||
2. **Content Validation**
|
||||
|
||||
* Content is scanned for malicious elements
|
||||
* HTML/Markdown sanitization
|
||||
* File upload validation and scanning
|
||||
|
||||
3. **Error Handling**
|
||||
|
||||
* Secure error handling that doesn't leak sensitive information
|
||||
* Consistent error responses
|
||||
* Detailed internal logging for troubleshooting
|
||||
|
||||
Dependency Management
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Dependency Scanning**
|
||||
|
||||
* Regular scanning for vulnerable dependencies
|
||||
* Automated updates for security patches
|
||||
* Dependency pinning for stability
|
||||
|
||||
2. **Minimal Dependencies**
|
||||
|
||||
* Only necessary dependencies are included
|
||||
* Regular dependency audits
|
||||
* Preference for well-maintained libraries
|
||||
|
||||
3. **Containerization**
|
||||
|
||||
* Minimal base images
|
||||
* Non-root container execution
|
||||
* Image scanning for vulnerabilities
|
||||
|
||||
Logging and Monitoring
|
||||
--------------------
|
||||
|
||||
Security Logging
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
1. **Authentication Events**
|
||||
|
||||
* Login attempts (successful and failed)
|
||||
* Password changes and resets
|
||||
* API key creation and usage
|
||||
* Session management events
|
||||
|
||||
2. **Authorization Events**
|
||||
|
||||
* Permission checks
|
||||
* Access denials
|
||||
* Privilege escalation
|
||||
* Role changes
|
||||
|
||||
3. **System Events**
|
||||
|
||||
* Configuration changes
|
||||
* Service starts and stops
|
||||
* Database migrations
|
||||
* Backup and restore operations
|
||||
|
||||
Monitoring and Alerting
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Security Monitoring**
|
||||
|
||||
* Real-time monitoring for suspicious activities
|
||||
* Anomaly detection for unusual patterns
|
||||
* Rate limiting and abuse detection
|
||||
* Geographic anomaly detection
|
||||
|
||||
2. **Performance Monitoring**
|
||||
|
||||
* Resource usage tracking
|
||||
* API response time monitoring
|
||||
* Error rate monitoring
|
||||
* Database performance tracking
|
||||
|
||||
3. **Alerting**
|
||||
|
||||
* Immediate alerts for security incidents
|
||||
* Escalation procedures
|
||||
* On-call rotation
|
||||
* Incident response playbooks
|
||||
|
||||
Compliance and Privacy
|
||||
--------------------
|
||||
|
||||
Data Governance
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **Data Classification**
|
||||
|
||||
* Clear classification of data sensitivity
|
||||
* Handling procedures for each classification
|
||||
* Access controls based on classification
|
||||
* Retention policies by data type
|
||||
|
||||
2. **Data Minimization**
|
||||
|
||||
* Only necessary data is collected
|
||||
* Automatic data pruning
|
||||
* Anonymization where possible
|
||||
* Purpose limitation
|
||||
|
||||
3. **User Consent**
|
||||
|
||||
* Clear consent mechanisms
|
||||
* Granular permission options
|
||||
* Easy consent withdrawal
|
||||
* Consent records
|
||||
|
||||
Privacy Features
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
1. **User Privacy Controls**
|
||||
|
||||
* Data export functionality
|
||||
* Account deletion
|
||||
* Privacy settings management
|
||||
* Usage tracking opt-out
|
||||
|
||||
2. **Data Portability**
|
||||
|
||||
* Export in standard formats
|
||||
* Complete data export
|
||||
* Machine-readable formats
|
||||
* Import capabilities
|
||||
|
||||
3. **Transparency**
|
||||
|
||||
* Clear privacy policy
|
||||
* Data usage explanations
|
||||
* Third-party data sharing disclosure
|
||||
* Processing activities documentation
|
||||
|
||||
Security Testing
|
||||
--------------
|
||||
|
||||
Vulnerability Management
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Security Testing**
|
||||
|
||||
* Regular penetration testing
|
||||
* Static application security testing (SAST)
|
||||
* Dynamic application security testing (DAST)
|
||||
* Software composition analysis (SCA)
|
||||
|
||||
2. **Bug Bounty Program**
|
||||
|
||||
* Responsible disclosure policy
|
||||
* Security researcher engagement
|
||||
* Vulnerability triage process
|
||||
* Remediation tracking
|
||||
|
||||
3. **Security Reviews**
|
||||
|
||||
* Code reviews with security focus
|
||||
* Architecture security reviews
|
||||
* Threat modeling
|
||||
* Security design reviews
|
||||
|
||||
Incident Response
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Incident Response Plan**
|
||||
|
||||
* Defined incident response procedures
|
||||
* Roles and responsibilities
|
||||
* Communication templates
|
||||
* Escalation paths
|
||||
|
||||
2. **Breach Notification**
|
||||
|
||||
* Legal compliance with notification requirements
|
||||
* User communication plan
|
||||
* Regulatory reporting procedures
|
||||
* Post-incident analysis
|
||||
|
||||
3. **Recovery Procedures**
|
||||
|
||||
* Backup and restore testing
|
||||
* Business continuity planning
|
||||
* Disaster recovery procedures
|
||||
* Service level objectives
|
||||
|
||||
Security Roadmap
|
||||
--------------
|
||||
|
||||
Planned Security Enhancements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Short-term (0-6 months)**
|
||||
|
||||
* Implement multi-factor authentication
|
||||
* Enhance API key management
|
||||
* Improve security logging
|
||||
* Conduct initial penetration test
|
||||
|
||||
2. **Medium-term (6-12 months)**
|
||||
|
||||
* Implement security information and event management (SIEM)
|
||||
* Enhance data encryption
|
||||
* Develop comprehensive security training
|
||||
* Implement automated security testing in CI/CD
|
||||
|
||||
3. **Long-term (12+ months)**
|
||||
|
||||
* Achieve SOC 2 compliance
|
||||
* Implement advanced threat protection
|
||||
* Develop zero-trust architecture
|
||||
* Enhance privacy features for international compliance
|
||||
@@ -1,56 +0,0 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
What is AI-Writer?
|
||||
-----------------
|
||||
|
||||
AI-Writer (Alwrity) is a comprehensive AI-powered content creation platform designed to help content creators, marketers, and businesses generate high-quality content efficiently. The platform leverages advanced language models and AI technologies to assist in creating various types of content, from social media posts to full-length articles.
|
||||
|
||||
Key Features
|
||||
-----------
|
||||
|
||||
1. **Multi-Platform Content Generation**
|
||||
|
||||
* LinkedIn content (posts, articles, profiles)
|
||||
* Twitter/X posts and threads
|
||||
* Blog articles and SEO-optimized content
|
||||
* Marketing copy and email templates
|
||||
|
||||
2. **AI Research Integration**
|
||||
|
||||
* Web crawling for relevant information
|
||||
* Content summarization
|
||||
* Fact-checking capabilities
|
||||
* Citation and reference management
|
||||
|
||||
3. **Database Integration**
|
||||
|
||||
* Content storage and retrieval
|
||||
* Vector database for semantic search
|
||||
* Content versioning and history
|
||||
|
||||
4. **Analytics Dashboard**
|
||||
|
||||
* Content performance metrics
|
||||
* Usage statistics
|
||||
* AI model performance analysis
|
||||
|
||||
5. **Customization Options**
|
||||
|
||||
* Personalized content templates
|
||||
* Brand voice and tone settings
|
||||
* Custom workflows
|
||||
|
||||
6. **Multiple AI Provider Support**
|
||||
|
||||
* OpenAI (GPT models)
|
||||
* Google Gemini
|
||||
* Anthropic Claude (coming soon)
|
||||
* Local models (coming soon)
|
||||
|
||||
Project History
|
||||
--------------
|
||||
|
||||
AI-Writer was created to address the growing need for high-quality content creation at scale. The project aims to democratize access to advanced AI writing capabilities while maintaining a focus on quality, accuracy, and ethical content generation.
|
||||
|
||||
The platform continues to evolve with new features and improvements based on user feedback and advancements in AI technology.
|
||||
@@ -1,139 +0,0 @@
|
||||
# Migration Plan: Alwrity (AI-Writer) to Enterprise-Ready Architecture
|
||||
|
||||
## 1. Background & Motivation
|
||||
Alwrity (AI-Writer) is currently an open-source, Streamlit-based project for AI-powered content creation, SEO, analytics, and more. To serve enterprise customers, we need to move to a scalable, secure, and maintainable architecture, reusing as much of the existing Python codebase as possible while replacing the UI and improving backend robustness.
|
||||
|
||||
---
|
||||
|
||||
## 2. Current State
|
||||
- **UI:** Streamlit (great for prototyping, not for enterprise)
|
||||
- **Backend:** Python modules for AI writing, SEO, analytics, chatbot, etc.
|
||||
- **Database:** SQLite, ChromaDB, some service layers for Twitter and content
|
||||
- **AI/ML:** Integrates with OpenAI, Gemini, and other providers
|
||||
|
||||
---
|
||||
|
||||
## 3. Design Directions & Tech Stack Recommendations
|
||||
|
||||
### A. Frontend
|
||||
- **React** (TypeScript) for scalable, maintainable UI
|
||||
- **UI Library:** Material-UI (MUI) or Ant Design
|
||||
- **State/Data:** React Query, Context API or Redux Toolkit
|
||||
|
||||
### B. Backend
|
||||
- **FastAPI** (Python): async, high-performance, easy to wrap existing modules
|
||||
- **Task Queue:** Celery + Redis for background jobs (if needed)
|
||||
|
||||
### C. Database & Storage
|
||||
- **PostgreSQL** for structured data
|
||||
- **Redis** for caching and task queue
|
||||
- **Vector DB:** Pinecone, Weaviate, or Qdrant for semantic search (if needed)
|
||||
- **Blob Storage:** AWS S3 or Azure Blob for files
|
||||
|
||||
### D. AI/ML Integration
|
||||
- Reuse existing Python modules
|
||||
- Serve custom models via FastAPI endpoints
|
||||
|
||||
### E. Authentication
|
||||
- **Auth0** or **Keycloak** for OAuth2/SSO, or FastAPI JWT for MVP
|
||||
|
||||
### F. DevOps
|
||||
- **Docker** for containerization
|
||||
- **GitHub Actions** for CI/CD
|
||||
- **(Optional) Kubernetes** for orchestration
|
||||
|
||||
### G. Security & Compliance
|
||||
- SSO, RBAC, audit logs, encryption, GDPR/SOC2 readiness
|
||||
|
||||
---
|
||||
|
||||
## 4. Migration Plan: Step-by-Step
|
||||
|
||||
### Phase 1: Preparation
|
||||
- Audit codebase for reusable business logic
|
||||
- Separate UI code from backend logic
|
||||
- Set up monorepo or separate repos for backend (Python/FastAPI) and frontend (React)
|
||||
|
||||
### Phase 2: Backend API Layer
|
||||
- Scaffold FastAPI app
|
||||
- Wrap existing Python modules as API endpoints (content generation, SEO, analytics, etc.)
|
||||
- Add authentication (JWT for MVP, SSO for production)
|
||||
- Write unit/integration tests
|
||||
|
||||
### Phase 3: Frontend Migration
|
||||
- Scaffold React app (TypeScript)
|
||||
- Set up routing, authentication, dashboard layout
|
||||
- For each Streamlit feature, create a React page/component
|
||||
- Use MUI/Ant Design for UI
|
||||
- Fetch data from FastAPI using React Query
|
||||
|
||||
### Phase 4: Feature Parity & Enhancements
|
||||
- Migrate all features, one by one, to new stack
|
||||
- Use Celery + Redis for long-running jobs
|
||||
- Add UI/UX improvements (loading, error handling, feedback)
|
||||
|
||||
### Phase 5: Productionization
|
||||
- Dockerize frontend and backend
|
||||
- Set up CI/CD with GitHub Actions
|
||||
- Add logging, monitoring (Sentry, Prometheus, Grafana)
|
||||
- Harden security (HTTPS, CORS, secure cookies, etc.)
|
||||
|
||||
### Phase 6: Launch & Iterate
|
||||
- Deploy to cloud
|
||||
- Gather user feedback and iterate
|
||||
|
||||
---
|
||||
|
||||
## 5. Prioritized Modules for Migration
|
||||
|
||||
### Best-fit modules to start with (already decoupled from UI):
|
||||
1. **AI Writers (lib/ai_writers/):** Blog, news, social, email, story, YouTube script writers
|
||||
2. **SEO Tools (lib/ai_seo_tools/):** Keyword analyzer, meta generator, content gap, enterprise SEO, content calendar
|
||||
3. **Website Analyzer (lib/utils/website_analyzer/):** Performance, SEO, content quality analysis
|
||||
4. **Analytics/Performance (lib/content_performance_predictor/):** Content analytics and prediction
|
||||
5. **Chatbot Core (lib/chatbot_custom/core/):** Workflow engine, tool router, intent analyzer, context manager
|
||||
6. **Database Services (lib/database/):** Twitter and content management service layers
|
||||
7. **AI Marketing Tools (lib/ai_marketing_tools/ai_backlinker/):** Backlinking and marketing automation
|
||||
|
||||
### Modules to avoid for now:
|
||||
- Streamlit UI scripts and thin wrappers
|
||||
|
||||
---
|
||||
|
||||
## 6. Summary Table
|
||||
|
||||
| Layer | Stack/Tooling | Why? |
|
||||
|---------------|-----------------------------|--------------------------------------------|
|
||||
| Frontend | React + TypeScript + MUI | Modern, scalable, huge ecosystem |
|
||||
| Backend | FastAPI (Python) | Async, high-perf, easy to wrap old code |
|
||||
| Auth | FastAPI JWT/Auth0/Keycloak | Secure, enterprise-ready |
|
||||
| DB | PostgreSQL, Redis | Reliable, scalable, Python-friendly |
|
||||
| AI/ML | Existing Python modules | Maximum code reuse |
|
||||
| Task Queue | Celery + Redis | For background/async jobs |
|
||||
| DevOps | Docker, GitHub Actions | Easy deployment, automation |
|
||||
|
||||
---
|
||||
|
||||
## 7. Next Steps
|
||||
- Start with AI Writers and SEO Tools: wrap as FastAPI endpoints
|
||||
- Gradually add Website Analyzer, Analytics, and Chatbot features
|
||||
- Leave UI and Streamlit code aside; focus on modules that don’t depend on Streamlit
|
||||
- Build React frontend to consume new API endpoints
|
||||
|
||||
---
|
||||
|
||||
## 8. Optional: Sample FastAPI Endpoint (for reference)
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
from lib.ai_writers.blog_writer import generate_blog_post
|
||||
|
||||
app = FastAPI()
|
||||
|
||||
@app.post("/generate-blog/")
|
||||
def generate_blog(data: BlogRequest):
|
||||
return generate_blog_post(data.topic, data.keywords)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This document should be updated as the migration progresses and new architectural decisions are made.**
|
||||
@@ -1,106 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Test script to verify frontend-backend communication.
|
||||
"""
|
||||
|
||||
import requests
|
||||
import time
|
||||
|
||||
def test_backend_endpoints():
|
||||
"""Test all backend endpoints"""
|
||||
base_url = "http://localhost:8000"
|
||||
|
||||
print("🧪 Testing Backend Endpoints...")
|
||||
|
||||
# Test health endpoint
|
||||
print("\n1️⃣ Testing health endpoint...")
|
||||
try:
|
||||
response = requests.get(f"{base_url}/health")
|
||||
if response.status_code == 200:
|
||||
print("✅ Health endpoint working")
|
||||
else:
|
||||
print(f"❌ Health endpoint failed: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ Health endpoint error: {e}")
|
||||
|
||||
# Test onboarding check
|
||||
print("\n2️⃣ Testing onboarding check...")
|
||||
try:
|
||||
response = requests.get(f"{base_url}/api/check-onboarding")
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"✅ Onboarding check working: {data}")
|
||||
else:
|
||||
print(f"❌ Onboarding check failed: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ Onboarding check error: {e}")
|
||||
|
||||
# Test onboarding start
|
||||
print("\n3️⃣ Testing onboarding start...")
|
||||
try:
|
||||
response = requests.post(f"{base_url}/api/onboarding/start")
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"✅ Onboarding start working: {data}")
|
||||
else:
|
||||
print(f"❌ Onboarding start failed: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ Onboarding start error: {e}")
|
||||
|
||||
# Test onboarding step
|
||||
print("\n4️⃣ Testing onboarding step...")
|
||||
try:
|
||||
response = requests.get(f"{base_url}/api/onboarding/step")
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"✅ Onboarding step working: {data}")
|
||||
else:
|
||||
print(f"❌ Onboarding step failed: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ Onboarding step error: {e}")
|
||||
|
||||
def test_frontend_communication():
|
||||
"""Test if frontend can reach backend"""
|
||||
print("\n🌐 Testing Frontend-Backend Communication...")
|
||||
|
||||
# Simulate frontend API calls
|
||||
base_url = "http://localhost:8000"
|
||||
|
||||
# Test the exact endpoints the frontend uses
|
||||
endpoints = [
|
||||
("GET", "/api/check-onboarding"),
|
||||
("POST", "/api/onboarding/start"),
|
||||
("GET", "/api/onboarding/step"),
|
||||
("GET", "/api/onboarding/api-keys"),
|
||||
("POST", "/api/onboarding/api-keys"),
|
||||
("GET", "/api/onboarding/progress"),
|
||||
]
|
||||
|
||||
for method, endpoint in endpoints:
|
||||
print(f"\nTesting {method} {endpoint}...")
|
||||
try:
|
||||
if method == "GET":
|
||||
response = requests.get(f"{base_url}{endpoint}")
|
||||
elif method == "POST":
|
||||
response = requests.post(f"{base_url}{endpoint}")
|
||||
|
||||
if response.status_code in [200, 404]: # 404 is expected for some endpoints without data
|
||||
print(f"✅ {method} {endpoint} - Status: {response.status_code}")
|
||||
else:
|
||||
print(f"❌ {method} {endpoint} - Status: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ {method} {endpoint} - Error: {e}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("🚀 Starting Frontend-Backend Communication Test...")
|
||||
|
||||
# Wait a moment for services to be ready
|
||||
print("⏳ Waiting for services to be ready...")
|
||||
time.sleep(2)
|
||||
|
||||
test_backend_endpoints()
|
||||
test_frontend_communication()
|
||||
|
||||
print("\n🎯 Test complete!")
|
||||
print("📝 If all tests pass, the frontend should work correctly.")
|
||||
print("🌐 Visit http://localhost:3000 to test the onboarding flow.")
|
||||
@@ -1,82 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Test script to reset onboarding state and test the onboarding flow.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import sqlite3
|
||||
|
||||
# Add the backend directory to Python path
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'backend'))
|
||||
|
||||
def reset_database():
|
||||
"""Reset the onboarding database"""
|
||||
db_path = "backend/onboarding.db"
|
||||
if os.path.exists(db_path):
|
||||
os.remove(db_path)
|
||||
print("✅ Database file removed")
|
||||
else:
|
||||
print("ℹ️ No database file found")
|
||||
|
||||
def check_onboarding_status():
|
||||
"""Check the current onboarding status"""
|
||||
import requests
|
||||
try:
|
||||
response = requests.get("http://localhost:8000/api/check-onboarding")
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"📊 Onboarding Status: {data}")
|
||||
return data
|
||||
else:
|
||||
print(f"❌ Error: {response.status_code}")
|
||||
return None
|
||||
except Exception as e:
|
||||
print(f"❌ Error checking onboarding status: {e}")
|
||||
return None
|
||||
|
||||
def test_onboarding_flow():
|
||||
"""Test the complete onboarding flow"""
|
||||
print("\n🧪 Testing Onboarding Flow...")
|
||||
|
||||
# Step 1: Check initial status
|
||||
print("\n1️⃣ Checking initial onboarding status...")
|
||||
status = check_onboarding_status()
|
||||
|
||||
if status and status.get('onboarding_required'):
|
||||
print("✅ Correctly shows onboarding required for first-time user")
|
||||
else:
|
||||
print("❌ Incorrectly shows onboarding complete")
|
||||
|
||||
# Step 2: Start onboarding
|
||||
print("\n2️⃣ Starting onboarding session...")
|
||||
try:
|
||||
import requests
|
||||
response = requests.post("http://localhost:8000/api/onboarding/start")
|
||||
if response.status_code == 200:
|
||||
print("✅ Onboarding session started")
|
||||
else:
|
||||
print(f"❌ Error starting onboarding: {response.status_code}")
|
||||
except Exception as e:
|
||||
print(f"❌ Error: {e}")
|
||||
|
||||
# Step 3: Check status again
|
||||
print("\n3️⃣ Checking status after starting onboarding...")
|
||||
status = check_onboarding_status()
|
||||
|
||||
if status and status.get('onboarding_required'):
|
||||
print("✅ Still shows onboarding required (correct)")
|
||||
else:
|
||||
print("❌ Incorrectly shows onboarding complete")
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("🔄 Resetting onboarding state...")
|
||||
reset_database()
|
||||
|
||||
print("\n⏳ Waiting for backend to restart...")
|
||||
import time
|
||||
time.sleep(3)
|
||||
|
||||
test_onboarding_flow()
|
||||
|
||||
print("\n🎯 Test complete! Check your frontend at http://localhost:3000")
|
||||
Reference in New Issue
Block a user