seo/ARCHITECTURE.md

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:

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

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

# 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

# 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

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