Add ARCHITECTURE.md documenting the integrated package structure
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Kevin Bataille
196
ARCHITECTURE.md
Normal file
196
ARCHITECTURE.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user