# thecraighewitt/seomachine architecture

> Architecture diagram of the GitHub repository thecraighewitt/seomachine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thecraighewitt/seomachine
- Repository: https://github.com/thecraighewitt/seomachine

## Overview

This repository is a Claude Code workspace for an SEO content operations system, not a conventional application runtime. Its architecture is centered on human-in-the-loop workflows: research, drafting, optimization, rewriting, auditing, and publishing content through structured prompts, agents, and Python analysis modules.

1. **Primary orchestration layer: `.claude/commands/`**
   The main entry points are custom slash commands such as `/research`, `/write`, `/rewrite`, `/analyze-existing`, `/optimize`, `/priorities`, and the landing-page variants. These command files define the workflow steps and hand off work to agents, context files, or Python-backed analysis. In diagram terms, this is the control plane.

2. **Specialized agent layer: `.claude/agents/`**
   The agents split responsibilities into narrow roles: content analysis, SEO optimization, meta creation, internal linking, keyword mapping, editing, performance analysis, headline generation, CRO analysis, and landing-page optimization. They are downstream consumers of research briefs, drafts, and context, and they produce structured recommendations rather than final application state.

3. **Marketing skill library: `.claude/skills/`**
   The skills directory is a reusable knowledge base for specific marketing tasks: copywriting, CRO, paid ads, analytics tracking, A/B testing, schema markup, programmatic SEO, referral programs, and more. Architecturally, these are reference modules that inform agent behavior and command workflows, not executable business logic.

4. **Content strategy inputs: `context/` and `examples/`**
   The repo relies heavily on configuration-like editorial context: brand voice, writing examples, style guide, SEO guidelines, target keywords, internal links map, competitor analysis, and CRO best practices. The `examples/castos/` directory shows a fully populated real-world instance of those inputs. These files are the main boundary between generic tooling and business-specific output.

5. **Research and generation pipeline: `topics/`, `research/`, `drafts/`, `rewrites/`, `published/`**
   Content moves through a clear lifecycle. Topic ideas start in `topics/`, research briefs and analysis reports land in `research/`, first drafts in `drafts/`, updates in `rewrites/`, and final assets in `published/`. This directory structure is the repo’s artifact pipeline and is important for any architecture diagram showing state progression.

6. **Analytics and scoring engine: `data_sources/modules/`**
   The Python modules under `data_sources/modules/` provide the analytical backbone. They include search-intent classification, keyword analysis, content-length comparison, readability scoring, SEO quality rating, opportunity scoring, engagement analysis, competitor gap analysis, article planning, section writing, and social research aggregation. These modules transform raw inputs into scores, recommendations, and content strategy signals.

7. **External data integrations: Google Analytics, Search Console, DataForSEO**
   The repo integrates with GA4, Google Search Console, and DataForSEO through dedicated modules and scripts. These external services supply live performance, ranking, CTR, keyword, and competitor data. The `data_aggregator.py` module acts as a consolidation point for these sources, which is a key boundary in the system: external telemetry in, prioritized content actions out.

8. **Publishing boundary: `wordpress/`**
   Publishing is handled through WordPress REST API integration, with a custom MU-plugin (`seo-machine-yoast-rest.php`) exposing Yoast SEO fields and a theme snippet helper (`functions-snippet.php`). This is the output boundary of the system, where generated content and metadata leave the Claude workspace and become site content.

9. **Operational scripts at repo root**
   The root Python scripts such as `research_quick_wins.py`, `research_competitor_gaps.py`, `research_performance_matrix.py`, `research_serp_analysis.py`, `research_topic_clusters.py`, and `seo_competitor_analysis.py` are batch analysis entry points. They appear to be standalone orchestration scripts that likely reuse the same modules but run outside the Claude command flow for repeated analysis tasks.

10. **Configuration and environment layer: `config/`, `data_sources/config/`, `.env.example`**
   Repo-level configuration includes competitor templates, credentials templates, and environment setup for API keys and WordPress publishing. This layer defines how the system is adapted per business and how it connects to external services. It is essential to represent as a non-code dependency boundary in the architecture.

11. **Caching and ephemeral state: `data_sources/cache/`**
   The cache directory indicates that analysis modules store intermediate API responses or derived results locally to reduce repeated external calls. This is an infrastructure concern that sits between analysis modules and third-party APIs, improving speed and cost.

12. **Workflow outputs and review artifacts**
   The repo also contains output-oriented directories like `output/`, `audits/`, and `landing-pages/` in addition to the main content lifecycle folders. These represent generated reports and content variants used during review, optimization, and conversion-focused work. They are useful to show as side outputs of the analysis pipeline.

13. **Two major content tracks: SEO articles and landing pages**
   The architecture supports both informational SEO content and conversion-oriented landing pages. The article track runs through research → drafting → optimization → publishing, while the landing-page track runs through landing research → landing write → CRO audit → landing publish. They share context and analytics but use different agents and scoring models.

14. **Overall system flow**
   In practice, the system works as: topic or performance signal in → contextual research and external data aggregation → agent-driven analysis and drafting → SEO/CRO optimization and editorial review → WordPress publishing. The key architectural characteristic is that content strategy is data-informed, but final output is generated and curated through layered prompts, templates, and scoring modules rather than a monolithic app server.

