152 lines
5.6 KiB
Markdown
152 lines
5.6 KiB
Markdown
# AI Blog Writer Service Architecture
|
|
|
|
This directory contains the refactored AI Blog Writer service with a clean, modular architecture.
|
|
|
|
## 📁 Directory Structure
|
|
|
|
```
|
|
blog_writer/
|
|
├── README.md # This file
|
|
├── blog_service.py # Main entry point (imports from core)
|
|
├── core/ # Core service orchestrator
|
|
│ ├── __init__.py
|
|
│ └── blog_writer_service.py # Main service coordinator
|
|
├── research/ # Research functionality
|
|
│ ├── __init__.py
|
|
│ ├── research_service.py # Main research orchestrator
|
|
│ ├── keyword_analyzer.py # AI-powered keyword analysis
|
|
│ ├── competitor_analyzer.py # Competitor intelligence
|
|
│ └── content_angle_generator.py # Content angle discovery
|
|
├── outline/ # Outline generation
|
|
│ ├── __init__.py
|
|
│ ├── outline_service.py # Main outline orchestrator
|
|
│ ├── outline_generator.py # AI-powered outline generation
|
|
│ ├── outline_optimizer.py # Outline optimization
|
|
│ └── section_enhancer.py # Section enhancement
|
|
├── content/ # Content generation (TODO)
|
|
└── optimization/ # SEO & optimization (TODO)
|
|
```
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
### Core Module (`core/`)
|
|
- **`BlogWriterService`**: Main orchestrator that coordinates all blog writing functionality
|
|
- Provides a unified interface for research, outline generation, and content creation
|
|
- Delegates to specialized modules for specific functionality
|
|
|
|
### Research Module (`research/`)
|
|
- **`ResearchService`**: Orchestrates comprehensive research using Exa neural search (currently Exa-only for testing)
|
|
- **`KeywordAnalyzer`**: AI-powered keyword analysis and extraction
|
|
- **`CompetitorAnalyzer`**: Competitor intelligence and market analysis
|
|
- **`ContentAngleGenerator`**: Strategic content angle discovery
|
|
|
|
### Outline Module (`outline/`)
|
|
- **`OutlineService`**: Manages outline generation, refinement, and optimization
|
|
- **`OutlineGenerator`**: AI-powered outline generation from research data
|
|
- **`OutlineOptimizer`**: Optimizes outlines for flow, SEO, and engagement
|
|
- **`SectionEnhancer`**: Enhances individual sections using AI
|
|
|
|
## 🔄 Service Flow
|
|
|
|
1. **Research Phase**: `ResearchService` → `KeywordAnalyzer` + `CompetitorAnalyzer` + `ContentAngleGenerator`
|
|
2. **Outline Phase**: `OutlineService` → `OutlineGenerator` → `OutlineOptimizer`
|
|
3. **Content Phase**: (TODO) Content generation and optimization
|
|
4. **Publishing Phase**: (TODO) Platform integration and publishing
|
|
|
|
## 🚀 Usage
|
|
|
|
```python
|
|
from services.blog_writer.blog_service import BlogWriterService
|
|
|
|
# Initialize the service
|
|
service = BlogWriterService()
|
|
|
|
# Research a topic
|
|
research_result = await service.research(research_request)
|
|
|
|
# Generate outline from research
|
|
outline_result = await service.generate_outline(outline_request)
|
|
|
|
# Enhance sections
|
|
enhanced_section = await service.enhance_section_with_ai(section, "SEO optimization")
|
|
```
|
|
|
|
## 🎯 Key Benefits
|
|
|
|
### 1. **Modularity**
|
|
- Each module has a single responsibility
|
|
- Easy to test, maintain, and extend
|
|
- Clear separation of concerns
|
|
|
|
### 2. **Reusability**
|
|
- Components can be used independently
|
|
- Easy to swap implementations
|
|
- Shared utilities and helpers
|
|
|
|
### 3. **Scalability**
|
|
- New features can be added as separate modules
|
|
- Existing modules can be enhanced without affecting others
|
|
- Clear interfaces between modules
|
|
|
|
### 4. **Maintainability**
|
|
- Smaller, focused files are easier to understand
|
|
- Changes are isolated to specific modules
|
|
- Clear dependency relationships
|
|
|
|
## 🔧 Development Guidelines
|
|
|
|
### Adding New Features
|
|
1. Identify the appropriate module (research, outline, content, optimization)
|
|
2. Create new classes following the existing patterns
|
|
3. Update the module's `__init__.py` to export new classes
|
|
4. Add methods to the appropriate service orchestrator
|
|
5. Update the main `BlogWriterService` if needed
|
|
|
|
### Testing
|
|
- Each module should have its own test suite
|
|
- Mock external dependencies (AI providers, APIs)
|
|
- Test both success and failure scenarios
|
|
- Maintain high test coverage
|
|
|
|
### Error Handling
|
|
- Use graceful degradation with fallbacks
|
|
- Log errors appropriately
|
|
- Return meaningful error messages to users
|
|
- Don't let one module's failure break the entire flow
|
|
|
|
## 📈 Future Enhancements
|
|
|
|
### Content Module (`content/`)
|
|
- Section content generation
|
|
- Content optimization and refinement
|
|
- Multi-format output (HTML, Markdown, etc.)
|
|
|
|
### Optimization Module (`optimization/`)
|
|
- SEO analysis and recommendations
|
|
- Readability optimization
|
|
- Performance metrics and analytics
|
|
|
|
### Integration Module (`integration/`)
|
|
- Platform-specific adapters (WordPress, Wix, etc.)
|
|
- Publishing workflows
|
|
- Content management system integration
|
|
|
|
## 🔍 Code Quality
|
|
|
|
- **Type Hints**: All methods use proper type annotations
|
|
- **Documentation**: Comprehensive docstrings for all public methods
|
|
- **Error Handling**: Graceful failure with meaningful error messages
|
|
- **Logging**: Structured logging with appropriate levels
|
|
- **Testing**: Unit tests for all major functionality
|
|
- **Performance**: Efficient caching and API usage
|
|
|
|
## 📝 Migration Notes
|
|
|
|
The original `blog_service.py` has been refactored into this modular structure:
|
|
- **Research functionality** → `research/` module
|
|
- **Outline generation** → `outline/` module
|
|
- **Service orchestration** → `core/` module
|
|
- **Main entry point** → `blog_service.py` (now just imports from core)
|
|
|
|
All existing API endpoints continue to work without changes due to the maintained interface in `BlogWriterService`.
|