# nowork-studio/toprank architecture

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

- Interactive diagram: https://gitdiagram.com/nowork-studio/toprank
- Repository: https://github.com/nowork-studio/toprank

## Overview

1. **What this repo is**
   Toprank is not a traditional application or service; it is a **collection of agent skills** for Claude Code and Codex. Each skill is an instruction pack plus optional scripts and references that guide an AI agent to perform SEO or Google Ads tasks end-to-end.

2. **Primary architectural boundary: skill-based workflows**
   The core unit is a `SKILL.md` file. The agent loads the skill, follows its workflow, and may call local scripts or external APIs. This means the “application logic” lives mostly in **prompted procedures**, not in a long-running server.

3. **Two main product domains**
   The repo is split into:
   - `seo/` for SEO analysis, content, keyword research, metadata, schema, and CMS setup
   - `google-ads/` for Ads audit, account management, and ad copy generation  
   These are separate operational domains with different external systems, but they share the same skill packaging model.

4. **SEO analysis subsystem**
   `seo/seo-analysis/` is the most code-heavy skill. It combines:
   - Search Console analysis scripts
   - CMS detection and content fetch/push scripts
   - preflight checks for multiple CMSs
   - URL inspection and site audit helpers  
   This skill is the main data-ingestion and diagnostic pipeline for SEO.

5. **CMS integration boundary**
   The SEO analysis skill includes adapters for several CMS platforms:
   - Contentful
   - Ghost
   - Strapi
   - WordPress  
   The repo treats CMSs as pluggable backends. The analysis workflow can detect the CMS, fetch content, and in some cases push SEO updates back to the CMS.

6. **Google Search Console data flow**
   The SEO audit flow centers on Search Console:
   - setup guidance and site listing
   - pulling 90 days of query/page data
   - analyzing traffic drops, CTR issues, and position opportunities
   - generating prioritized actions  
   The scripts in `seo/seo-analysis/scripts/` are the main bridge between the agent and GSC.

7. **SEO content creation pipeline**
   `seo/content-writer/` consumes findings from analysis and turns them into publishable content. It is supported by reference docs for writing quality and SEO conventions, but it does not appear to have heavy runtime code; it is primarily a guided content-generation skill.

8. **Keyword, metadata, and schema support skills**
   These are narrower SEO specialist skills:
   - `keyword-research/` discovers, classifies, and prioritizes terms
   - `meta-tags-optimizer/` generates title tags, descriptions, and social tags
   - `schema-markup-generator/` produces JSON-LD structured data  
   They form a content optimization toolchain that can feed the content writer or standalone optimization tasks.

9. **Google Ads subsystem**
   `google-ads/ads-audit/`, `google-ads/ads/`, and `google-ads/ads-copy/` cover the Ads side:
   - auditing account health and spend efficiency
   - managing campaigns, keywords, bids, negatives, and ads
   - generating RSA ad copy and A/B tests  
   The audit skill also creates reusable **business context** for the rest of the Ads workflows.

10. **External Ads service integration**
   The Ads workflows depend on an external MCP-based AdsAgent integration. The repo includes `google-ads/ads/mcporter.json`, which is the service configuration boundary for connecting the agent to Google Ads actions and reads.

11. **Persistent state and cross-skill reuse**
   One notable stateful element is the business context saved by ads audit to `~/.adsagent/business-context.json`. That file is reused by later ads-copy or optimization tasks, so the Ads side has a shared local memory layer across skills.

12. **Installer and runtime integration**
   The `setup` flow and `bin/` utilities are the repo’s operational glue. `bin/toprank-config` and `bin/toprank-update-check` support installation/configuration and version management, while the setup process registers skills into the correct agent host directories (`.agents/skills` for Codex, `~/.claude/skills` for Claude Code).

13. **Testing and validation architecture**
   The repo includes layered tests:
   - unit tests for scripts and URL inspection
   - end-to-end skill routing and execution tests
   - LLM evaluation tests
   - fixtures that mock `gcloud` and Search Console responses  
   This shows the project validates both deterministic script behavior and agent-driven skill behavior.

14. **Documentation and reference-driven design**
   The `references/` folders under each skill are part of the runtime design, not just docs. They provide frameworks, templates, and validation rules that shape the agent’s output quality. In architecture terms, they are the “knowledge base” each skill depends on.

