# badis1996/seo-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/badis1996/seo-ai-agent
- Repository: https://github.com/badis1996/seo-ai-agent

## Overview

Asendia AI SEO Agent turns command-line requests into keyword clusters, competitor gap analyses, SEO content outlines, and weekly opportunity reports. The main entry point dispatches to the domain modules and reporting; a separate scheduler invokes the opportunity command weekly. The modules use free-alternative research clients, with keyword and competitor analysis also referencing shared text processing. Local ranking history is persisted by the opportunity tracker. Edges reflect the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`main.py`](https://github.com/badis1996/seo-ai-agent/blob/main/main.py) (Command dispatcher), [`utils/api_clients.py`](https://github.com/badis1996/seo-ai-agent/blob/main/utils/api_clients.py) (Research clients), [`modules/keyword_clustering.py`](https://github.com/badis1996/seo-ai-agent/blob/main/modules/keyword_clustering.py) (Keyword clustering), [`modules/competitor_audit.py`](https://github.com/badis1996/seo-ai-agent/blob/main/modules/competitor_audit.py) (Competitor audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_main["Command dispatcher<br/>[main.py]"]
  node_weekly_scheduler["Weekly scheduler<br/>[schedule_weekly.py]"]
  node_config["SEO settings<br/>[config.py]"]
end

subgraph group_research["SEO Research"]
  node_keyword_clustering["Keyword clustering"]
  node_competitor_audit["Competitor audit"]
  node_opportunity_tracker["Opportunity tracking"]
  node_ranking_history["Ranking history"]
end

subgraph group_content["Content"]
  node_content_generator["Outline generation"]
end

subgraph group_shared["Shared Services"]
  node_api_clients["Research clients<br/>[api_clients.py]"]
  node_data_processing["Text processing<br/>[data_processing.py]"]
  node_reporting["SEO reports<br/>[reporting.py]"]
end

node_cli_user(("CLI user"))
node_search_trends(("Search and trends"))
node_openai(("OpenAI"))

node_cli_user -->|"runs command"| node_main
node_main -->|"reads settings"| node_config
node_main -->|"dispatches to"| node_keyword_clustering
node_main -->|"dispatches to"| node_competitor_audit
node_main -->|"dispatches to"| node_content_generator
node_main -->|"dispatches to"| node_opportunity_tracker
node_main -->|"creates reports"| node_reporting
node_weekly_scheduler -->|"runs opportunity"| node_main
node_keyword_clustering -->|"fetches research"| node_api_clients
node_keyword_clustering -->|"uses processing"| node_data_processing
node_competitor_audit -->|"fetches research"| node_api_clients
node_competitor_audit -->|"uses processing"| node_data_processing
node_opportunity_tracker -->|"fetches trends"| node_api_clients
node_content_generator -->|"queries SERPs"| node_api_clients
node_content_generator -->|"requests outlines"| node_openai
node_api_clients -.->|"queries research"| node_search_trends
node_opportunity_tracker -->|"reads and writes"| node_ranking_history

click node_main "https://github.com/badis1996/seo-ai-agent/blob/main/main.py"
click node_weekly_scheduler "https://github.com/badis1996/seo-ai-agent/blob/main/schedule_weekly.py"
click node_config "https://github.com/badis1996/seo-ai-agent/blob/main/config.py"
click node_keyword_clustering "https://github.com/badis1996/seo-ai-agent/blob/main/modules/keyword_clustering.py"
click node_competitor_audit "https://github.com/badis1996/seo-ai-agent/blob/main/modules/competitor_audit.py"
click node_opportunity_tracker "https://github.com/badis1996/seo-ai-agent/blob/main/modules/opportunity_tracker.py"
click node_content_generator "https://github.com/badis1996/seo-ai-agent/blob/main/modules/content_generator.py"
click node_api_clients "https://github.com/badis1996/seo-ai-agent/blob/main/utils/api_clients.py"
click node_data_processing "https://github.com/badis1996/seo-ai-agent/blob/main/utils/data_processing.py"
click node_reporting "https://github.com/badis1996/seo-ai-agent/blob/main/utils/reporting.py"
click node_ranking_history "https://github.com/badis1996/seo-ai-agent/blob/main/modules/opportunity_tracker.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_main,node_weekly_scheduler,node_config,node_cli_user toneBlue
class node_keyword_clustering,node_competitor_audit,node_opportunity_tracker,node_ranking_history toneAmber
class node_content_generator toneMint
class node_api_clients,node_data_processing,node_reporting toneRose
class node_search_trends,node_openai toneIndigo
```

## Components

### Orchestration

- [Command dispatcher](https://github.com/badis1996/seo-ai-agent/blob/main/main.py): `main.py`
- [Weekly scheduler](https://github.com/badis1996/seo-ai-agent/blob/main/schedule_weekly.py): `schedule_weekly.py`
- [SEO settings](https://github.com/badis1996/seo-ai-agent/blob/main/config.py): `config.py`

### SEO Research

- [Keyword clustering](https://github.com/badis1996/seo-ai-agent/blob/main/modules/keyword_clustering.py): `modules/keyword_clustering.py`
- [Competitor audit](https://github.com/badis1996/seo-ai-agent/blob/main/modules/competitor_audit.py): `modules/competitor_audit.py`
- [Opportunity tracking](https://github.com/badis1996/seo-ai-agent/blob/main/modules/opportunity_tracker.py): `modules/opportunity_tracker.py`
- [Ranking history](https://github.com/badis1996/seo-ai-agent/blob/main/modules/opportunity_tracker.py): `modules/opportunity_tracker.py`

### Content

- [Outline generation](https://github.com/badis1996/seo-ai-agent/blob/main/modules/content_generator.py): `modules/content_generator.py`

### Shared Services

- [Research clients](https://github.com/badis1996/seo-ai-agent/blob/main/utils/api_clients.py): `utils/api_clients.py`
- [Text processing](https://github.com/badis1996/seo-ai-agent/blob/main/utils/data_processing.py): `utils/data_processing.py`
- [SEO reports](https://github.com/badis1996/seo-ai-agent/blob/main/utils/reporting.py): `utils/reporting.py`

### Other components

- **CLI user**
- **Search and trends**
- **OpenAI**

## Connections

- CLI user → Command dispatcher: runs command (evidence: `README.md`)
- Command dispatcher → SEO settings: reads settings (evidence: `main.py`)
- Command dispatcher → Keyword clustering: dispatches to (evidence: `main.py`)
- Command dispatcher → Competitor audit: dispatches to (evidence: `main.py`)
- Command dispatcher → Outline generation: dispatches to (evidence: `main.py`)
- Command dispatcher → Opportunity tracking: dispatches to (evidence: `main.py`)
- Command dispatcher → SEO reports: creates reports (evidence: `main.py`)
- Weekly scheduler → Command dispatcher: runs opportunity (evidence: `schedule_weekly.py`)
- Keyword clustering → Research clients: fetches research (evidence: `modules/keyword_clustering.py`)
- Keyword clustering → Text processing: uses processing (evidence: `modules/keyword_clustering.py`)
- Competitor audit → Research clients: fetches research (evidence: `modules/competitor_audit.py`)
- Competitor audit → Text processing: uses processing (evidence: `modules/competitor_audit.py`)
- Opportunity tracking → Research clients: fetches trends (evidence: `modules/opportunity_tracker.py`)
- Outline generation → Research clients: queries SERPs (evidence: `modules/content_generator.py`)
- Outline generation → OpenAI: requests outlines (evidence: `modules/content_generator.py`)
- Research clients → Search and trends: queries research (evidence: `README.md`)
- Opportunity tracking → Ranking history: reads and writes (evidence: `modules/opportunity_tracker.py`)