# zensink/zens-ink-seo-package architecture

> Architecture diagram of the GitHub repository zensink/zens-ink-seo-package, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zensink/zens-ink-seo-package
- Repository: https://github.com/zensink/zens-ink-seo-package

## Overview

ZensInk is a Python CLI SEO toolkit: users discover keywords, assess demand and competition, find content opportunities, then audit pages or review search performance. Its modules also offer intent analysis, Reddit mining, GEO/AI-readiness tools, and rank tracking; the MCP server exposes tools to agent clients. The README documents the workflow and capability set, while source excerpts show selected module behavior and calls. Connections among unsampled modules are omitted where their runtime wiring is not evidenced.

Main entry points: [`zens_ink/keyword_research.py`](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_research.py) (Keyword Research), [`zens_ink/mcp.py`](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/mcp.py) (MCP Server), [`zens_ink/keyword_volume.py`](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_volume.py) (Keyword Volume), [`zens_ink/kd.py`](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/kd.py) (Keyword Difficulty)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Keyword Discovery"]
  node_research["Keyword Research"]
  node_reddit["Reddit Mining"]
  node_volume["Keyword Volume<br/>[keyword_volume.py]"]
  node_brave_volume["Brave Volume<br/>[brave_volume.py]"]
  node_cluster["Keyword Clustering<br/>[keyword_cluster.py]"]
end

subgraph group_analysis["SEO Analysis"]
  node_difficulty["Keyword Difficulty<br/>[kd.py]"]
  node_kgr["KGR Scoring<br/>[kgr_auto.py]"]
  node_domain_rating["Domain Rating<br/>[domain_rating.py]"]
  node_search_intent["Keyword Intent<br/>[search_intent.py]"]
  node_serp_intent["SERP Intent<br/>[serp_intent.py]"]
  node_rank_tracker[("Rank History<br/>[rank_tracker.py]")]
end

subgraph group_planning["Content Planning"]
  node_content_matrix["Opportunity Matrix<br/>[content_matrix.py]"]
  node_competitor_gap["Competitor Gaps<br/>[competitor_gap.py]"]
  node_geo_fanout["GEO Fan-out<br/>[geo_fanout.py]"]
end

subgraph group_audits["Site Audits"]
  node_site_audit["Technical and GEO Audit<br/>[site_audit.py]"]
  node_onpage["On-page Scoring<br/>[onpage_audit.py]"]
  node_content_qc["Content Quality Gate<br/>[content_qc.py]"]
  node_ai_crawler["AI Crawler Audit"]
  node_llms_gen["LLMs File Generator<br/>[llms_gen.py]"]
end

subgraph group_interfaces["Interfaces and Config"]
  node_setup_gsc["GSC OAuth Setup<br/>[setup_gsc.py]"]
  node_search_performance["GSC Performance"]
  node_config["Shared Configuration<br/>[config.py]"]
  node_mcp["MCP Server<br/>[mcp.py]"]
end

node_user(("SEO User"))
node_agents(("MCP Clients"))
node_google_auto["Google Autocomplete"]
node_serper["Serper API"]
node_bing["Bing Webmaster"]
node_brave["Brave Search"]
node_ahrefs["Ahrefs API"]
node_reddit_api["Reddit API"]
node_gsc["Google Search Console"]

node_user -->|"runs tool"| node_research
node_research -->|"fetches suggestions"| node_google_auto
node_user -->|"checks demand"| node_volume
node_user -->|"checks difficulty"| node_difficulty
node_user -->|"compares sites"| node_competitor_gap
node_user -->|"audits site"| node_site_audit
node_user -->|"reviews rankings"| node_search_performance
node_reddit -->|"reuses autocomplete"| node_research
node_reddit -->|"searches posts"| node_reddit_api
node_volume -.->|"fetches volume"| node_bing
node_brave_volume -.->|"checks demand"| node_brave
node_domain_rating -.->|"fetches rating"| node_ahrefs
node_difficulty -->|"fetches SERP"| node_serper
node_serp_intent -->|"cross-validates"| node_search_intent
node_kgr -->|"uses suggestions"| node_research
node_kgr -->|"uses volume"| node_volume
node_onpage -->|"reuses audit"| node_site_audit
node_search_performance -->|"queries analytics"| node_gsc
node_setup_gsc -.->|"sets up OAuth"| node_gsc
node_search_performance -->|"reads settings"| node_config
node_volume -.->|"reads settings"| node_config
node_difficulty -->|"reads settings"| node_config
node_agents -->|"connects via stdio"| node_mcp
node_mcp -.->|"dispatches tool"| node_research
node_mcp -.->|"dispatches tool"| node_difficulty
node_mcp -.->|"dispatches tool"| node_site_audit

