197 lines
4.9 KiB
Markdown
197 lines
4.9 KiB
Markdown
# SEO Automation - Architecture Overview
|
|
|
|
## Integrated Application Structure
|
|
|
|
The SEO automation tool has been refactored into a proper Python package with a clean, modular architecture inspired by Ruby on Rails and modern Python best practices.
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
seo/
|
|
├── seo # Main executable (entry point)
|
|
├── src/seo/ # Main package
|
|
│ ├── __init__.py # Package initialization
|
|
│ ├── cli.py # CLI interface
|
|
│ ├── app.py # Main application class
|
|
│ ├── config.py # Configuration
|
|
│ ├── exporter.py # Export functionality
|
|
│ ├── analyzer.py # AI analysis
|
|
│ ├── recategorizer.py # Recategorization
|
|
│ ├── seo_checker.py # SEO checking
|
|
│ ├── categories.py # Category management
|
|
│ └── approval.py # Approval system
|
|
├── scripts/ # Legacy scripts (deprecated)
|
|
├── setup.py # Package installation
|
|
├── setup.cfg # Package configuration
|
|
└── config.yaml # Application config
|
|
```
|
|
|
|
## Application Architecture
|
|
|
|
### Main Application Class (SEOApp)
|
|
|
|
The `SEOApp` class in `app.py` is the heart of the application, providing a unified, Rails-inspired API:
|
|
|
|
```python
|
|
from seo.app import SEOApp
|
|
|
|
# Initialize
|
|
app = SEOApp(verbose=True)
|
|
|
|
# Use methods directly
|
|
app.export()
|
|
app.analyze()
|
|
app.seo_check()
|
|
app.categories()
|
|
app.approve()
|
|
|
|
# Or run full pipeline
|
|
app.full_pipeline()
|
|
```
|
|
|
|
### Design Principles
|
|
|
|
1. **Convention Over Configuration**: Sensible defaults, minimal configuration needed
|
|
2. **DRY (Don't Repeat Yourself)**: Shared functionality in base classes
|
|
3. **Separation of Concerns**: Each module has a single responsibility
|
|
4. **Rails-Inspired API**: Simple, intuitive method names
|
|
5. **Pythonic**: Follows Python best practices and idioms
|
|
|
|
## Modules
|
|
|
|
### Core Modules
|
|
|
|
- **app.py**: Main orchestrator, coordinates all operations
|
|
- **cli.py**: Command-line interface, parses arguments, routes commands
|
|
- **config.py**: Configuration management, loads from .env and config.yaml
|
|
|
|
### Feature Modules
|
|
|
|
- **exporter.py**: Exports posts from WordPress sites
|
|
- **analyzer.py**: AI-powered post analysis
|
|
- **recategorizer.py**: AI-powered recategorization
|
|
- **seo_checker.py**: SEO quality analysis
|
|
- **categories.py**: Category management across sites
|
|
- **approval.py**: User approval system for recommendations
|
|
|
|
## Usage Patterns
|
|
|
|
### As a Library
|
|
|
|
```python
|
|
from seo.app import SEOApp
|
|
|
|
# Create instance
|
|
app = SEOApp()
|
|
|
|
# Export posts
|
|
csv_file = app.export()
|
|
|
|
# Analyze with AI (uses latest export)
|
|
app.analyze()
|
|
|
|
# Or analyze specific file
|
|
app.analyze(csv_file)
|
|
|
|
# Check SEO quality
|
|
app.seo_check(top_n=20)
|
|
|
|
# Manage categories
|
|
app.categories()
|
|
|
|
# Approve recommendations
|
|
app.approve()
|
|
```
|
|
|
|
### Via CLI
|
|
|
|
```bash
|
|
# Individual commands
|
|
./seo export
|
|
./seo analyze
|
|
./seo seo_check
|
|
./seo categories
|
|
./seo approve
|
|
|
|
# With arguments
|
|
./seo analyze output/all_posts_2026-02-16.csv
|
|
./seo approve output/category_assignments_*.csv
|
|
./seo seo_check --top-n 20
|
|
|
|
# Full pipeline
|
|
./seo full_pipeline
|
|
|
|
# Get status
|
|
./seo status
|
|
```
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install in development mode
|
|
cd seo
|
|
pip install -e .
|
|
|
|
# Now you can use from anywhere
|
|
seo help
|
|
seo export
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
User Input (CLI or Library)
|
|
↓
|
|
SEOApp (orchestrator)
|
|
↓
|
|
┌───────────────────────────────────────┐
|
|
│ exporter analyzer seo_checker │
|
|
│ categories approval recategorizer│
|
|
└───────────────────────────────────────┘
|
|
↓
|
|
WordPress API / AI API
|
|
↓
|
|
Output Files (output/)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration is loaded from multiple sources in order of precedence:
|
|
|
|
1. Environment variables (.env file)
|
|
2. config.yaml
|
|
3. Default values
|
|
|
|
```python
|
|
from seo.config import Config
|
|
|
|
# Access configuration
|
|
api_key = Config.OPENROUTER_API_KEY
|
|
sites = Config.WORDPRESS_SITES
|
|
```
|
|
|
|
## Benefits of This Architecture
|
|
|
|
1. **Maintainability**: Clear separation of concerns
|
|
2. **Testability**: Each module can be tested independently
|
|
3. **Extensibility**: Easy to add new features
|
|
4. **Reusability**: Can be used as a library or CLI
|
|
5. **Discoverability**: Intuitive API, easy to learn
|
|
6. **Robustness**: Proper error handling and logging
|
|
7. **Pythonic**: Follows Python conventions and best practices
|
|
|
|
## Future Enhancements
|
|
|
|
- Add async support for parallel API calls
|
|
- Implement caching for API responses
|
|
- Add progress bars for long operations
|
|
- Create web interface
|
|
- Add plugin system for custom analyzers
|
|
- Implement scheduling for automated runs
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2026-02-16
|
|
**Architecture**: Integrated Python Package
|