15. **Overall data flow**
   Typical flow is: user trigger → skill selection → `SKILL.md` workflow → local scripts/reference docs → external service calls to Google Search Console or Google Ads / CMS APIs → structured report or direct changes. The repo is therefore a **tooling-and-workflow platform for AI agents**, with external integrations and local state, rather than a conventional monolithic app.

Main entry points: [`seo/seo-analysis/SKILL.md`](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/SKILL.md) (SEO Analysis), [`google-ads/ads-audit/SKILL.md`](https://github.com/nowork-studio/toprank/blob/main/google-ads/ads-audit/SKILL.md) (Ads Audit), [`setup`](https://github.com/nowork-studio/toprank/tree/main/setup) (Setup), [`seo/content-writer/SKILL.md`](https://github.com/nowork-studio/toprank/blob/main/seo/content-writer/SKILL.md) (Content Writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_agent_hosts{{"Agent Hosts<br/>runtime target"}}
  node_setup_flow["Setup<br/>installer"]
  node_bin_config["Config Tool<br/>cli"]
  node_bin_update["Update Check<br/>cli"]
  node_upgrade_skill["Upgrade Skill<br/>[SKILL.md]"]
end

subgraph group_seo["SEO"]
  node_skill_seo_analysis["SEO Analysis<br/>skill orchestrator<br/>[SKILL.md]"]
  node_gsc_analyze["GSC Analyze<br/>script<br/>[analyze_gsc.py]"]
  node_cms_detect["CMS Detect<br/>script<br/>[cms_detect.py]"]
  node_cms_adapters{{"CMS Adapters<br/>adapter layer"}}
  node_seo_preflight["Preflight<br/>checks<br/>[preflight.py]"]
  node_url_inspection["URL Inspection<br/>script<br/>[url_inspection.py]"]
  node_gsc_setup_ref["GSC Setup<br/>reference<br/>[gsc_setup.md]"]
  node_skill_content_writer["Content Writer<br/>skill<br/>[SKILL.md]"]
  node_skill_keyword_research["Keyword Research<br/>skill<br/>[SKILL.md]"]
  node_skill_meta_optimizer["Meta Optimizer<br/>skill<br/>[SKILL.md]"]
  node_skill_schema_generator["Schema Generator<br/>skill<br/>[SKILL.md]"]
  node_search_console_external{{"Search Console<br/>external service"}}
  node_cms_external{{"CMS Backends<br/>external service"}}
end

subgraph group_ads["Google Ads"]
  node_skill_ads_audit["Ads Audit<br/>skill<br/>[SKILL.md]"]
  node_skill_ads_manage["Ads Manager<br/>skill<br/>[SKILL.md]"]
  node_skill_ads_copy["Ads Copy<br/>skill<br/>[SKILL.md]"]
  node_ads_mcporter["Ads MCP Config<br/>integration config<br/>[mcporter.json]"]
  node_ads_agent_external{{"AdsAgent<br/>external service"}}
end

subgraph group_quality["Quality"]
  node_test_suite(("Tests<br/>validation suite"))
  node_gsc_fixture["GSC Fixture<br/>test fixture"]
end

node_skill_seo_analysis -->|"runs"| node_gsc_analyze
node_skill_seo_analysis -->|"detects"| node_cms_detect
node_skill_seo_analysis -->|"preflights"| node_seo_preflight
node_skill_seo_analysis -->|"inspects"| node_url_inspection
node_skill_seo_analysis -.->|"guided by"| node_gsc_setup_ref
node_gsc_analyze -->|"reads"| node_search_console_external
node_cms_detect -->|"selects"| node_cms_adapters
node_seo_preflight -->|"checks"| node_cms_adapters
node_cms_adapters -->|"connects"| node_cms_external
node_skill_seo_analysis -->|"feeds findings"| node_skill_content_writer
node_skill_keyword_research -->|"prioritizes topics"| node_skill_content_writer
node_skill_meta_optimizer -->|"optimizes drafts"| node_skill_content_writer
node_skill_schema_generator -->|"adds schema"| node_skill_content_writer
node_skill_ads_audit -->|"uses"| node_ads_mcporter
node_ads_mcporter -->|"routes to"| node_ads_agent_external
node_skill_ads_audit -->|"shares context"| node_skill_ads_manage
node_skill_ads_audit -->|"seeds copy"| node_skill_ads_copy
node_skill_ads_audit -.->|"borrows terms"| node_skill_keyword_research
node_setup_flow -->|"installs to"| node_agent_hosts
node_setup_flow -->|"uses"| node_bin_config
node_setup_flow -->|"uses"| node_bin_update
node_upgrade_skill -.->|"maintains"| node_setup_flow
node_test_suite -->|"covers"| node_skill_seo_analysis
node_test_suite -->|"covers"| node_skill_ads_audit
node_test_suite -->|"mocks"| node_gsc_fixture

click node_skill_seo_analysis "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/SKILL.md"
click node_gsc_analyze "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/analyze_gsc.py"
click node_cms_detect "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/cms_detect.py"
click node_seo_preflight "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/preflight.py"
click node_url_inspection "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/url_inspection.py"
click node_gsc_setup_ref "https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/references/gsc_setup.md"
click node_skill_content_writer "https://github.com/nowork-studio/toprank/blob/main/seo/content-writer/SKILL.md"
click node_skill_keyword_research "https://github.com/nowork-studio/toprank/blob/main/seo/keyword-research/SKILL.md"
click node_skill_meta_optimizer "https://github.com/nowork-studio/toprank/blob/main/seo/meta-tags-optimizer/SKILL.md"
click node_skill_schema_generator "https://github.com/nowork-studio/toprank/blob/main/seo/schema-markup-generator/SKILL.md"
click node_skill_ads_audit "https://github.com/nowork-studio/toprank/blob/main/google-ads/ads-audit/SKILL.md"
click node_skill_ads_manage "https://github.com/nowork-studio/toprank/blob/main/google-ads/ads/SKILL.md"
click node_skill_ads_copy "https://github.com/nowork-studio/toprank/blob/main/google-ads/ads-copy/SKILL.md"
click node_ads_mcporter "https://github.com/nowork-studio/toprank/blob/main/google-ads/ads/mcporter.json"
click node_setup_flow "https://github.com/nowork-studio/toprank/tree/main/setup"
click node_bin_config "https://github.com/nowork-studio/toprank/tree/main/bin/toprank-config"
click node_bin_update "https://github.com/nowork-studio/toprank/tree/main/bin/toprank-update-check"
click node_upgrade_skill "https://github.com/nowork-studio/toprank/blob/main/toprank-upgrade/SKILL.md"
click node_test_suite "https://github.com/nowork-studio/toprank/tree/main/test"
click node_gsc_fixture "https://github.com/nowork-studio/toprank/blob/main/test/fixtures/sample_gsc_data.json"

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_agent_hosts,node_setup_flow,node_bin_config,node_bin_update,node_upgrade_skill toneBlue
class node_skill_seo_analysis,node_gsc_analyze,node_cms_detect,node_cms_adapters,node_seo_preflight,node_url_inspection,node_gsc_setup_ref,node_skill_content_writer,node_skill_keyword_research,node_skill_meta_optimizer,node_skill_schema_generator,node_search_console_external,node_cms_external toneAmber
class node_skill_ads_audit,node_skill_ads_manage,node_skill_ads_copy,node_ads_mcporter,node_ads_agent_external toneMint
class node_test_suite,node_gsc_fixture toneRose
```

## Components

### Platform

Installation, upgrade, and skill packaging for agent hosts.

- **Agent Hosts**: runtime target · Codex and Claude Code skill directories used during installation.
- [Setup](https://github.com/nowork-studio/toprank/tree/main/setup): installer · Registers skills and prepares local agent runtime integration. · `setup`
- [Config Tool](https://github.com/nowork-studio/toprank/tree/main/bin/toprank-config): cli · Operational glue for configuration and setup tasks. · `bin/toprank-config`
- [Update Check](https://github.com/nowork-studio/toprank/tree/main/bin/toprank-update-check): cli · Checks for version updates and maintenance state. · `bin/toprank-update-check`
- [Upgrade Skill](https://github.com/nowork-studio/toprank/blob/main/toprank-upgrade/SKILL.md): skill · Skill used to guide repository upgrade and maintenance workflows. · `toprank-upgrade/SKILL.md`

### SEO

SEO analysis and content optimization skills.

- [SEO Analysis](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/SKILL.md): skill orchestrator · Main SEO workflow that coordinates GSC analysis, CMS inspection, and update helpers. · `seo/seo-analysis/SKILL.md`
- [GSC Analyze](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/analyze_gsc.py): script · Pulls and analyzes Search Console query/page data for drops, CTR, and opportunities. · `seo/seo-analysis/scripts/analyze_gsc.py`
- [CMS Detect](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/cms_detect.py): script · Detects the site CMS before content fetch or update steps. · `seo/seo-analysis/scripts/cms_detect.py`
- **CMS Adapters**: adapter layer · Pluggable content backends for Contentful, Ghost, Strapi, and WordPress.
- [Preflight](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/preflight.py): checks · CMS-specific readiness checks before content or SEO operations. · `seo/seo-analysis/scripts/preflight.py`
- [URL Inspection](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/scripts/url_inspection.py): script · Inspects URLs as part of SEO diagnostics and audit flows. · `seo/seo-analysis/scripts/url_inspection.py`
- [GSC Setup](https://github.com/nowork-studio/toprank/blob/main/seo/seo-analysis/references/gsc_setup.md): reference · Setup guidance and operating notes for Search Console access. · `seo/seo-analysis/references/gsc_setup.md`
- [Content Writer](https://github.com/nowork-studio/toprank/blob/main/seo/content-writer/SKILL.md): skill · Turns SEO findings into publishable content plans and drafts. · `seo/content-writer/SKILL.md`
- [Keyword Research](https://github.com/nowork-studio/toprank/blob/main/seo/keyword-research/SKILL.md): skill · Discovers, classifies, and prioritizes target terms. · `seo/keyword-research/SKILL.md`
- [Meta Optimizer](https://github.com/nowork-studio/toprank/blob/main/seo/meta-tags-optimizer/SKILL.md): skill · Generates title tags, descriptions, and social metadata. · `seo/meta-tags-optimizer/SKILL.md`
- [Schema Generator](https://github.com/nowork-studio/toprank/blob/main/seo/schema-markup-generator/SKILL.md): skill · Produces JSON-LD structured data and validation guidance. · `seo/schema-markup-generator/SKILL.md`
- **Search Console**: external service · Primary SEO data source for site, query, and page performance.
- **CMS Backends**: external service · Contentful, Ghost, Strapi, and WordPress endpoints used by SEO workflows.

### Google Ads

Ads audit, management, and copy skills.

- [Ads Audit](https://github.com/nowork-studio/toprank/blob/main/google-ads/ads-audit/SKILL.md): skill · Audits account health and creates reusable business context. · `google-ads/ads-audit/SKILL.md`
- [Ads Manager](https://github.com/nowork-studio/toprank/blob/main/google-ads/ads/SKILL.md): skill · Manages campaigns, keywords, bids, negatives, and ads. · `google-ads/ads/SKILL.md`
- [Ads Copy](https://github.com/nowork-studio/toprank/blob/main/google-ads/ads-copy/SKILL.md): skill · Generates RSA ad copy and A/B test variants. · `google-ads/ads-copy/SKILL.md`
- [Ads MCP Config](https://github.com/nowork-studio/toprank/blob/main/google-ads/ads/mcporter.json): integration config · Service boundary for the external AdsAgent / MCP integration. · `google-ads/ads/mcporter.json`
- **AdsAgent**: external service · External Google Ads execution and read layer used by Ads workflows.

### Quality

Tests, fixtures, and validation helpers.

- [Tests](https://github.com/nowork-studio/toprank/tree/main/test): validation suite · Unit, end-to-end, and LLM evaluation coverage for skill behavior. · `test`
- [GSC Fixture](https://github.com/nowork-studio/toprank/blob/main/test/fixtures/sample_gsc_data.json): test fixture · Mock Search Console data used by analyzer and routing tests. · `test/fixtures/sample_gsc_data.json`

## Connections

- SEO Analysis → GSC Analyze: runs
- SEO Analysis → CMS Detect: detects
- SEO Analysis → Preflight: preflights
- SEO Analysis → URL Inspection: inspects
- SEO Analysis → GSC Setup: guided by
- GSC Analyze → Search Console: reads
- CMS Detect → CMS Adapters: selects
- Preflight → CMS Adapters: checks
- CMS Adapters → CMS Backends: connects
- SEO Analysis → Content Writer: feeds findings
- Keyword Research → Content Writer: prioritizes topics
- Meta Optimizer → Content Writer: optimizes drafts
- Schema Generator → Content Writer: adds schema
- Ads Audit → Ads MCP Config: uses
- Ads MCP Config → AdsAgent: routes to
- Ads Audit → Ads Manager: shares context
- Ads Audit → Ads Copy: seeds copy
- Ads Audit → Keyword Research: borrows terms
- Setup → Agent Hosts: installs to
- Setup → Config Tool: uses
- Setup → Update Check: uses
- Upgrade Skill → Setup: maintains
- Tests → SEO Analysis: covers
- Tests → Ads Audit: covers
- Tests → GSC Fixture: mocks