click node_research "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_research.py"
click node_reddit "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/reddit_blueocean.py"
click node_volume "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_volume.py"
click node_brave_volume "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/brave_volume.py"
click node_cluster "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_cluster.py"
click node_difficulty "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/kd.py"
click node_kgr "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/kgr_auto.py"
click node_domain_rating "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/domain_rating.py"
click node_search_intent "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/search_intent.py"
click node_serp_intent "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/serp_intent.py"
click node_rank_tracker "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/rank_tracker.py"
click node_content_matrix "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/content_matrix.py"
click node_competitor_gap "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/competitor_gap.py"
click node_geo_fanout "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/geo_fanout.py"
click node_site_audit "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/site_audit.py"
click node_onpage "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/onpage_audit.py"
click node_content_qc "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/content_qc.py"
click node_ai_crawler "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/ai_crawler_audit.py"
click node_llms_gen "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/llms_gen.py"
click node_setup_gsc "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/setup_gsc.py"
click node_search_performance "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/search_performance.py"
click node_config "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/config.py"
click node_mcp "https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/mcp.py"

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_research,node_reddit,node_volume,node_brave_volume,node_cluster,node_user,node_agents toneBlue
class node_difficulty,node_kgr,node_domain_rating,node_search_intent,node_serp_intent,node_rank_tracker toneAmber
class node_content_matrix,node_competitor_gap,node_geo_fanout,node_serper,node_ahrefs,node_reddit_api toneMint
class node_site_audit,node_onpage,node_content_qc,node_ai_crawler,node_llms_gen toneRose
class node_setup_gsc,node_search_performance,node_config,node_mcp,node_google_auto,node_bing,node_brave,node_gsc toneIndigo
```

## Components

### Keyword Discovery

- [Keyword Research](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_research.py): `zens_ink/keyword_research.py`
- [Reddit Mining](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/reddit_blueocean.py): `zens_ink/reddit_blueocean.py`
- [Keyword Volume](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_volume.py): `zens_ink/keyword_volume.py`
- [Brave Volume](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/brave_volume.py): `zens_ink/brave_volume.py`
- [Keyword Clustering](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/keyword_cluster.py): `zens_ink/keyword_cluster.py`

### SEO Analysis

- [Keyword Difficulty](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/kd.py): `zens_ink/kd.py`
- [KGR Scoring](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/kgr_auto.py): `zens_ink/kgr_auto.py`
- [Domain Rating](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/domain_rating.py): `zens_ink/domain_rating.py`
- [Keyword Intent](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/search_intent.py): `zens_ink/search_intent.py`
- [SERP Intent](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/serp_intent.py): `zens_ink/serp_intent.py`
- [Rank History](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/rank_tracker.py): `zens_ink/rank_tracker.py`

### Content Planning

- [Opportunity Matrix](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/content_matrix.py): `zens_ink/content_matrix.py`
- [Competitor Gaps](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/competitor_gap.py): `zens_ink/competitor_gap.py`
- [GEO Fan-out](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/geo_fanout.py): `zens_ink/geo_fanout.py`

### Site Audits

- [Technical and GEO Audit](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/site_audit.py): `zens_ink/site_audit.py`
- [On-page Scoring](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/onpage_audit.py): `zens_ink/onpage_audit.py`
- [Content Quality Gate](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/content_qc.py): `zens_ink/content_qc.py`
- [AI Crawler Audit](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/ai_crawler_audit.py): `zens_ink/ai_crawler_audit.py`
- [LLMs File Generator](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/llms_gen.py): `zens_ink/llms_gen.py`

### Interfaces and Config

- [GSC OAuth Setup](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/setup_gsc.py): `zens_ink/setup_gsc.py`
- [GSC Performance](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/search_performance.py): `zens_ink/search_performance.py`
- [Shared Configuration](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/config.py): `zens_ink/config.py`
- [MCP Server](https://github.com/zensink/zens-ink-seo-package/blob/main/zens_ink/mcp.py): `zens_ink/mcp.py`

### Other components

- **SEO User**
- **MCP Clients**
- **Google Autocomplete**
- **Serper API**
- **Bing Webmaster**
- **Brave Search**
- **Ahrefs API**
- **Reddit API**
- **Google Search Console**

## Connections

- SEO User → Keyword Research: runs tool (evidence: `README.md`)
- Keyword Research → Google Autocomplete: fetches suggestions (evidence: `zens_ink/keyword_research.py`)
- SEO User → Keyword Volume: checks demand (evidence: `README.md`)
- SEO User → Keyword Difficulty: checks difficulty (evidence: `README.md`)
- SEO User → Competitor Gaps: compares sites (evidence: `README.md`)
- SEO User → Technical and GEO Audit: audits site (evidence: `README.md`)
- SEO User → GSC Performance: reviews rankings (evidence: `README.md`)
- Reddit Mining → Keyword Research: reuses autocomplete (evidence: `zens_ink/reddit_blueocean.py`)
- Reddit Mining → Reddit API: searches posts (evidence: `zens_ink/reddit_blueocean.py`)
- Keyword Volume → Bing Webmaster: fetches volume (evidence: `README.md`)
- Brave Volume → Brave Search: checks demand (evidence: `README.md`)
- Domain Rating → Ahrefs API: fetches rating (evidence: `README.md`)
- Keyword Difficulty → Serper API: fetches SERP (evidence: `zens_ink/kd.py`)
- SERP Intent → Keyword Intent: cross-validates (evidence: `zens_ink/serp_intent.py`)
- KGR Scoring → Keyword Research: uses suggestions (evidence: `zens_ink/kgr_auto.py`)
- KGR Scoring → Keyword Volume: uses volume (evidence: `zens_ink/kgr_auto.py`)
- On-page Scoring → Technical and GEO Audit: reuses audit (evidence: `zens_ink/onpage_audit.py`)
- GSC Performance → Google Search Console: queries analytics (evidence: `zens_ink/search_performance.py`)
- GSC OAuth Setup → Google Search Console: sets up OAuth (evidence: `README.md`)
- GSC Performance → Shared Configuration: reads settings (evidence: `zens_ink/search_performance.py`)
- Keyword Volume → Shared Configuration: reads settings (evidence: `zens_ink/keyword_volume.py`)
- Keyword Difficulty → Shared Configuration: reads settings (evidence: `zens_ink/kd.py`)
- MCP Clients → MCP Server: connects via stdio (evidence: `README.md`)
- MCP Server → Keyword Research: dispatches tool (evidence: `README.md`)
- MCP Server → Keyword Difficulty: dispatches tool (evidence: `README.md`)
- MCP Server → Technical and GEO Audit: dispatches tool (evidence: `README.md`)