# allanreda/seo-keyword-cannibalization-detector architecture

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

- Interactive diagram: https://gitdiagram.com/allanreda/seo-keyword-cannibalization-detector
- Repository: https://github.com/allanreda/seo-keyword-cannibalization-detector

## Overview

This is a single-file SEO analysis script. Its main workflow imports a URL list, retrieves Google Search Console keyword metrics for those URLs, fetches and processes page HTML, identifies keywords ranking on multiple URLs, aggregates performance, and exports the results to Excel. The README documents URL cleanup and Excel output; the sampled source confirms API access, HTML processing, and aggregation, but not the omitted cleanup and export implementations.

Main entry points: [`keyword_cannibalization.py`](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py) (Analysis workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and access"]
  node_url_workbook["URL workbook"]
  node_script_workflow["Analysis workflow"]
  node_gsc_auth["GSC authentication"]
  node_gsc_api["Search Console API"]
  node_url_filters["Page URL filters"]
end

subgraph group_analysis["Page and keyword analysis"]
  node_keyword_fetch["Keyword data fetch"]
  node_keyword_rows["Keyword metrics"]
  node_page_fetch["Page HTML fetch"]
  node_website["Website pages"]
  node_html_extract["Visible text extraction"]
  node_link_extract["Page link extraction"]
end

subgraph group_results["Cannibalization results"]
  node_keyword_aggregation["Keyword aggregation"]
  node_cannibalization_results["Cannibalization results"]
  node_results_workbook["Results workbook"]
end

node_seo_specialist(("SEO specialist"))

node_seo_specialist -->|"runs"| node_script_workflow
node_url_workbook -->|"provides URLs"| node_script_workflow
node_script_workflow -->|"obtains credentials"| node_gsc_auth
node_gsc_auth -->|"authorizes access"| node_gsc_api
node_script_workflow -->|"builds filters"| node_url_filters
node_url_filters -->|"selects pages"| node_keyword_fetch
node_keyword_fetch -->|"queries metrics"| node_gsc_api
node_keyword_fetch -->|"returns rows"| node_keyword_rows
node_script_workflow -->|"fetches pages"| node_page_fetch
node_page_fetch -->|"requests HTML"| node_website
node_page_fetch -->|"passes HTML"| node_html_extract
node_html_extract -->|"extracts links"| node_link_extract
node_script_workflow -->|"groups keyword rows"| node_keyword_aggregation
node_keyword_rows -->|"provides metrics"| node_keyword_aggregation
node_keyword_aggregation -->|"identifies overlaps"| node_cannibalization_results
node_script_workflow -->|"exports results"| node_results_workbook
node_cannibalization_results -->|"provides results"| node_results_workbook
node_results_workbook -->|"delivers report"| node_seo_specialist

click node_script_workflow "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_gsc_auth "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_url_filters "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_keyword_fetch "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_keyword_rows "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_page_fetch "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_html_extract "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_link_extract "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_keyword_aggregation "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py"
click node_cannibalization_results "https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.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_url_workbook,node_script_workflow,node_gsc_auth,node_gsc_api,node_url_filters toneBlue
class node_keyword_fetch,node_keyword_rows,node_page_fetch,node_website,node_html_extract,node_link_extract toneAmber
class node_keyword_aggregation,node_cannibalization_results,node_results_workbook toneMint
class node_seo_specialist toneIndigo
```

## Components

### Inputs and access

- **URL workbook**
- [Analysis workflow](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- [GSC authentication](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- **Search Console API**
- [Page URL filters](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`

### Page and keyword analysis

- [Keyword data fetch](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- [Keyword metrics](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- [Page HTML fetch](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- **Website pages**
- [Visible text extraction](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- [Page link extraction](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`

### Cannibalization results

- [Keyword aggregation](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- [Cannibalization results](https://github.com/allanreda/seo-keyword-cannibalization-detector/blob/main/keyword_cannibalization.py): `keyword_cannibalization.py`
- **Results workbook**

### Other components

- **SEO specialist**

## Connections

- SEO specialist → Analysis workflow: runs
- URL workbook → Analysis workflow: provides URLs
- Analysis workflow → GSC authentication: obtains credentials
- GSC authentication → Search Console API: authorizes access
- Analysis workflow → Page URL filters: builds filters
- Page URL filters → Keyword data fetch: selects pages
- Keyword data fetch → Search Console API: queries metrics
- Keyword data fetch → Keyword metrics: returns rows
- Analysis workflow → Page HTML fetch: fetches pages
- Page HTML fetch → Website pages: requests HTML
- Page HTML fetch → Visible text extraction: passes HTML
- Visible text extraction → Page link extraction: extracts links
- Analysis workflow → Keyword aggregation: groups keyword rows
- Keyword metrics → Keyword aggregation: provides metrics
- Keyword aggregation → Cannibalization results: identifies overlaps
- Analysis workflow → Results workbook: exports results
- Cannibalization results → Results workbook: provides results
- Results workbook → SEO specialist: delivers report