# adtechthai/narastainless-seo architecture

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

- Interactive diagram: https://gitdiagram.com/adtechthai/narastainless-seo
- Repository: https://github.com/adtechthai/narastainless-seo

## Overview

This repository is an SEO analysis and content-planning package for narastainless.com, not a general-purpose application. Its main workflow turns Ahrefs exports and search-performance data into recovery and competitor analyses, keyword clusters, and client-facing dashboards and reports; a parallel editorial workflow organizes research and article deliverables. The README documents the high-level raw-to-processed-to-output flow. Script excerpts show several dashboard and report transformations, but do not establish every data handoff, so unsampled connections are omitted.

Main entry points: [`02_processed_data`](https://github.com/adtechthai/narastainless-seo/tree/main/02_processed_data) (Processed data), [`04_scripts/build_dashboard_v2.py`](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_dashboard_v2.py) (Dashboard builder), [`05_articles/_research`](https://github.com/adtechthai/narastainless-seo/tree/main/05_articles/_research) (Research dossiers), [`04_scripts/build_report_2026_08.py`](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_report_2026_08.py) (Monthly report builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["SEO analysis"]
  node_rebuild["Keyword filtering<br/>[rebuild_data.py]"]
  node_cluster_defs["Keyword clusters"]
  node_competitor_analysis["Competitor analysis"]
  node_keyword_analysis["Keyword analysis"]
  node_serp["SERP research<br/>[fetch_serp.py]"]
  node_competitor_data["Competitor table"]
end

subgraph group_dashboard["Dashboards and reports"]
  node_dashboard_source["SEO dashboard"]
  node_dashboard_v2["Dashboard builder"]
  node_dashboard_out["SEO dashboards"]
  node_competitor_page["Competitor page"]
  node_competitor_html["Competitor report"]
  node_technical_page["Technical audit"]
  node_report_builder["Monthly report builder"]
  node_report_data["Report data"]
  node_reports["SEO deliverables"]
end

subgraph group_editorial["Editorial planning"]
  node_articles["Article drafts"]
  node_research["Research dossiers"]
  node_research_split["Research splitter<br/>[split_research.py]"]
end

subgraph group_inputs["SEO data"]
  node_raw[("Ahrefs exports")]
  node_processed[("Processed data")]
  node_serp_results[("SERP results<br/>[serp_results.json]")]
end

node_analyst(("SEO analyst"))

node_analyst -->|"provides exports"| node_raw
node_raw -->|"processes data"| node_processed
node_analyst -->|"rebuilds keywords"| node_rebuild
node_rebuild -->|"creates filtered data"| node_processed
node_analyst -->|"analyzes recovery"| node_competitor_analysis
node_competitor_analysis -->|"generates recovery data"| node_processed
node_analyst -->|"plans content"| node_cluster_defs
node_cluster_defs -->|"supplies clusters"| node_dashboard_v2
node_dashboard_source -->|"provides GSC data"| node_dashboard_v2
node_processed -->|"provides GA4 data"| node_dashboard_v2
node_dashboard_v2 -->|"builds dashboard"| node_dashboard_out
node_processed -->|"reads competitor exports"| node_competitor_data
node_competitor_data -->|"feeds competitor view"| node_competitor_page
node_processed -->|"reads recovery data"| node_competitor_html
node_competitor_html -->|"builds competitor report"| node_dashboard_out
node_processed -->|"reads audit data"| node_technical_page
node_report_builder -->|"generates report data"| node_report_data
node_analyst -->|"creates research"| node_research
node_research -->|"guides article drafts"| node_articles
node_research_split -->|"writes dossiers"| node_research
node_analyst -->|"reviews deliverables"| node_reports
node_report_builder -.->|"produces analysis"| node_reports

click node_raw "https://github.com/adtechthai/narastainless-seo/tree/main/01_raw_data"
click node_processed "https://github.com/adtechthai/narastainless-seo/tree/main/02_processed_data"
click node_rebuild "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/rebuild_data.py"
click node_cluster_defs "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/cluster_definitions.py"
click node_competitor_analysis "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/analyze_competitors.py"
click node_keyword_analysis "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/analyze_competitor_keywords.py"
click node_serp "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/fetch_serp.py"
click node_serp_results "https://github.com/adtechthai/narastainless-seo/blob/main/02_processed_data/serp_results.json"
click node_dashboard_source "https://github.com/adtechthai/narastainless-seo/blob/main/narastainless_seo_dashboard.html"
click node_dashboard_v2 "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_dashboard_v2.py"
click node_dashboard_out "https://github.com/adtechthai/narastainless-seo/tree/main/03_outputs"
click node_competitor_data "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_competitor_traffic_data.py"
click node_competitor_page "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/add_competitor_page.py"
click node_competitor_html "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_competitor_html.py"
click node_technical_page "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/add_technical_audit_page.py"
click node_report_builder "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_report_2026_08.py"
click node_report_data "https://github.com/adtechthai/narastainless-seo/blob/main/03_outputs/report-2026-08.data.js"
click node_articles "https://github.com/adtechthai/narastainless-seo/tree/main/05_articles"
click node_research "https://github.com/adtechthai/narastainless-seo/tree/main/05_articles/_research"
click node_research_split "https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/split_research.py"
click node_reports "https://github.com/adtechthai/narastainless-seo/blob/main/03_outputs/narastainless_seo_analysis.xlsx"

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_rebuild,node_cluster_defs,node_competitor_analysis,node_keyword_analysis,node_serp,node_competitor_data toneBlue
class node_dashboard_source,node_dashboard_v2,node_dashboard_out,node_competitor_page,node_competitor_html,node_technical_page,node_report_builder,node_report_data,node_reports toneAmber
class node_articles,node_research,node_research_split toneMint
class node_raw,node_processed,node_serp_results toneRose
class node_analyst toneIndigo
```

## Components

### SEO analysis

- [Keyword filtering](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/rebuild_data.py): `04_scripts/rebuild_data.py`
- [Keyword clusters](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/cluster_definitions.py): `04_scripts/cluster_definitions.py`
- [Competitor analysis](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/analyze_competitors.py): `04_scripts/analyze_competitors.py`
- [Keyword analysis](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/analyze_competitor_keywords.py): `04_scripts/analyze_competitor_keywords.py`
- [SERP research](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/fetch_serp.py): `04_scripts/fetch_serp.py`
- [Competitor table](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_competitor_traffic_data.py): `04_scripts/build_competitor_traffic_data.py`

### Dashboards and reports

- [SEO dashboard](https://github.com/adtechthai/narastainless-seo/blob/main/narastainless_seo_dashboard.html): `narastainless_seo_dashboard.html`
- [Dashboard builder](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_dashboard_v2.py): `04_scripts/build_dashboard_v2.py`
- [SEO dashboards](https://github.com/adtechthai/narastainless-seo/tree/main/03_outputs): `03_outputs`
- [Competitor page](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/add_competitor_page.py): `04_scripts/add_competitor_page.py`
- [Competitor report](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_competitor_html.py): `04_scripts/build_competitor_html.py`
- [Technical audit](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/add_technical_audit_page.py): `04_scripts/add_technical_audit_page.py`
- [Monthly report builder](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/build_report_2026_08.py): `04_scripts/build_report_2026_08.py`
- [Report data](https://github.com/adtechthai/narastainless-seo/blob/main/03_outputs/report-2026-08.data.js): `03_outputs/report-2026-08.data.js`
- [SEO deliverables](https://github.com/adtechthai/narastainless-seo/blob/main/03_outputs/narastainless_seo_analysis.xlsx): `03_outputs/narastainless_seo_analysis.xlsx`

### Editorial planning

- [Article drafts](https://github.com/adtechthai/narastainless-seo/tree/main/05_articles): `05_articles`
- [Research dossiers](https://github.com/adtechthai/narastainless-seo/tree/main/05_articles/_research): `05_articles/_research`
- [Research splitter](https://github.com/adtechthai/narastainless-seo/blob/main/04_scripts/split_research.py): `04_scripts/split_research.py`

### SEO data

- [Ahrefs exports](https://github.com/adtechthai/narastainless-seo/tree/main/01_raw_data): `01_raw_data`
- [Processed data](https://github.com/adtechthai/narastainless-seo/tree/main/02_processed_data): `02_processed_data`
- [SERP results](https://github.com/adtechthai/narastainless-seo/blob/main/02_processed_data/serp_results.json): `02_processed_data/serp_results.json`

### Other components

- **SEO analyst**

## Connections

- SEO analyst → Ahrefs exports: provides exports (evidence: `README.md`)
- Ahrefs exports → Processed data: processes data (evidence: `README.md`)
- SEO analyst → Keyword filtering: rebuilds keywords (evidence: `README.md`)
- Keyword filtering → Processed data: creates filtered data (evidence: `README.md`)
- SEO analyst → Competitor analysis: analyzes recovery (evidence: `README.md`)
- Competitor analysis → Processed data: generates recovery data (evidence: `README.md`)
- SEO analyst → Keyword clusters: plans content (evidence: `README.md`)
- Keyword clusters → Dashboard builder: supplies clusters (evidence: `04_scripts/build_dashboard_v2.py`)
- SEO dashboard → Dashboard builder: provides GSC data (evidence: `04_scripts/build_dashboard_v2.py`)
- Processed data → Dashboard builder: provides GA4 data (evidence: `04_scripts/build_dashboard_v2.py`)
- Dashboard builder → SEO dashboards: builds dashboard (evidence: `04_scripts/build_dashboard_v2.py`)
- Processed data → Competitor table: reads competitor exports (evidence: `04_scripts/build_competitor_traffic_data.py`)
- Competitor table → Competitor page: feeds competitor view (evidence: `04_scripts/add_competitor_page.py`)
- Processed data → Competitor report: reads recovery data (evidence: `04_scripts/build_competitor_html.py`)
- Competitor report → SEO dashboards: builds competitor report (evidence: `04_scripts/build_competitor_html.py`)
- Processed data → Technical audit: reads audit data (evidence: `04_scripts/add_technical_audit_page.py`)
- Monthly report builder → Report data: generates report data (evidence: `03_outputs/report-2026-08.data.js`)
- SEO analyst → Research dossiers: creates research (evidence: `README.md`)
- Research dossiers → Article drafts: guides article drafts (evidence: `README.md`)
- Research splitter → Research dossiers: writes dossiers (evidence: `04_scripts/split_research.py`)
- SEO analyst → SEO deliverables: reviews deliverables (evidence: `README.md`)
- Monthly report builder → SEO deliverables: produces analysis