Main entry points: [`.claude/commands`](https://github.com/thecraighewitt/seomachine/blob/main/.claude/commands) (Commands), [`data_sources/modules`](https://github.com/thecraighewitt/seomachine/tree/main/data_sources/modules) (Scoring modules), [`research`](https://github.com/thecraighewitt/seomachine/tree/main/research) (Research), [`.claude/agents`](https://github.com/thecraighewitt/seomachine/blob/main/.claude/agents) (Agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control_plane["Control plane"]
  node_commands["Commands<br/>[commands]"]
  node_agents["Agents<br/>specialized roles<br/>[agents]"]
end

subgraph group_knowledge["Knowledge base"]
  node_skills["Skills<br/>marketing playbooks<br/>[skills]"]
  node_context["Context<br/>brand inputs"]
  node_examples["Examples<br/>reference instance"]
end

subgraph group_pipeline["Content pipeline"]
  node_topics["Topics<br/>idea backlog"]
  node_research["Research<br/>briefs and reports"]
  node_drafts["Drafts<br/>first-pass content"]
  node_rewrites["Rewrites<br/>revision stage"]
  node_published["Published<br/>final assets"]
  node_output["Output<br/>generated reports"]
end

subgraph group_analytics["Analytics engine"]
  node_data_aggregator[("Data aggregator<br/>integration hub<br/>[data_aggregator.py]")]
  node_analysis_modules["Scoring modules<br/>analysis library"]
  node_external_sources[("External sources<br/>GA4 GSC DataForSEO")]
end

subgraph group_publishing["Publishing boundary"]
  node_wordpress["WordPress<br/>publishing integration"]
end

node_scripts["Batch scripts<br/>standalone orchestration"]
node_config["Config<br/>environment setup"]

node_commands -->|"dispatches"| node_agents
node_commands -->|"consults"| node_skills
node_commands -->|"grounds in"| node_context
node_commands -->|"starts from"| node_topics
node_commands -->|"produces"| node_research
node_commands -->|"writes"| node_drafts
node_commands -->|"refines"| node_rewrites
node_agents -->|"uses"| node_analysis_modules
node_agents -->|"applies"| node_context
node_examples -->|"instantiates"| node_context
node_topics -->|"feeds"| node_research
node_research -->|"informs"| node_drafts
node_drafts -->|"iterates to"| node_rewrites
node_rewrites -->|"finalizes"| node_published
node_analysis_modules -->|"converges in"| node_data_aggregator
node_data_aggregator -->|"pulls from"| node_external_sources
node_analysis_modules -->|"scores"| node_research
node_analysis_modules -->|"emits"| node_output
node_scripts -->|"reuses"| node_analysis_modules
node_scripts -->|"generates"| node_research
node_wordpress -->|"receives"| node_published
node_config -->|"configures"| node_data_aggregator
node_config -->|"configures"| node_wordpress

click node_commands "https://github.com/thecraighewitt/seomachine/blob/main/.claude/commands"
click node_agents "https://github.com/thecraighewitt/seomachine/blob/main/.claude/agents"
click node_skills "https://github.com/thecraighewitt/seomachine/blob/main/.claude/skills"
click node_context "https://github.com/thecraighewitt/seomachine/tree/main/context"
click node_examples "https://github.com/thecraighewitt/seomachine/tree/main/examples/castos"
click node_topics "https://github.com/thecraighewitt/seomachine/tree/main/topics"
click node_research "https://github.com/thecraighewitt/seomachine/tree/main/research"
click node_drafts "https://github.com/thecraighewitt/seomachine/tree/main/drafts"
click node_rewrites "https://github.com/thecraighewitt/seomachine/tree/main/rewrites"
click node_published "https://github.com/thecraighewitt/seomachine/tree/main/published"
click node_output "https://github.com/thecraighewitt/seomachine/tree/main/output"
click node_data_aggregator "https://github.com/thecraighewitt/seomachine/blob/main/data_sources/modules/data_aggregator.py"
click node_analysis_modules "https://github.com/thecraighewitt/seomachine/tree/main/data_sources/modules"
click node_external_sources "https://github.com/thecraighewitt/seomachine/blob/main/data_sources/modules/google_analytics.py"
click node_wordpress "https://github.com/thecraighewitt/seomachine/tree/main/wordpress"
click node_config "https://github.com/thecraighewitt/seomachine/tree/main/config"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commands,node_agents toneBlue
class node_skills,node_context,node_examples toneAmber
class node_topics,node_research,node_drafts,node_rewrites,node_published,node_output toneMint
class node_data_aggregator,node_analysis_modules,node_external_sources toneRose
class node_wordpress toneIndigo
class node_scripts,node_config toneNeutral
```

## Components

### Control plane

Claude commands and agents that orchestrate human-in-the-loop workflows.

- [Commands](https://github.com/thecraighewitt/seomachine/blob/main/.claude/commands): claude slash commands · Primary workflow entry points for research, writing, optimization, audits, and publishing. · `.claude/commands`
- [Agents](https://github.com/thecraighewitt/seomachine/blob/main/.claude/agents): specialized roles · Narrow-purpose agents for analysis, SEO, editing, CRO, metadata, and performance work. · `.claude/agents`

### Knowledge base

Reusable marketing skills and business-specific context inputs.

- [Skills](https://github.com/thecraighewitt/seomachine/blob/main/.claude/skills): marketing playbooks · Reusable marketing and growth knowledge used to guide prompts and agent behavior. · `.claude/skills`
- [Context](https://github.com/thecraighewitt/seomachine/tree/main/context): brand inputs · Repository-specific editorial and SEO guidance such as voice, keywords, links, and style. · `context`
- [Examples](https://github.com/thecraighewitt/seomachine/tree/main/examples/castos): reference instance · Concrete business example set used to ground the generic workflows. · `examples/castos`

### Content pipeline

Topic, research, draft, rewrite, and published artifact flow.

- [Topics](https://github.com/thecraighewitt/seomachine/tree/main/topics): idea backlog · Seed ideas and content opportunities before research begins. · `topics`
- [Research](https://github.com/thecraighewitt/seomachine/tree/main/research): briefs and reports · Research outputs, SERP analysis, competitor gaps, and performance investigation artifacts. · `research`
- [Drafts](https://github.com/thecraighewitt/seomachine/tree/main/drafts): first-pass content · Working article drafts before optimization or rewrite. · `drafts`
- [Rewrites](https://github.com/thecraighewitt/seomachine/tree/main/rewrites): revision stage · Updated content versions after audit, optimization, or editorial feedback. · `rewrites`
- [Published](https://github.com/thecraighewitt/seomachine/tree/main/published): final assets · Final content artifacts after approval and publishing. · `published`
- [Output](https://github.com/thecraighewitt/seomachine/tree/main/output): generated reports · Standalone generated reports and content outputs outside the main lifecycle folders. · `output`

### Analytics engine

Python modules that score, analyze, and aggregate external data.

- [Data aggregator](https://github.com/thecraighewitt/seomachine/blob/main/data_sources/modules/data_aggregator.py): integration hub · Consolidates external telemetry and keyword/ranking data into analysis-ready inputs. · `data_sources/modules/data_aggregator.py`
- [Scoring modules](https://github.com/thecraighewitt/seomachine/tree/main/data_sources/modules): analysis library · SEO, readability, opportunity, intent, engagement, and landing-page scoring modules. · `data_sources/modules`
- [External sources](https://github.com/thecraighewitt/seomachine/blob/main/data_sources/modules/google_analytics.py): GA4 GSC DataForSEO · Live search, traffic, CTR, and competitor data pulled from external services. · `data_sources/modules/google_analytics.py`

### Publishing boundary

WordPress integration and final content handoff.

- [WordPress](https://github.com/thecraighewitt/seomachine/tree/main/wordpress): publishing integration · REST publishing boundary and Yoast field exposure for final site delivery. · `wordpress`

### Other components

- **Batch scripts**: standalone orchestration · Root-level analysis entry points for recurring research and ranking workflows.
- [Config](https://github.com/thecraighewitt/seomachine/tree/main/config): environment setup · Repo and data-source configuration, credentials templates, and environment definitions. · `config`

## Connections

- Commands → Agents: dispatches · Slash commands hand work to role-specific agents.
- Commands → Skills: consults · Workflows reference reusable marketing playbooks.
- Commands → Context: grounds in · Commands use brand, SEO, and editorial context.
- Commands → Topics: starts from · Topic and priority commands seed the pipeline.
- Commands → Research: produces · Research commands generate briefs and analysis artifacts.
- Commands → Drafts: writes · Writing commands create draft content.
- Commands → Rewrites: refines · Rewrite and optimize commands create revised assets.
- Agents → Scoring modules: uses · Agents rely on scoring and analysis helpers for recommendations.
- Agents → Context: applies · Agents incorporate repository-specific guidance.
- Examples → Context: instantiates · The example workspace shows a filled-in version of the context layer.
- Topics → Research: feeds · Ideas become research briefs and SERP investigations.
- Research → Drafts: informs · Research outputs shape first drafts.
- Drafts → Rewrites: iterates to · Drafts move into optimization and revision.
- Rewrites → Published: finalizes · Rewritten content becomes publishable output.
- Scoring modules → Data aggregator: converges in · Analytical results are combined through the aggregator.
- Data aggregator → External sources: pulls from · Aggregation depends on live telemetry and keyword services.
- Scoring modules → Research: scores · Analysis modules produce research signals and content recommendations.
- Scoring modules → Output: emits · Batch analysis often lands in generated reports.
- Batch scripts → Scoring modules: reuses · Root scripts reuse the shared Python analysis library.
- Batch scripts → Research: generates · Standalone scripts produce research artifacts.
- WordPress → Published: receives · Final content is handed to the publishing boundary.
- Config → Data aggregator: configures · API keys and source settings shape the analytics layer.
- Config → WordPress: configures · Publishing credentials and site settings control WordPress integration.
